@venn-lang/runtime 0.1.0

package/src/scheduler/pending.types.ts

@@ -0,0 +1,9 @@
+/**
+ * What a statement leaves behind: nothing, or work still in flight.
+ *
+ * Most statements are pure evaluation (a `let`, a `return`, a comparison) and an
+ * `async` handler would wrap each one in a promise and a microtask. Returning
+ * `undefined` when there is nothing to await lets the caller skip that, which is
+ * what keeps a loop over 50k items from paying five promises an iteration.
+ */
+export type Pending = void | Promise<void>;

package/src/scheduler/run-action.ts

@@ -0,0 +1,163 @@
+import { ConsolePort, VennError } from "@venn-lang/contracts";
+import {
+  type ActionCall,
+  type AstNode,
+  callArgs,
+  display,
+  evaluate,
+  invoke,
+  splitCall,
+} from "@venn-lang/core";
+import type { ActionDefinition, ActionInput } from "@venn-lang/sdk";
+import type { Scope } from "../scope/index.js";
+import { callParams } from "./call-params.js";
+import { takes } from "./declared-arity.js";
+import type { Engine } from "./engine.types.js";
+import type { Invocation } from "./invocation.js";
+import { localCallee } from "./local-call.js";
+import { settle } from "./settled.js";
+import { ExitSignal } from "./signals.js";
+import { PRELUDE, resolveTarget } from "./target.js";
+
+/**
+ * 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.
+ */
+export async function runAction(engine: Engine, call: Invocation, scope: Scope): Promise<unknown> {
+  if (PRELUDE.has(call.target)) return runPrelude(engine, call, scope);
+  // `conn.close()` is a method on something the program holds. A name it bound
+  // beats a namespace of the same name, so this is asked first.
+  const callee = localCallee(call.target, scope);
+  if (callee !== undefined) 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: unknown, call: Invocation, scope: Scope): Promise<unknown> {
+  const values = await Promise.all(call.args.map((expr) => settle(evaluate(expr, scope))));
+  return settle(invoke(callee, values));
+}
+
+/**
+ * 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.
+ */
+export async function runActionStatement(
+  engine: Engine,
+  call: ActionCall,
+  scope: Scope,
+): Promise<void> {
+  await runAction(engine, { ...call, args: callArgs(call) }, scope);
+}
+
+async function buildInput(args: {
+  action: ActionDefinition;
+  call: Invocation;
+  scope: Scope;
+  uri: string;
+}): Promise<ActionInput<unknown>> {
+  // The trailing `{ … }` is the options in both spellings, but only the bareword
+  // one puts it where the parser can label it. Splitting by declared arity is
+  // what stops `http.get(url, { headers })` sending no headers at all.
+  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;
+  const site = siteOf(args.call);
+  return {
+    args: positional,
+    params: callParams({ schema, opts, raw, site, 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: Invocation): AstNode {
+  return call.node ?? (call as unknown as AstNode);
+}
+
+function unknownAction(target: string): VennError {
+  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: Engine, call: Invocation, scope: Scope): Promise<void> {
+  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: Engine, args: readonly unknown[]): void {
+  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: Engine, args: readonly unknown[]): void {
+  engine.emitter.emit({ kind: "log", data: { level: "info", message: line(args) } });
+}
+
+function line(args: readonly unknown[]): string {
+  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: unknown): number {
+  const code = Math.trunc(Number(value ?? 0));
+  return Number.isFinite(code) ? code : 1;
+}
+
+function skipLog(engine: Engine, message: string): void {
+  engine.emitter.emit({ kind: "log", data: { level: "warn", message: `skipped: ${message}` } });
+}
+
+function waitMs(value: unknown): number {
+  if (typeof value === "number") return value;
+  const duration = value as { kind?: string; ms?: number };
+  return duration?.kind === "duration" ? (duration.ms ?? 0) : 0;
+}
+
+function failError(message: string): VennError {
+  return new VennError({ code: "VN6002", message: message || "fail" });
+}

package/src/scheduler/run-around.ts

@@ -0,0 +1,23 @@
+import { invoke, readDecorations } from "@venn-lang/core";
+
+/**
+ * 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.
+ */
+export async function runAround(node: object, body: () => unknown): Promise<void> {
+  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, []);
+  }
+}

package/src/scheduler/run-attempts.ts

@@ -0,0 +1,105 @@
+import { VennError } from "@venn-lang/contracts";
+import type { Annotation } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { type RetrySpec, readRetry, readTimeout } from "./annotations.js";
+import type { Engine } from "./engine.types.js";
+import { isControlSignal } from "./signals.js";
+
+interface AnnotatedNode {
+  annotations: Annotation[];
+}
+
+/** Run a step/flow body applying its `@timeout` and `@retry` annotations. */
+export async function runWithAnnotations(args: {
+  engine: Engine;
+  node: AnnotatedNode;
+  scope: Scope;
+  title: string;
+  run: () => Promise<void>;
+}): Promise<void> {
+  const timeout = readTimeout(args.node);
+  const retry = readRetry(args.node);
+  const attempt = (): Promise<void> => 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. */
+export async function withLock(
+  engine: Engine,
+  name: string | undefined,
+  run: () => Promise<void>,
+): Promise<void> {
+  if (!name) return run();
+  const release = await engine.lock.acquire(name);
+  try {
+    await run();
+  } finally {
+    release();
+  }
+}
+
+async function withTimeout(timeoutMs: number | undefined, run: () => Promise<void>): Promise<void> {
+  if (timeoutMs === undefined) return run();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const guard = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(timeoutError(timeoutMs)), timeoutMs);
+  });
+  try {
+    await Promise.race([run(), guard]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function withRetry(args: {
+  engine: Engine;
+  retry: RetrySpec;
+  title: string;
+  run: () => Promise<void>;
+}): Promise<void> {
+  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));
+  }
+}
+
+interface AttemptOutcome {
+  ok: boolean;
+  error?: unknown;
+}
+
+async function attempt(engine: Engine, run: () => Promise<void>): Promise<AttemptOutcome> {
+  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: { engine: Engine; title: string; attempt: number }): void {
+  args.engine.emitter.emit({
+    kind: "flow.retrying",
+    data: { title: args.title, attempt: args.attempt, reason: "previous attempt failed" },
+  });
+}
+
+function backoff(retry: RetrySpec, attempt: number): number {
+  return retry.backoffMs * retry.factor ** (attempt - 1);
+}
+
+function timeoutError(ms: number): VennError {
+  return new VennError({ code: "VN8001", message: `Timed out after ${ms}ms.` });
+}

