@venn-lang/runtime 0.1.0

package/src/scheduler/run-flow.ts

@@ -0,0 +1,69 @@
+import { type FlowDecl, isLifecycleDecl, type LifecycleDecl, ProblemError } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { hasAnnotation, readLock } from "./annotations.js";
+import type { Engine } from "./engine.types.js";
+import { recordFlaky } from "./flaky.js";
+import { runAround } from "./run-around.js";
+import { runWithAnnotations, withLock } from "./run-attempts.js";
+import { runBlock } from "./run-block.js";
+import { runOnHandlers } from "./run-lifecycle.js";
+import { ExitSignal, isControlSignal } from "./signals.js";
+
+/** Run a flow: body, then its `on failure`/`on success` handlers, then finish. */
+export async function runFlow(engine: Engine, flow: FlowDecl, scope: Scope): Promise<void> {
+  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";
+  const event = status === "failed" ? "failure" : "success";
+  await runOnHandlers({ engine, handlers, event, scope });
+  engine.emitter.emit({ kind: "flow.finished", data: { title: flow.title, status } });
+}
+
+async function runFlowBody(engine: Engine, flow: FlowDecl, scope: Scope): Promise<void> {
+  try {
+    await withLock(engine, flowLock(flow), () =>
+      runWithAnnotations({
+        engine,
+        node: flow,
+        scope,
+        title: flow.title,
+        // The caller wants a promise; a block that never suspended returns none.
+        run: () => runAround(flow, () => runBlock(engine, flow.body, scope)),
+      }),
+    );
+  } catch (error) {
+    // `break`/`return` end the flow and no more than that. `exit` is not the
+    // flow's to absorb: it ends the run, so it keeps unwinding.
+    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: FlowDecl): string | undefined {
+  return readLock(flow) ?? (hasAnnotation(flow, "serial") ? `serial:${flow.title}` : undefined);
+}
+
+function isOnHandler(stmt: unknown): stmt is LifecycleDecl {
+  return isLifecycleDecl(stmt) && Boolean((stmt as LifecycleDecl).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: Engine, error: unknown): void {
+  engine.result.failed += 1;
+  if (error instanceof ProblemError) {
+    engine.emitter.emit({ kind: "expect.failed", data: { problem: error.problem } });
+    return;
+  }
+  const message = (error as { message?: string })?.message ?? String(error);
+  engine.emitter.emit({ kind: "log", data: { level: "error", message } });
+}

package/src/scheduler/run-foreach.ts

@@ -0,0 +1,148 @@
+import {
+  buildProblem,
+  CODES,
+  evaluate,
+  type ForEachStmt,
+  ProblemError,
+  typeName,
+} from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { planOf } from "./block-plan.js";
+import { runPool } from "./concurrency.js";
+import type { Engine } from "./engine.types.js";
+import { nodeSpan } from "./node-span.js";
+import { optsNumber } from "./opts.js";
+import type { Pending } from "./pending.types.js";
+import { runBlock, runSteps } from "./run-block.js";
+import { settle } from "./settled.js";
+import { BreakSignal, ContinueSignal } from "./signals.js";
+
+/** `forEach x in list { concurrency: N } { … }`: iterate, up to N in flight. */
+export async function runForEach(engine: Engine, stmt: ForEachStmt, scope: Scope): Promise<void> {
+  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;
+  // One at a time is the default and by far the common case: run it as a plain
+  // loop rather than through the pool, which allocates a worker, an array and a
+  // `Promise.all` to supervise a single sequential walk.
+  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: { engine: Engine; stmt: ForEachStmt; source: unknown }): ProblemError {
+  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: unknown): string | undefined {
+  if (typeName(source) !== "map") return undefined;
+  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: Engine,
+  stmt: ForEachStmt,
+  items: readonly unknown[],
+  scope: Scope,
+): Pending {
+  const plan = planOf(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(engine, stmt, items, at + 1, scope, pending);
+    } catch (error) {
+      if (error instanceof BreakSignal) return undefined;
+      if (error instanceof ContinueSignal) continue;
+      throw error;
+    }
+  }
+  return undefined;
+}
+
+function slowSequential(
+  engine: Engine,
+  stmt: ForEachStmt,
+  items: readonly unknown[],
+  scope: Scope,
+): Pending {
+  for (let at = 0; at < items.length; at += 1) {
+    try {
+      const pending = iterate(engine, stmt, items[at], scope);
+      if (pending) return resume(engine, stmt, items, at + 1, scope, pending);
+    } catch (error) {
+      if (error instanceof BreakSignal) return undefined;
+      if (error instanceof ContinueSignal) continue;
+      throw error;
+    }
+  }
+  return undefined;
+}
+
+function iterate(engine: Engine, stmt: ForEachStmt, item: unknown, scope: Scope): Pending {
+  const child = scope.child();
+  child.set(stmt.item, item);
+  return runBlock(engine, stmt.body, child);
+}
+
+async function resume(
+  engine: Engine,
+  stmt: ForEachStmt,
+  items: readonly unknown[],
+  from: number,
+  scope: Scope,
+  pending: Promise<void>,
+): Promise<void> {
+  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: {
+  engine: Engine;
+  stmt: ForEachStmt;
+  item: unknown;
+  scope: Scope;
+}): Promise<void> {
+  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;
+  }
+}

