@venn-lang/runtime 0.1.0

package/src/scheduler/run-script.ts

@@ -0,0 +1,48 @@
+import type { Document } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { absorbExit } from "./absorb-exit.js";
+import { createBaseScope } from "./base-scope.js";
+import { bindFunctions } from "./bind-globals.js";
+import { bindImports } from "./bind-imports.js";
+import type { Engine } from "./engine.types.js";
+import { runPrologue } from "./run-prologue.js";
+import { registerEnding, runSetup } from "./script-lifecycle.js";
+
+/**
+ * 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.
+ */
+export async function runScript(engine: Engine, doc: Document): Promise<void> {
+  const base = (): Scope => 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: Engine, doc: Document, scope: Scope): Promise<void> {
+  const ending = registerEnding({ engine, doc, scope });
+  await runSetup({ engine, doc, scope });
+  // Collected into the ending as they are reached, so a program interrupted
+  // halfway gives back exactly what it had managed to take.
+  await runPrologue({ engine, doc, scope, into: ending.deferred });
+}

package/src/scheduler/run-statements.ts

@@ -0,0 +1,107 @@
+import type {
+  ActionCall,
+  CaptureStmt,
+  ExpectStmt,
+  ForEachStmt,
+  GroupDecl,
+  IfStmt,
+  LetStmt,
+  ParallelStmt,
+  RaceStmt,
+  RepeatStmt,
+  ReturnStmt,
+  RunStmt,
+  Statement,
+  StepDecl,
+  TryStmt,
+  WhileStmt,
+} 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 { runActionStatement } from "./run-action.js";
+import { runCapture, runLet, runReturn } from "./run-bindings.js";
+import { runExpect } from "./run-expect.js";
+import { runForEach } from "./run-foreach.js";
+import { runGroup } from "./run-group.js";
+import { runIf } from "./run-if.js";
+import { runParallel } from "./run-parallel.js";
+import { runRace } from "./run-race.js";
+import { runRepeat } from "./run-repeat.js";
+import { runRun } from "./run-run.js";
+import { runStep } from "./run-step.js";
+import { runTry } from "./run-try.js";
+import { runWhile } from "./run-while.js";
+import { BreakSignal, CancelSignal, ContinueSignal } from "./signals.js";
+
+/** Run a block's statements in order. */
+export async function runStatements(
+  engine: Engine,
+  stmts: readonly Statement[],
+  scope: Scope,
+): Promise<void> {
+  for (const stmt of stmts) {
+    const pending = runStatement(engine, stmt, scope);
+    if (pending) await pending;
+  }
+}
+
+/**
+ * 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.
+ */
+export function runStatement(engine: Engine, stmt: Statement, scope: Scope): Pending {
+  if (engine.signal?.aborted) throw new CancelSignal();
+  switch (stmt.$type) {
+    case "LetStmt":
+      return runLet(engine, stmt as LetStmt, scope);
+    case "ActionCall":
+      return runActionStatement(engine, stmt as ActionCall, scope);
+    case "ExpectStmt":
+      return runExpect(engine, stmt as ExpectStmt, scope);
+    case "IfStmt":
+      return runIf(engine, stmt as IfStmt, scope);
+    case "StepDecl":
+      return runStep(engine, stmt as StepDecl, scope);
+    case "GroupDecl":
+      return runGroup(engine, stmt as GroupDecl, scope);
+    default:
+      return control(engine, stmt, scope);
+  }
+}
+
+/** Loops, concurrency and the control-flow signals: the rarer half. */
+function control(engine: Engine, stmt: Statement, scope: Scope): Pending {
+  switch (stmt.$type) {
+    case "ForEachStmt":
+      return runForEach(engine, stmt as ForEachStmt, scope);
+    case "RepeatStmt":
+      return runRepeat(engine, stmt as RepeatStmt, scope);
+    case "WhileStmt":
+      return runWhile(engine, stmt as WhileStmt, scope);
+    case "ParallelStmt":
+      return runParallel(engine, stmt as ParallelStmt, scope);
+    case "RaceStmt":
+      return runRace(engine, stmt as RaceStmt, scope);
+    case "TryStmt":
+      return runTry(engine, stmt as TryStmt, scope);
+    case "RunStmt":
+      return runRun(engine, stmt as RunStmt, scope);
+    default:
+      return leaf(stmt, scope);
+  }
+}
+
+function leaf(stmt: Statement, scope: Scope): Pending {
+  if (stmt.$type === "CaptureStmt") return runCapture(stmt as CaptureStmt, scope);
+  if (stmt.$type === "ReturnStmt") return runReturn(stmt as ReturnStmt, scope);
+  if (stmt.$type === "BreakStmt") throw new BreakSignal();
+  if (stmt.$type === "ContinueStmt") throw new ContinueSignal();
+  // LifecycleDecl (on/defer) is handled by runBlock / runFlow, not here.
+  return undefined;
+}

