@venn-lang/runtime 0.1.0

package/src/scheduler/block-plan.ts

@@ -0,0 +1,66 @@
+import {
+  type Block,
+  compileExpr,
+  isLetStmt,
+  isLifecycleDecl,
+  type LetStmt,
+  type Statement,
+} from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+import type { Engine } from "./engine.types.js";
+import { actionCall } from "./invocation.js";
+import type { Pending } from "./pending.types.js";
+import { runStatement } from "./run-statements.js";
+import { isPending } from "./settled.js";
+
+/** One statement of a block, bound to everything the source already settled. */
+export type Step = (engine: Engine, scope: Scope) => Pending;
+
+/** A block reduced to what running it needs, decided once from the source. */
+export interface BlockPlan {
+  readonly steps: readonly Step[];
+  readonly defers: boolean;
+}
+
+const plans = new WeakMap<Block, BlockPlan>();
+
+/** The plan for a block, built on first use and cached against the node itself. */
+export function planOf(block: Block): BlockPlan {
+  const known = plans.get(block);
+  if (known) return known;
+  const built: BlockPlan = {
+    steps: block.stmts.map(stepOf),
+    defers: block.stmts.some(isDefer),
+  };
+  plans.set(block, built);
+  return built;
+}
+
+function isDefer(stmt: Statement): boolean {
+  return isLifecycleDecl(stmt) && stmt.hook === "defer";
+}
+
+function stepOf(stmt: Statement): Step {
+  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: Statement): Step | undefined {
+  if (!isLetStmt(stmt)) return undefined;
+  const let_ = stmt as LetStmt;
+  if (let_.args.length > 0 || let_.opts) return undefined;
+  const call = actionCall(let_.value);
+  if (call && call.target.indexOf(".") >= 0) return undefined;
+  const name = let_.name;
+  const thunk = compileExpr(let_.value);
+  return (_engine, scope) => bind(name, thunk(scope), scope);
+}
+
+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);
+}

package/src/scheduler/branch-engine.ts

@@ -0,0 +1,13 @@
+import type { Engine } from "./engine.types.js";
+
+/**
+ * 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.
+ */
+export function branchEngine(engine: Engine, signal: AbortSignal): Engine {
+  return { ...engine, signal, ctx: { ...engine.ctx, signal } };
+}

package/src/scheduler/call-params.ts