package/src/scheduler/run-group.ts

@@ -0,0 +1,9 @@
+import type { GroupDecl } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { runBlock } from "./run-block.js";
+
+/** A group only clusters steps in the graph; it shares the enclosing scope. */
+export async function runGroup(engine: Engine, stmt: GroupDecl, scope: Scope): Promise<void> {
+  await runBlock(engine, stmt.body, scope);
+}

package/src/scheduler/run-if.ts

@@ -0,0 +1,21 @@
+import { evaluate, type IfStmt, isIfStmt, truthy } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import type { Pending } from "./pending.types.js";
+import { runBlock } from "./run-block.js";
+import { isPending } from "./settled.js";
+
+/** `if cond { … } else if … else { … }`: evaluate and run the taken branch. */
+export function runIf(engine: Engine, stmt: IfStmt, scope: Scope): Pending {
+  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: Engine, stmt: IfStmt, scope: Scope, yes: boolean): Pending {
+  if (yes) return runBlock(engine, stmt.then, scope.child());
+  const branch = stmt.otherwise;
+  if (!branch) return undefined;
+  if (isIfStmt(branch)) return runIf(engine, branch, scope);
+  return runBlock(engine, branch, scope.child());
+}

package/src/scheduler/run-lifecycle.ts

@@ -0,0 +1,86 @@
+import { buildProblem, CODES, type LifecycleDecl, type Problem } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { nodeSpan } from "./node-span.js";
+import { runBlock } from "./run-block.js";
+import { ExitSignal, isControlSignal } from "./signals.js";
+
+/**
+ * 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.
+ */
+export async function runHooks(args: {
+  engine: Engine;
+  hooks: readonly LifecycleDecl[];
+  scope: Scope;
+}): Promise<void> {
+  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.
+ */
+export async function runOnHandlers(args: {
+  engine: Engine;
+  handlers: readonly LifecycleDecl[];
+  event: string;
+  scope: Scope;
+}): Promise<void> {
+  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: Engine, hook: LifecycleDecl, scope: Scope): Promise<void> {
+  try {
+    await runBlock(engine, hook.body, scope.child());
+  } catch (error) {
+    // Read as a flow body reads it: `break`/`return` unwind, they do not fail.
+    // `exit` is not the hook's to absorb: it ends the run, and the code it
+    // carries is the whole verdict, so it keeps unwinding to whoever ends it.
+    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: { engine: Engine; hook: LifecycleDecl; error: unknown }): void {
+  args.engine.result.failed += 1;
+  args.engine.emitter.emit({ kind: "expect.failed", data: { problem: hookProblem(args) } });
+}
+
+function hookProblem(args: { engine: Engine; hook: LifecycleDecl; error: unknown }): Problem {
+  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: LifecycleDecl): string {
+  return hook.hook ?? (hook.event ? `on ${hook.event}` : "lifecycle");
+}
+
+function messageOf(error: unknown): string {
+  return (error as { message?: string })?.message ?? String(error);
+}

package/src/scheduler/run-matcher.ts

@@ -0,0 +1,99 @@
+import { VennError } from "@venn-lang/contracts";
+import {
+  buildDiff,
+  type Diff,
+  type ExpectStmt,
+  evaluate,
+  type MatcherClause,
+} from "@venn-lang/core";
+import type { MatcherArgs, MatcherDefinition } from "@venn-lang/sdk";
+import type { ResolvedMatcher } from "../registry/index.js";
+import type { Scope } from "../scope/index.js";
+import { callParams } from "./call-params.js";
+import type { Engine } from "./engine.types.js";
+import { nodeSource } from "./node-span.js";
+
+/** The pass/fail, the one-line message, and the diff that message summarises. */
+export interface MatcherOutcome {
+  passed: boolean;
+  message?: string;
+  diff?: Diff;
+}
+
+/** Resolve a bareword matcher from the registry and run it against the subject. */
+export async function evalMatcher(args: {
+  engine: Engine;
+  stmt: ExpectStmt;
+  scope: Scope;
+}): Promise<MatcherOutcome> {
+  const clause = args.stmt.matcher as MatcherClause;
+  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: {
+  matcher: MatcherDefinition;
+  input: MatcherArgs<unknown>;
+  stmt: ExpectStmt;
+}): MatcherOutcome {
+  const message = args.matcher.message(args.input);
+  const detail = args.stmt.negate ? undefined : args.matcher.detail?.(args.input);
+  if (!detail) return { passed: false, message };
+  const label = subjectLabel(args.stmt);
+  return { passed: false, message, diff: buildDiff({ label, ...detail }) };
+}
+
+/** The diff's header: the subject as the flow spelled it, on one line. */
+function subjectLabel(stmt: ExpectStmt): string {
+  const source = stmt.subject ? nodeSource(stmt.subject).replace(/\s+/g, " ").trim() : "";
+  return source === "" ? "value" : source;
+}
+
+function buildArgs(args: {
+  resolved: ResolvedMatcher;
+  stmt: ExpectStmt;
+  clause: MatcherClause;
+  scope: Scope;
+  engine: Engine;
+}): MatcherArgs<unknown> {
+  const { stmt, clause, scope } = args;
+  const subject = stmt.subject ? evaluate(stmt.subject, scope) : undefined;
+  const positional = clause.args.map((expr) => evaluate(expr, scope));
+  return { subject, args: positional, 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: {
+  resolved: ResolvedMatcher;
+  stmt: ExpectStmt;
+  clause: MatcherClause;
+  scope: Scope;
+  engine: Engine;
+}): unknown {
+  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: string): VennError {
+  return new VennError({
+    code: "VN2004",
+    message: `Unknown matcher "${name}".`,
+    detail: { name },
+  });
+}

package/src/scheduler/run-parallel.ts

@@ -0,0 +1,68 @@
+import type { ParallelStmt, Statement } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { branchEngine } from "./branch-engine.js";
+import { runPool } from "./concurrency.js";
+import type { Engine } from "./engine.types.js";
+import { optsNumber } from "./opts.js";
+import { optsText } from "./opts-text.js";
+import { runStatement } from "./run-statements.js";
+import { CancelSignal, isControlSignal } from "./signals.js";
+
+/**
+ * `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.
+ */
+export async function runParallel(engine: Engine, stmt: ParallelStmt, scope: Scope): Promise<void> {
+  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: unknown[] = [];
+  await runPool(stmt.body.stmts, Math.max(1, limit), (child) =>
+    branch({ engine, child, scope, controller, failures, onError }),
+  );
+  report(failures);
+}
+
+interface BranchArgs {
+  engine: Engine;
+  child: Statement;
+  scope: Scope;
+  controller: AbortController;
+  failures: unknown[];
+  onError: string;
+}
+
+/**
+ * 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: BranchArgs): Promise<void> {
+  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: readonly unknown[]): void {
+  if (failures.length === 0) return;
+  if (failures.length === 1) throw failures[0];
+  throw new AggregateError(failures, `${failures.length} parallel branches failed.`);
+}

package/src/scheduler/run-prologue.ts

@@ -0,0 +1,59 @@
+import {
+  type Block,
+  type Declaration,
+  type Document,
+  isLifecycleDecl,
+  isRunnable,
+  type LifecycleDecl,
+} from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { runBlock } from "./run-block.js";
+import { runStatement } from "./run-statements.js";
+
+/** A cleanup a program deferred, to be run on the way out. */
+export type Teardown = () => Promise<void>;
+
+/**
+ * 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.
+ */
+export async function runPrologue(args: {
+  engine: Engine;
+  doc: Document;
+  scope: Scope;
+  into?: Teardown[];
+}): Promise<Teardown[]> {
+  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: Declaration): node is Declaration & LifecycleDecl {
+  return isLifecycleDecl(node) && node.hook === "defer";
+}
+
+function deferred(args: { engine: Engine; body: Block; scope: Scope }): Teardown {
+  // Cleanup must complete even when what it tidies was cancelled mid-flight.
+  const engine: Engine = { ...args.engine, signal: undefined };
+  return async () => {
+    await runBlock(engine, args.body, args.scope.child());
+  };
+}
+
+/** Undo in reverse: what opened last is given back first. */
+export async function runTeardowns(teardowns: readonly Teardown[]): Promise<void> {
+  for (const teardown of [...teardowns].reverse()) await teardown();
+}

package/src/scheduler/run-race.ts

@@ -0,0 +1,20 @@
+import type { RaceStmt } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { branchEngine } from "./branch-engine.js";
+import type { Engine } from "./engine.types.js";
+import { runStatement } from "./run-statements.js";
+
+/** `race { … }`: the first branch to settle wins, the losers are cancelled. */
+export async function runRace(engine: Engine, stmt: RaceStmt, scope: Scope): Promise<void> {
+  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();
+    // The losers reject with CancelSignal once they reach a statement boundary.
+    for (const branch of branches) branch.catch(() => {});
+  }
+}

package/src/scheduler/run-repeat.ts

@@ -0,0 +1,54 @@
+import {
+  buildProblem,
+  CODES,
+  evaluate,
+  ProblemError,
+  type RepeatStmt,
+  typeName,
+} from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { nodeSpan } from "./node-span.js";
+import { runBlock } from "./run-block.js";
+import { BreakSignal, ContinueSignal } from "./signals.js";
+
+/** `repeat N as i { … }`: run the body N times, honouring break/continue. */
+export async function runRepeat(engine: Engine, stmt: RepeatStmt, scope: Scope): Promise<void> {
+  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: Engine, stmt: RepeatStmt, value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw notANumber(engine, stmt, value);
+  return value > 0 ? Math.floor(value) : 0;
+}
+
+function notANumber(engine: Engine, stmt: RepeatStmt, value: unknown): ProblemError {
+  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 { … }`.",
+    }),
+  );
+}

package/src/scheduler/run-run.ts

@@ -0,0 +1,41 @@
+import { VennError } from "@venn-lang/contracts";
+import { evaluate, type FragmentDecl, type ParamList, type RunStmt } from "@venn-lang/core";
+import { createScope, type Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { runBlock } from "./run-block.js";
+import { ReturnSignal } from "./signals.js";
+
+/** `run fragment(args) as x`: invoke a fragment and bind its return value. */
+export async function runRun(engine: Engine, stmt: RunStmt, scope: Scope): Promise<void> {
+  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: Engine, fragment: FragmentDecl, scope: Scope): Promise<unknown> {
+  try {
+    await runBlock(engine, fragment.body, scope);
+    return undefined;
+  } catch (error) {
+    if (error instanceof ReturnSignal) return error.value;
+    throw error;
+  }
+}
+
+function bindParams(scope: Scope, params: ParamList | undefined, args: readonly unknown[]): void {
+  (params?.params ?? []).forEach((param, index) => {
+    scope.set(param.name, args[index]);
+  });
+}
+
+function unknownFragment(name: string): VennError {
+  return new VennError({
+    code: "VN2005",
+    message: `Unknown fragment "${name}".`,
+    detail: { fragment: name },
+  });
+}