package/src/scheduler/run-step.ts

@@ -0,0 +1,76 @@
+import { type Block, isBlock, isStepDecl, type StepDecl } 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 { matchesTitle } from "./filter.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 { isControlSignal } from "./signals.js";
+
+/** Run a step honouring @skip/@only, @lock, @timeout and @retry; its bindings are step-local. */
+export async function runStep(engine: Engine, step: StepDecl, parent: Scope): Promise<void> {
+  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: Engine, step: StepDecl): boolean {
+  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 = new WeakMap<Block, boolean>();
+
+/**
+ * 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: unknown): boolean {
+  if (!isBlock(container)) return false;
+  const known = focused.get(container);
+  if (known !== undefined) return known;
+  const found = container.stmts.some((stmt) => isStepDecl(stmt) && hasAnnotation(stmt, "only"));
+  focused.set(container, found);
+  return found;
+}
+
+function execute(
+  engine: Engine,
+  step: StepDecl,
+  scopes: { parent: Scope; scope: Scope },
+): Promise<void> {
+  return withLock(engine, readLock(step), () =>
+    runWithAnnotations({
+      engine,
+      node: step,
+      scope: scopes.parent,
+      title: step.title,
+      // The caller wants a promise; a block that never suspended returns none.
+      run: () => runAround(step, () => runBlock(engine, step.body, scopes.scope)),
+    }),
+  );
+}
+
+function finished(engine: Engine, title: string, status: "passed" | "failed"): void {
+  engine.emitter.emit({ kind: "step.finished", data: { title, status } });
+}

package/src/scheduler/run-try.ts

@@ -0,0 +1,34 @@
+import type { TryStmt } 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 { isControlSignal } from "./signals.js";
+
+/** `try { } catch e { } finally { }`: control signals pass through, errors go to catch. */
+export async function runTry(engine: Engine, stmt: TryStmt, scope: Scope): Promise<void> {
+  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: {
+  engine: Engine;
+  stmt: TryStmt;
+  scope: Scope;
+  error: unknown;
+}): Promise<void> {
+  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: unknown): { message: string; code: string } {
+  const e = error as { message?: string; code?: string };
+  return { message: e?.message ?? String(error), code: e?.code ?? "VN7000" };
+}

package/src/scheduler/run-while.ts

@@ -0,0 +1,50 @@
+import {
+  buildProblem,
+  CODES,
+  evaluate,
+  ProblemError,
+  truthy,
+  type WhileStmt,
+} 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 { settle } from "./settled.js";
+import { BreakSignal, ContinueSignal } from "./signals.js";
+
+/**
+ * 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 = 100_000;
+
+/** `while cond { … }`: loop while the condition is truthy. */
+export async function runWhile(engine: Engine, stmt: WhileStmt, scope: Scope): Promise<void> {
+  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: Engine, stmt: WhileStmt): ProblemError {
+  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.",
+    }),
+  );
+}

package/src/scheduler/script-lifecycle.ts

@@ -0,0 +1,47 @@
+import type { Document } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import { collectHooks } from "./collect.js";
+import type { Engine } from "./engine.types.js";
+import { runHooks } from "./run-lifecycle.js";
+import type { Teardown } from "./run-prologue.js";
+import { runTeardowns } from "./run-prologue.js";
+
+/**
+ * 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.
+ */
+export async function runSetup(args: {
+  engine: Engine;
+  doc: Document;
+  scope: Scope;
+}): Promise<void> {
+  await runHooks({ engine: args.engine, hooks: collectHooks(args.doc).setup, scope: args.scope });
+}
+
+/** What the program will do on the way out, filled in as the program runs. */
+export interface Ending {
+  /** Cleanups the statements deferred, in the order they were written. */
+  readonly deferred: Teardown[];
+}
+
+/**
+ * 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.
+ */
+export function registerEnding(args: { engine: Engine; doc: Document; scope: Scope }): Ending {
+  const ending: 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;
+}

package/src/scheduler/settled.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export function isPending(value: unknown): value is Promise<unknown> {
+  return value instanceof Promise;
+}
+
+/** Wait for a value only if there is something to wait for. */
+export async function settle<T>(value: T | Promise<T>): Promise<T> {
+  return isPending(value) ? ((await value) as T) : (value as T);
+}

package/src/scheduler/signals.ts