package/src/scheduler/run-bindings.ts

@@ -0,0 +1,67 @@
+import {
+  type CaptureStmt,
+  evaluate,
+  isNamespaceValue,
+  type LetStmt,
+  type ReturnStmt,
+} from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { actionCall, type Invocation, invocationOf } from "./invocation.js";
+import type { Pending } from "./pending.types.js";
+import { runAction } from "./run-action.js";
+import { isPending } from "./settled.js";
+import { ReturnSignal } from "./signals.js";
+import { resolveTarget } from "./target.js";
+
+/**
+ * `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.
+ */
+export function runLet(engine: Engine, stmt: LetStmt, scope: Scope): Pending {
+  const call = invocationOf(stmt) ?? impliedCall(engine, stmt, scope);
+  // Only a call suspends. Binding a plain expression is the common case, and
+  // an `async` here would cost a promise per iteration of every loop.
+  if (!call) return bind(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: Engine, stmt: LetStmt, scope: Scope): Invocation | undefined {
+  const call = actionCall(stmt.value);
+  const dot = call ? call.target.indexOf(".") : -1;
+  if (!call || dot < 0 || bound(scope, call.target.slice(0, dot))) return undefined;
+  const resolved = engine.registry.action(resolveTarget(call.target, engine.aliases));
+  return resolved ? { target: call.target, args: call.args, node: stmt } : undefined;
+}
+
+/** A name the user bound. A plugin namespace in scope is not one, so the verb still calls. */
+function bound(scope: Scope, name: string): boolean {
+  const value = scope.lookup(name);
+  return value !== undefined && !isNamespaceValue(value);
+}
+
+/** Bind now, or once the value it is waiting on arrives. */
+function bind(name: string, value: unknown, scope: Scope): Pending {
+  if (isPending(value)) return value.then((settled) => scope.set(name, settled));
+  return void scope.set(name, value);
+}
+
+/** `capture` is removed in favour of `let`; still run, so old files keep working. */
+export function runCapture(stmt: CaptureStmt, scope: Scope): void {
+  scope.set(stmt.name, evaluate(stmt.value, scope));
+}
+
+/** `return expr`: unwind to the enclosing fragment with the value. */
+export function runReturn(stmt: ReturnStmt, scope: Scope): never {
+  const value = stmt.value ? evaluate(stmt.value, scope) : undefined;
+  throw new ReturnSignal(value);
+}

package/src/scheduler/run-block.ts

@@ -0,0 +1,65 @@
+import { type Block, isLifecycleDecl, type LifecycleDecl, type Statement } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { type BlockPlan, planOf, type Step } from "./block-plan.js";
+import type { Engine } from "./engine.types.js";
+import type { Pending } from "./pending.types.js";
+import { runStatement } from "./run-statements.js";
+import { CancelSignal } from "./signals.js";
+
+/**
+ * Run a block's statements in order, running any `defer { … }` bodies LIFO on
+ * the way out, including on error or a control-flow signal.
+ */
+export function runBlock(engine: Engine, block: Block, scope: Scope): Pending {
+  const plan = planOf(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. */
+export function runSteps(engine: Engine, steps: readonly Step[], scope: Scope): Pending {
+  for (let at = 0; at < steps.length; at += 1) {
+    if (engine.signal?.aborted) throw new CancelSignal();
+    const pending = (steps[at] as Step)(engine, scope);
+    if (pending) return resume(engine, steps, at + 1, scope, pending);
+  }
+  return undefined;
+}
+
+async function resume(
+  engine: Engine,
+  steps: readonly Step[],
+  from: number,
+  scope: Scope,
+  pending: Promise<void>,
+): Promise<void> {
+  await pending;
+  for (let at = from; at < steps.length; at += 1) {
+    if (engine.signal?.aborted) throw new CancelSignal();
+    const next = (steps[at] as Step)(engine, scope);
+    if (next) await next;
+  }
+}
+
+async function withDefers(engine: Engine, block: Block, scope: Scope): Promise<void> {
+  const defers: Block[] = [];
+  try {
+    for (const stmt of block.stmts) {
+      if (isDefer(stmt)) {
+        defers.unshift(stmt.body);
+        continue;
+      }
+      const pending = runStatement(engine, stmt, scope);
+      if (pending) await pending;
+    }
+  } finally {
+    const cleanup: Engine = { ...engine, signal: undefined };
+    for (const body of defers) await runBlock(cleanup, body, scope.child());
+  }
+}
+
+function isDefer(stmt: Statement): stmt is LifecycleDecl {
+  return isLifecycleDecl(stmt) && stmt.hook === "defer";
+}
+
+export type { BlockPlan };

package/src/scheduler/run-document.ts

@@ -0,0 +1,181 @@
+import {
+  type Document,
+  evaluate,
+  type FlowDecl,
+  isFlowDecl,
+  isMatrixDecl,
+  isStepDecl,
+  type PlannedStep,
+  type RunPlan,
+} from "@venn-lang/core";
+import { createScope, type Scope } from "../scope/index.js";
+import { absorbExit } from "./absorb-exit.js";
+import { hasAnnotation, readTags } from "./annotations.js";
+import { createBaseScope } from "./base-scope.js";
+import { bindGlobals } from "./bind-globals.js";
+import { bindImports } from "./bind-imports.js";
+import { collectHooks, type SuiteHooks } from "./collect.js";
+import type { Engine } from "./engine.types.js";
+import { matchesTitle } from "./filter.js";
+import { settleFlaky } from "./flaky.js";
+import { runFlow } from "./run-flow.js";
+import { runHooks } from "./run-lifecycle.js";
+import { runPrologue, runTeardowns } from "./run-prologue.js";
+
+/**
+ * Walk a document: setup once, then for each `matrix` variant bind `env`/`matrix`
+ * globals, open resources, run flows (with before/afterEach), close resources.
+ */
+export async function runDocument(engine: Engine, doc: Document): Promise<void> {
+  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: {
+  engine: Engine;
+  doc: Document;
+  flows: readonly FlowDecl[];
+  hooks: SuiteHooks;
+}): Promise<void> {
+  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: {
+  engine: Engine;
+  doc: Document;
+  flows: readonly FlowDecl[];
+  hooks: SuiteHooks;
+}): Promise<void> {
+  for (const variant of matrixVariants(args.engine, args.doc)) {
+    await runVariant({ ...args, variant });
+  }
+}
+
+async function runVariant(args: {
+  engine: Engine;
+  doc: Document;
+  flows: readonly FlowDecl[];
+  hooks: SuiteHooks;
+  variant: Record<string, unknown>;
+}): Promise<void> {
+  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 {
+    // Whatever ends the pass, a failure or an `exit` on its way out of the run,
+    // the suite still gives back what it opened.
+    await runTeardowns(teardowns);
+  }
+}
+
+async function runFlows(args: {
+  engine: Engine;
+  flows: readonly FlowDecl[];
+  hooks: SuiteHooks;
+  root: Scope;
+}): Promise<void> {
+  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: {
+  engine: Engine;
+  flow: FlowDecl;
+  hooks: SuiteHooks;
+  root: Scope;
+}): Promise<void> {
+  // A scope of its own, so what `beforeEach` opens dies with the flow that
+  // needed it rather than lingering into the next one.
+  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: {
+  engine: Engine;
+  doc: Document;
+  variant: Record<string, unknown>;
+}): Scope {
+  const base = (): Scope => createBaseScope({ engine: args.engine, variant: args.variant });
+  const root = base();
+  const graph = args.engine.imports;
+  // Before the document's own globals, so a local name of the same spelling
+  // wins. That is the rule fragments already follow.
+  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: Engine, doc: Document): Record<string, unknown>[] {
+  const matrix = doc.decls.find(isMatrixDecl);
+  if (!matrix) return [{}];
+  const scope = createScope();
+  scope.set("env", engine.env);
+  return product(evaluate(matrix.body, scope) as Record<string, unknown>);
+}
+
+function product(dims: Record<string, unknown>): Record<string, unknown>[] {
+  let combos: Record<string, unknown>[] = [{}];
+  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: Engine, flows: readonly FlowDecl[]): FlowDecl[] {
+  const only = flows.filter((flow) => hasAnnotation(flow, "only"));
+  const pool = only.length > 0 ? only : flows;
+  const kept = pool.filter((flow) => !hasAnnotation(flow, "skip"));
+  const named = kept.filter((flow) => matchesTitle(flow.title, engine.filter.flow));
+  return byTags(named, engine.filter.tags);
+}
+
+function byTags(flows: FlowDecl[], tags: readonly string[] | undefined): FlowDecl[] {
+  if (!tags || tags.length === 0) return flows;
+  return flows.filter((flow) => readTags(flow).some((tag) => tags.includes(tag)));
+}
+
+function planOf(flows: readonly FlowDecl[]): RunPlan {
+  return { flows: flows.map((flow) => ({ title: flow.title, steps: stepTitles(flow) })) };
+}
+
+function stepTitles(flow: FlowDecl): PlannedStep[] {
+  return flow.body.stmts.filter(isStepDecl).map((step) => ({ title: step.title }));
+}

package/src/scheduler/run-expect.ts

@@ -0,0 +1,48 @@
+import { buildProblem, CODES, type ExpectStmt, evaluate, truthy } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { nodeSource, nodeSpan } from "./node-span.js";
+import { evalMatcher, type MatcherOutcome } from "./run-matcher.js";
+import { settle } from "./settled.js";
+
+/** Evaluate an `expect` (matcher clause, `.all` checks, negated, or subject) and emit the outcome. */
+export async function runExpect(engine: Engine, stmt: ExpectStmt, scope: Scope): Promise<void> {
+  const outcome = stmt.matcher
+    ? await evalMatcher({ engine, stmt, scope })
+    : { passed: await evalBoolean({ stmt, scope }) };
+  record({ engine, stmt, outcome });
+}
+
+async function evalBoolean(args: { stmt: ExpectStmt; scope: Scope }): Promise<boolean> {
+  return args.stmt.modifier === "all" ? evalChecks(args) : evalSubject(args);
+}
+
+async function evalSubject(args: { stmt: ExpectStmt; scope: Scope }): Promise<boolean> {
+  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: { stmt: ExpectStmt; scope: Scope }): Promise<boolean> {
+  for (const check of args.stmt.checks) {
+    if (!truthy(await settle(evaluate(check, args.scope)))) return false;
+  }
+  return true;
+}
+
+function record(args: { engine: Engine; stmt: ExpectStmt; outcome: MatcherOutcome }): void {
+  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)}`,
+    // The title is one line; the two sides it summarises travel as the body.
+    diff: args.outcome.diff,
+  });
+  args.engine.emitter.emit({ kind: "expect.failed", data: { problem } });
+}