@@ -0,0 +1,140 @@
+import {
+  type AstNode,
+  buildProblem,
+  CODES,
+  display,
+  type MapEntry,
+  type MapLit,
+  type Problem,
+  ProblemError,
+  typeName,
+} from "@venn-lang/core";
+import type { ZodType } from "@venn-lang/sdk";
+import { nodeSpan } from "./node-span.js";
+import { unknownOptions } from "./unknown-option.js";
+
+/** The bits of a Zod failure this reads. Structural, so no Zod internals leak out. */
+interface Issue {
+  code?: string;
+  path?: readonly PropertyKey[];
+  expected?: string;
+  values?: readonly unknown[];
+}
+
+/** Zod's word for a type, in the word the language uses for it. */
+const WORDS: Record<string, string> = {
+  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.
+ */
+export function callParams(args: {
+  schema: ZodType | undefined;
+  opts: MapLit | undefined;
+  raw: unknown;
+  site: AstNode;
+  uri: string;
+}): unknown {
+  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: {
+  schema: ZodType;
+  opts: MapLit | undefined;
+  raw: unknown;
+  site: AstNode;
+  uri: string;
+}): unknown {
+  try {
+    return args.schema.parse(args.raw);
+  } catch (error) {
+    const issue = firstIssue(error);
+    // Not a schema rejection: a transform threw, and it already says why.
+    if (!issue) throw error;
+    const { raw, opts, site, uri } = args;
+    throw new ProblemError(badOption({ issue, raw, opts, site, uri }));
+  }
+}
+
+function badOption(args: {
+  issue: Issue;
+  raw: unknown;
+  opts: MapLit | undefined;
+  site: AstNode;
+  uri: string;
+}): Problem {
+  const path = args.issue.path ?? [];
+  return buildProblem({
+    spec: CODES.VN3010_TYPE_MISMATCH,
+    // The entry that failed, else the map; a required option nobody wrote has
+    // neither, and then the call itself is the nearest true place.
+    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: { key: string; issue: Issue; value: unknown }): string {
+  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 === undefined) 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: string, values: readonly unknown[], value: unknown): string {
+  const accepted = values.map((option) => shown(option)).join(", ");
+  return `"${key}" must be one of ${accepted} — not ${shown(value)}.`;
+}
+
+/** A value as a message shows it: strings quoted, so `"soon"` reads as text. */
+function shown(value: unknown): string {
+  return typeof value === "string" ? JSON.stringify(value) : display(value);
+}
+
+function valueAt(raw: unknown, path: readonly PropertyKey[]): unknown {
+  let value = raw;
+  for (const key of path) value = (value as Record<PropertyKey, unknown> | undefined)?.[key];
+  return value;
+}
+
+/** The written entry to underline, when the failure names a key this map spells. */
+function entryFor(opts: MapLit | undefined, path: readonly PropertyKey[]): MapEntry | undefined {
+  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: unknown): Issue | undefined {
+  const issues = (error as { issues?: unknown } | undefined)?.issues;
+  return Array.isArray(issues) ? (issues[0] as Issue) : undefined;
+}

package/src/scheduler/cleanup.types.ts

@@ -0,0 +1,18 @@
+/** Something a run opened, and how to give it back. */
+export type Cleanup = () => Promise<void>;
+
+/**
+ * Where a run registers what it opened, for whoever owns the process.
+ *
+ * The runtime does not decide when a program ends: a served program ends when
+ * the machine says so, and only the host hears that. So the run says what has to
+ * happen on the way out, and the host says when.
+ */
+export interface CleanupSink {
+  add(cleanup: Cleanup): unknown;
+}
+
+/** A sink that also runs what it collected, newest first. */
+export interface CleanupList extends CleanupSink {
+  close(): Promise<void>;
+}

package/src/scheduler/collect.ts

@@ -0,0 +1,60 @@
+import {
+  type Document,
+  evaluate,
+  type FragmentDecl,
+  isConfigDecl,
+  isFragmentDecl,
+  isLifecycleDecl,
+  type LifecycleDecl,
+} from "@venn-lang/core";
+import { createScope } from "../scope/index.js";
+
+/** Top-level lifecycle blocks, grouped by hook. */
+export interface SuiteHooks {
+  setup: LifecycleDecl[];
+  teardown: LifecycleDecl[];
+  beforeEach: LifecycleDecl[];
+  afterEach: LifecycleDecl[];
+}
+
+/** Index the document's fragments by name for `run`. */
+export function collectFragments(doc: Document): Map<string, FragmentDecl> {
+  const map = new Map<string, FragmentDecl>();
+  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. */
+export function collectConfig(
+  doc: Document,
+  env: Record<string, unknown>,
+): Record<string, unknown> {
+  const decl = doc.decls.find(isConfigDecl);
+  if (!decl) return {};
+  const scope = createScope();
+  scope.set("env", env);
+  return evaluate(decl.body, scope) as Record<string, unknown>;
+}
+
+/** Gather top-level setup/teardown/beforeEach/afterEach blocks. */
+export function collectHooks(doc: Document): SuiteHooks {
+  const hooks: SuiteHooks = { setup: [], teardown: [], beforeEach: [], afterEach: [] };
+  for (const decl of doc.decls) {
+    if (isLifecycleDecl(decl)) addHook(hooks, decl);
+  }
+  return hooks;
+}
+
+/** Gather the `on <event> { … }` handlers a flow declared, for one event. */
+export function collectOn(stmts: readonly unknown[], event: string): LifecycleDecl[] {
+  return stmts.filter(
+    (stmt): stmt is LifecycleDecl => isLifecycleDecl(stmt) && stmt.event === event,
+  );
+}
+
+function addHook(hooks: SuiteHooks, decl: LifecycleDecl): void {
+  const bucket = hooks[decl.hook as keyof SuiteHooks];
+  if (bucket) bucket.push(decl);
+}

package/src/scheduler/concurrency.ts

@@ -0,0 +1,16 @@
+/** Run `task` over `items` with at most `limit` in flight at once. */
+export async function runPool<T>(
+  items: readonly T[],
+  limit: number,
+  task: (item: T, index: number) => Promise<void>,
+): Promise<void> {
+  const size = Math.max(1, limit);
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      await task(items[index] as T, index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
+}

package/src/scheduler/create-cleanup-list.ts

@@ -0,0 +1,17 @@
+import type { Cleanup, CleanupList } from "./cleanup.types.js";
+
+/**
+ * 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.
+ */
+export function createCleanupList(): CleanupList {
+  const pending: Cleanup[] = [];
+  return {
+    add: (cleanup) => pending.push(cleanup),
+    close: async () => {
+      for (const cleanup of pending.splice(0).reverse()) await cleanup().catch(() => {});
+    },
+  };
+}

package/src/scheduler/declared-arity.ts

@@ -0,0 +1,13 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+
+/**
+ * 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.
+ */
+export function takes(action: ActionDefinition): number {
+  if (action.args?.some((each) => each.rest)) return Number.POSITIVE_INFINITY;
+  return action.args?.length ?? action.signature?.params.length ?? 0;
+}

package/src/scheduler/engine.types.ts

@@ -0,0 +1,50 @@
+import type { Clock, LockProvider } from "@venn-lang/contracts";
+import type { FragmentDecl } from "@venn-lang/core";
+import type { ActionContext } from "@venn-lang/sdk";
+import type { Emitter } from "../emit/index.js";
+import type { Registry } from "../registry/index.js";
+import type { ImportGraph } from "./bind-imports.js";
+import type { CleanupSink } from "./cleanup.types.js";
+import type { RunFilter } from "./filter.types.js";
+import type { FlakyTally } from "./flaky.types.js";
+
+/** Mutable pass/fail tally accumulated across a run. */
+export interface RunCounters {
+  passed: number;
+  failed: number;
+}
+
+/** The shared state every `run-*` step reads from. */
+export interface Engine {
+  registry: Registry;
+  emitter: Emitter;
+  ctx: ActionContext;
+  clock: Clock;
+  lock: LockProvider;
+  uri: string;
+  result: RunCounters;
+  fragments: Map<string, FragmentDecl>;
+  /**
+   * How to reach what the imported files published: their modules, and how a
+   * specifier names one. Absent when nothing was imported, which is most runs.
+   */
+  imports?: ImportGraph;
+  /** `use "…" as h` aliases, mapped to the namespace each package contributes. */
+  aliases: ReadonlyMap<string, string>;
+  /** `@flaky(ratio)` tallies per annotated node, settled at the end of the run. */
+  flaky: Map<object, FlakyTally>;
+  /** Set on a `race` branch: once aborted, the branch stops at its next statement. */
+  signal?: AbortSignal;
+  /** What a script-mode program owes the machine when it ends. */
+  cleanup: CleanupSink;
+  env: Record<string, unknown>;
+  /** Which flows and steps to include (`--tags`, `--flow`, `--step`). */
+  filter: RunFilter;
+  /** Stop after the first flow that fails. */
+  bail?: boolean;
+  /**
+   * The code an `exit` asked to leave with, unset until one runs. Read by the
+   * host: `exit 0` ends a run cleanly however many flows were left.
+   */
+  exit?: number;
+}

package/src/scheduler/filter.ts

@@ -0,0 +1,5 @@
+/** A title matches when the needle is absent, or contained case-insensitively. */
+export function matchesTitle(title: string, needle: string | undefined): boolean {
+  if (!needle) return true;
+  return title.toLowerCase().includes(needle.toLowerCase());
+}

package/src/scheduler/filter.types.ts

@@ -0,0 +1,9 @@
+/** Which flows and steps a run includes. Absent fields mean "no restriction". */
+export interface RunFilter {
+  /** Keep flows carrying at least one of these `@tags`. */
+  tags?: readonly string[];
+  /** Keep flows whose title contains this text, case-insensitively. */
+  flow?: string;
+  /** Keep steps whose title contains this text, case-insensitively. */
+  step?: string;
+}

package/src/scheduler/flaky.ts

@@ -0,0 +1,32 @@
+import { type Annotated, readFlaky } from "./annotations.js";
+import type { Engine } from "./engine.types.js";
+import type { FlakyTally } from "./flaky.types.js";
+
+/** Record one execution of a `@flaky(ratio)` node, and how much it failed by. */
+export function recordFlaky(engine: Engine, node: Annotated, before: number): void {
+  const ratio = readFlaky(node);
+  if (ratio === undefined) 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.
+ */
+export function settleFlaky(engine: Engine): void {
+  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: FlakyTally): string {
+  return `flaky tolerated: ${tally.failedRuns}/${tally.runs} runs failed, within ratio ${tally.ratio}`;
+}

package/src/scheduler/flaky.types.ts

@@ -0,0 +1,7 @@
+/** Per-node flakiness tally, accumulated across executions and settled once. */
+export interface FlakyTally {
+  ratio: number;
+  runs: number;
+  failedRuns: number;
+  failedUnits: number;
+}

package/src/scheduler/index.ts

@@ -0,0 +1,16 @@
+export { absorbExit } from "./absorb-exit.js";
+export { collectAliases, collectBoundNames, collectNamespaces } from "./aliases.js";
+export { bindImports, type ImportGraph } from "./bind-imports.js";
+export type { Cleanup, CleanupList, CleanupSink } from "./cleanup.types.js";
+export { collectConfig, collectFragments, collectOn } from "./collect.js";
+export { createCleanupList } from "./create-cleanup-list.js";
+export type { Engine, RunCounters } from "./engine.types.js";
+export { matchesTitle } from "./filter.js";
+export type { RunFilter } from "./filter.types.js";
+export type { Invocation } from "./invocation.js";
+export { actionTarget, invocationOf } from "./invocation.js";
+export { nodeSource, nodeSpan } from "./node-span.js";
+export { runDocument } from "./run-document.js";
+export { runScript } from "./run-script.js";
+export { PRELUDE, resolveTarget, splitTarget } from "./target.js";
+export { unknownOptions } from "./unknown-option.js";

package/src/scheduler/invocation.ts

@@ -0,0 +1,103 @@
+import {
+  type AstNode,
+  type Call,
+  type Expr,
+  isCall,
+  isMember,
+  isRef,
+  type LetStmt,
+  type MapLit,
+} from "@venn-lang/core";
+
+/** What running an action needs, whichever syntax spelled it. */
+export interface Invocation {
+  target: string;
+  args: readonly Expr[];
+  opts?: MapLit;
+  /**
+   * Where the call is written, for a failure with no smaller node to point at.
+   * Absent when the invocation *is* the node: a call spelled as a statement.
+   */
+  node?: AstNode;
+}
+
+/**
+ * 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.
+ */
+export function actionTarget(expr: Expr | undefined): string | undefined {
+  if (!expr) return undefined;
+  if (isRef(expr)) return expr.name;
+  if (!isMember(expr) || expr.optional) return undefined;
+  const receiver = actionTarget(expr.receiver);
+  return receiver === undefined ? undefined : `${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.
+ */
+export function invocationOf(stmt: LetStmt): Invocation | undefined {
+  return remember(invocations, stmt, readInvocation);
+}
+
+function readInvocation(stmt: LetStmt): Invocation | undefined {
+  if (stmt.args.length === 0 && !stmt.opts) return undefined;
+  const target = actionTarget(stmt.value);
+  if (target === undefined) return undefined;
+  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.
+ */
+export function actionCall(value: Expr): ActionShape | undefined {
+  return remember(calls, value, readActionCall);
+}
+
+function readActionCall(value: Expr): ActionShape | undefined {
+  const bare = actionTarget(value);
+  if (bare !== undefined) return { target: bare, args: [] };
+  if (!isCall(value)) return undefined;
+  const target = actionTarget(value.callee);
+  return target === undefined ? undefined : { target, args: argValues(value) };
+}
+
+/** An action in expression position: the path it names and its arguments. */
+export interface ActionShape {
+  target: string;
+  args: readonly Expr[];
+}
+
+/**
+ * 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 = new WeakMap<LetStmt, Invocation | null>();
+const calls = new WeakMap<Expr, ActionShape | null>();
+
+function remember<K extends object, V>(
+  cache: WeakMap<K, V | null>,
+  key: K,
+  read: (key: K) => V | undefined,
+): V | undefined {
+  const known = cache.get(key);
+  if (known !== undefined) return known ?? undefined;
+  const found = read(key) ?? null;
+  cache.set(key, found);
+  return found ?? undefined;
+}
+
+function argValues(call: Call): Expr[] {
+  return (call.args?.args ?? []).map((arg) => arg.value);
+}

package/src/scheduler/local-call.ts

@@ -0,0 +1,28 @@
+import { isCallable, isNamespaceValue, memberValue } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+
+/**
+ * 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.
+ */
+export function localCallee(target: string, scope: Scope): unknown {
+  const segments = target.split(".");
+  const head = segments[0];
+  if (!head) return undefined;
+  const root = scope.lookup(head);
+  if (root === undefined || isNamespaceValue(root)) return undefined;
+  let value: unknown = root;
+  for (let at = 1; at < segments.length; at += 1) {
+    value = memberValue(value, segments[at] as string);
+  }
+  return isCallable(value) ? value : undefined;
+}

package/src/scheduler/node-span.ts

@@ -0,0 +1,29 @@
+import type { Span } from "@venn-lang/core";
+
+/** Minimal structural view of a Langium CST node (avoids importing langium). */
+interface CstView {
+  offset?: number;
+  length?: number;
+  text?: string;
+  range?: { start?: { line?: number; character?: number } };
+}
+interface WithCst {
+  $cstNode?: CstView;
+}
+
+/** The exact source text of an AST node, for the event stream. */
+export function nodeSource(node: WithCst): string {
+  return node.$cstNode?.text ?? "";
+}
+
+/** A Span for an AST node, for a runtime Problem. */
+export function nodeSpan(node: WithCst, uri: string): Span {
+  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,
+  };
+}

package/src/scheduler/opts-text.ts

@@ -0,0 +1,10 @@
+import { evaluate, type MapLit } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+
+/** Read a string field from an options map literal (e.g. `{ onError: "cancel" }`). */
+export function optsText(opts: MapLit | undefined, key: string, scope: Scope): string | undefined {
+  const entry = opts?.entries.find((candidate) => candidate.key === key);
+  if (!entry) return undefined;
+  const value = evaluate(entry.value, scope);
+  return typeof value === "string" ? value : undefined;
+}

package/src/scheduler/opts.ts

@@ -0,0 +1,14 @@
+import { evaluate, type MapLit } from "@venn-lang/core";
+import type { Scope } from "../scope/index.js";
+
+/** Read a numeric field from an options map literal (e.g. `{ concurrency: 4 }`). */
+export function optsNumber(
+  opts: MapLit | undefined,
+  key: string,
+  scope: Scope,
+): number | undefined {
+  const entry = opts?.entries.find((candidate) => candidate.key === key);
+  if (!entry) return undefined;
+  const value = evaluate(entry.value, scope);
+  return typeof value === "number" ? value : undefined;
+}