@@ -0,0 +1,33 @@
+// Control-flow signals thrown to unwind loops and fragments. Deliberately not
+// Errors, so a `try/catch` in a flow re-throws them instead of treating them as
+// failures.
+
+export class BreakSignal {}
+export class ContinueSignal {}
+export class ReturnSignal {
+  constructor(readonly value: unknown) {}
+}
+/** Thrown at a statement boundary when the branch's race has already been won. */
+export class CancelSignal {}
+/**
+ * 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.
+ */
+export class ExitSignal {
+  constructor(readonly code: number) {}
+}
+
+export type ControlSignal = BreakSignal | ContinueSignal | ReturnSignal | CancelSignal | ExitSignal;
+
+export function isControlSignal(value: unknown): value is ControlSignal {
+  return (
+    value instanceof BreakSignal ||
+    value instanceof ContinueSignal ||
+    value instanceof ReturnSignal ||
+    value instanceof CancelSignal ||
+    value instanceof ExitSignal
+  );
+}

package/src/scheduler/target.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+export const PRELUDE: ReadonlySet<string> = new Set([
+  "print",
+  "log",
+  "wait",
+  "skip",
+  "fail",
+  "exit",
+]);
+
+/** Split an action target `namespace.action` into parts (no dot ⇒ namespace only). */
+export function splitTarget(target: string): { namespace: string; name: string } {
+  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. */
+export function resolveTarget(
+  target: string,
+  aliases: ReadonlyMap<string, string>,
+): { namespace: string; name: string } {
+  const { namespace, name } = splitTarget(target);
+  return { namespace: aliases.get(namespace) ?? namespace, name };
+}

package/src/scheduler/unknown-option.ts

@@ -0,0 +1,87 @@
+import { buildProblem, CODES, type MapEntry, type MapLit, type Problem } from "@venn-lang/core";
+import { type ParamSpec, paramSpecs } from "@venn-lang/sdk";
+import { nodeSpan } from "./node-span.js";
+
+/**
+ * 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.
+ */
+export function unknownOptions(args: {
+  opts: MapLit | undefined;
+  params: unknown;
+  uri: string;
+}): Problem[] {
+  const specs = paramSpecs(args.params as never);
+  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: unknown): boolean {
+  const def = (params as { def?: { catchall?: unknown; innerType?: unknown } } | undefined)?.def;
+  if (def?.catchall !== undefined) return true;
+  return def?.innerType !== undefined && welcomesMore(def.innerType);
+}
+
+function unknownOption(args: {
+  entry: MapEntry;
+  specs: readonly ParamSpec[];
+  uri: string;
+}): Problem {
+  const { key } = args.entry;
+  const hint = nearest(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(key: string, specs: readonly ParamSpec[]): string | undefined {
+  const scored = specs
+    .map((spec) => ({ name: spec.name, distance: distance(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
+    : undefined;
+}
+
+/** Levenshtein, small enough to keep here and precise enough for a "did you mean". */
+function distance(left: string, right: string): number {
+  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;
+}

package/src/scope/create-scope.ts

@@ -0,0 +1,67 @@
+import type { Cell } from "@venn-lang/core";
+import type { Scope } from "./scope.types.js";
+
+/**
+ * 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.
+ */
+class MapScope implements Scope {
+  private readonly vars = new Map<string, Cell>();
+
+  constructor(private readonly parent?: Scope) {}
+
+  lookup(name: string): unknown {
+    // A cell always exists once asked for, so its presence answers whether this
+    // scope binds the name. A binding legitimately holding `undefined` reads as
+    // its own value rather than falling through to the parent.
+    const found = this.vars.get(name);
+    return found === undefined ? this.parent?.lookup(name) : found.value;
+  }
+
+  set(name: string, value: unknown): void {
+    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: string): Cell {
+    const own = this.vars.get(name);
+    if (own) return own;
+    const inherited = this.parent?.cell(name);
+    if (inherited) return inherited;
+    const made: Cell = { value: undefined };
+    this.vars.set(name, made);
+    return made;
+  }
+
+  child(): Scope {
+    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.
+ */
+export function createScope(parent?: Scope): Scope {
+  return new MapScope(parent);
+}

package/src/scope/index.ts

@@ -0,0 +1,2 @@
+export { createScope } from "./create-scope.js";
+export type { Scope } from "./scope.types.js";

package/src/scope/scope.types.ts

@@ -0,0 +1,12 @@
+import type { CellEnv } from "@venn-lang/core";
+
+/**
+ * A lexical scope: the evaluator's env plus mutation and nesting.
+ *
+ * A `CellEnv`, so a closure defined here can address its free names once and
+ * read them by index afterwards instead of walking the chain per call.
+ */
+export interface Scope extends CellEnv {
+  set(name: string, value: unknown): void;
+  child(): Scope;
+}