@venn-lang/core 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@venn-lang/core",
+  "version": "0.1.0",
+  "description": "The Venn compiler: grammar, parser, type checker, expression compiler, decorator expansion, and the Problem model.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "compiler",
+    "parser",
+    "langium",
+    "dsl"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/core#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "langium": "^4.3.1",
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@fast-check/vitest": "^0.4.1",
+    "langium-cli": "^4.3.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "langium:generate": "langium generate",
+    "prebuild": "pnpm run langium:generate",
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/ast/call-args.ts

@@ -0,0 +1,15 @@
+import type { ActionCall, Expr } from "../generated/ast.js";
+
+/**
+ * The arguments of a call, however it was written.
+ *
+ * The language spells a call two ways, `conn.close()` with brackets and
+ * `http.get "url"` without, and the parser keeps them in different places on
+ * the node. They are the same call with the same arguments, so every reader
+ * downstream asks here and sees one list.
+ */
+export function callArgs(call: ActionCall): readonly Expr[] {
+  const bracketed = call.call?.args ?? [];
+  if (bracketed.length === 0) return call.args;
+  return [...bracketed.map((arg) => arg.value), ...call.args];
+}

package/src/ast/dotted-path.ts

@@ -0,0 +1,22 @@
+import type { AstNode } from "langium";
+import type { Expr } from "../generated/ast.js";
+import { isMember, isRef } from "../generated/ast.js";
+
+/**
+ * The dotted name an expression spells, such as `http.get` or
+ * `data.faker.uuid`.
+ *
+ * The parser cannot tell a namespace from a field: `res.status` and `http.get`
+ * are the same shape. Only a registry knows which is which, so the name is
+ * carried this far as text and asked about there.
+ *
+ * @returns The dotted name, or `undefined` when the expression is not a plain
+ *   chain of identifiers.
+ */
+export function dottedPath(expr: Expr | AstNode | undefined): string | undefined {
+  if (!expr) return undefined;
+  if (isRef(expr)) return expr.name;
+  if (!isMember(expr) || expr.optional) return undefined;
+  const receiver = dottedPath(expr.receiver);
+  return receiver === undefined ? undefined : `${receiver}.${expr.member}`;
+}

package/src/ast/index.ts

@@ -0,0 +1,7 @@
+export type { AstNode } from "langium";
+export { callArgs } from "./call-args.js";
+export { dottedPath } from "./dotted-path.js";
+export { isRunnable } from "./is-statement.js";
+export type { SplitCall } from "./split-call.js";
+export { splitCall } from "./split-call.js";
+export { walkAst } from "./walk.js";

package/src/ast/is-statement.ts

@@ -0,0 +1,40 @@
+import {
+  type Declaration,
+  isConfigDecl,
+  isDatasetDecl,
+  isDecoDecl,
+  isFactoryDecl,
+  isFlowDecl,
+  isFnDecl,
+  isFragmentDecl,
+  isLifecycleDecl,
+  isMatrixDecl,
+  isReportDecl,
+  isTypeDecl,
+  type Statement,
+} from "../generated/ast.js";
+
+/**
+ * Whether a top-level node runs, or merely defines.
+ *
+ * A `flow`, a `fn`, a `type` are definitions: they exist for something else to
+ * reach. Everything else at the top of a file is a statement, and statements
+ * run in the order they are written. That holds in a script, where the file is
+ * the program, and in a test file, so the same lines mean the same thing in
+ * both.
+ */
+export function isRunnable(node: Declaration): node is Declaration & Statement {
+  return !(
+    isFlowDecl(node) ||
+    isFnDecl(node) ||
+    isFragmentDecl(node) ||
+    isTypeDecl(node) ||
+    isFactoryDecl(node) ||
+    isDatasetDecl(node) ||
+    isConfigDecl(node) ||
+    isMatrixDecl(node) ||
+    isReportDecl(node) ||
+    isDecoDecl(node) ||
+    isLifecycleDecl(node)
+  );
+}

package/src/ast/split-call.ts

@@ -0,0 +1,28 @@
+import type { Expr, MapLit } from "../generated/ast.js";
+import { isMapLit } from "../generated/ast.js";
+
+/** A call's arguments, told apart: what it takes, and what configures it. */
+export interface SplitCall {
+  args: readonly Expr[];
+  opts?: MapLit;
+}
+
+/**
+ * Tell a verb's positional arguments from its options map.
+ *
+ * The language spells one call two ways, and the trailing `{ … }` means the
+ * same in both: `http.get "url" { headers }` and `http.get("url", { headers })`
+ * are the same request. Only the first spelling puts the map somewhere the
+ * parser can label, so the second is disambiguated here.
+ *
+ * A map beyond the declared positionals is the options; a map *within* them is
+ * an argument. `db.seed({ users: […] })` passes a map because seeding is what
+ * it does, and that must never be read as configuration.
+ *
+ * @param takes How many positional arguments the verb declares.
+ */
+export function splitCall(args: readonly Expr[], takes: number): SplitCall {
+  const last = args[args.length - 1];
+  if (args.length <= takes || !last || !isMapLit(last)) return { args };
+  return { args: args.slice(0, -1), opts: last };
+}

package/src/ast/walk.ts

@@ -0,0 +1,6 @@
+import { type AstNode, AstUtils } from "langium";
+
+/** Every descendant of `root`, depth-first, for whole-document passes. */
+export function walkAst(root: AstNode): AstNode[] {
+  return AstUtils.streamAllContents(root).toArray();
+}

package/src/codes/build-problem.ts

@@ -0,0 +1,24 @@
+import type { Diff, Problem, RelatedInfo, Span } from "../problem/index.js";
+import type { CodeSpec } from "./code.types.js";
+
+/** Construct a {@link Problem} from a catalog spec plus location and message. */
+export function buildProblem(args: {
+  spec: CodeSpec;
+  span: Span;
+  title: string;
+  help?: string;
+  related?: RelatedInfo[];
+  diff?: Diff;
+  note?: string;
+}): Problem {
+  return {
+    code: args.spec.code,
+    severity: args.spec.severity,
+    title: args.title,
+    span: args.span,
+    help: args.help,
+    related: args.related,
+    diff: args.diff,
+    note: args.note,
+  };
+}

package/src/codes/catalog.ts

@@ -0,0 +1,35 @@
+import type { CodeSpec } from "./code.types.js";
+
+/**
+ * Every VNxxxx the kernel itself can raise. Codes are stable, googlable, and
+ * documented; families follow the leading digit (1 lex/syntax … 8 timeout).
+ */
+export const CODES = {
+  VN1001_LEX: { code: "VN1001", severity: "error" },
+  VN1002_PARSE: { code: "VN1002", severity: "error" },
+  VN2003_UNKNOWN_ACTION: { code: "VN2003", severity: "error" },
+  VN2004_UNKNOWN_MATCHER: { code: "VN2004", severity: "error" },
+  VN2005_UNKNOWN_FRAGMENT: { code: "VN2005", severity: "error" },
+  VN2006_UNKNOWN_ENV: { code: "VN2006", severity: "error" },
+  VN2007_NAMESPACE_NOT_IMPORTED: { code: "VN2007", severity: "error" },
+  VN2008_UNCALLED_ACTION: { code: "VN2008", severity: "error" },
+  VN2009_NOT_EXPORTED: { code: "VN2009", severity: "error" },
+  VN2013_UNKNOWN_DECORATOR: { code: "VN2013", severity: "error" },
+  VN2014_DECORATOR_TARGET: { code: "VN2014", severity: "error" },
+  VN2015_DECO_SIGNATURE: { code: "VN2015", severity: "error" },
+  VN2016_DECO_IMPURE: { code: "VN2016", severity: "error" },
+  VN2017_DECO_VERB: { code: "VN2017", severity: "error" },
+  VN3001_UNKNOWN_OPTION: { code: "VN3001", severity: "error" },
+  VN3010_TYPE_MISMATCH: { code: "VN3010", severity: "error" },
+  VN3012_UNIT_MISMATCH: { code: "VN3012", severity: "error" },
+  VN3013_NOT_CALLABLE: { code: "VN3013", severity: "error" },
+  VN3014_STILL_WAITING: { code: "VN3014", severity: "error" },
+  VN3015_NOT_A_LIST: { code: "VN3015", severity: "error" },
+  VN3016_NOT_A_NUMBER: { code: "VN3016", severity: "error" },
+  VN3017_DECO_ARGUMENTS: { code: "VN3017", severity: "error" },
+  VN5001_REMOVED_KEYWORD: { code: "VN5001", severity: "error" },
+  VN6001_ASSERTION_FAILED: { code: "VN6001", severity: "error" },
+  VN7001_ACTION_FAILED: { code: "VN7001", severity: "error" },
+  VN7004_HOOK_FAILED: { code: "VN7004", severity: "error" },
+  VN8002_LOOP_LIMIT: { code: "VN8002", severity: "error" },
+} as const satisfies Record<string, CodeSpec>;

package/src/codes/code.types.ts

@@ -0,0 +1,7 @@
+import type { Severity } from "../problem/index.js";
+
+/** A catalog entry: a stable code plus its default severity. */
+export interface CodeSpec {
+  code: string;
+  severity: Severity;
+}

package/src/codes/index.ts

@@ -0,0 +1,3 @@
+export { buildProblem } from "./build-problem.js";
+export { CODES } from "./catalog.js";
+export type { CodeSpec } from "./code.types.js";

package/src/compile/compile.ts

@@ -0,0 +1,169 @@
+/**
+ * Expression compilation: a tree becomes a function of the environment.
+ *
+ * A program's tree is fixed once parsed, so every decision the source settles
+ * (which operator, which literal value, which slot a name lives in, how a
+ * string splits around its placeholders) is made once here instead of on every
+ * visit.
+ */
+
+import type { Cell } from "../expr/cell.types.js";
+import type { Closure } from "../expr/closure.types.js";
+import type { EvalEnv } from "../expr/eval-env.types.js";
+import type { Frame } from "../expr/frame.js";
+import type { Expr, FnDecl } from "../generated/ast.js";
+import type { Compile, Thunk } from "./compile.types.js";
+import { freeSlot, type LexScope, rootScope } from "./lex-scope.js";
+import {
+  closureIn,
+  compileBinary,
+  compileCall,
+  compileFnExpr,
+  compileIndex,
+  compileInstant,
+  compileList,
+  compileMap,
+  compileMember,
+  compileNumber,
+  compileString,
+  compileTernary,
+  compileUnary,
+  constant,
+  constThunk,
+} from "./nodes/index.js";
+
+const ROOT = rootScope();
+
+/**
+ * Compile an expression into a function of the environment.
+ *
+ * Memoised per node, so asking twice for the same expression hands back the
+ * same thunk.
+ *
+ * @returns A thunk: give it an environment and it produces the value.
+ */
+export function compileExpr(expr: Expr): Thunk {
+  return compileIn(expr, ROOT);
+}
+
+/**
+ * Build the function value for a top-level `fn name(…)`.
+ *
+ * The body is compiled against `env`, which is what lets a recursive
+ * declaration reach its own name: the cell is handed out before the binding
+ * that fills it exists.
+ *
+ * @returns The closure, ready to be bound under the declaration's name.
+ */
+export function closureOfDecl(decl: FnDecl, env: EvalEnv): Closure {
+  return closureIn(decl, env, compileIn);
+}
+
+function compileIn(expr: Expr, scope: LexScope): Thunk {
+  const known = scope.cache.get(expr);
+  if (known) return known;
+  const thunk = dispatch(expr, scope);
+  scope.cache.set(expr, thunk);
+  return thunk;
+}
+
+const NOTHING: Thunk = () => undefined;
+
+function dispatch(expr: Expr, scope: LexScope): Thunk {
+  switch (expr.$type) {
+    case "NumberLit":
+      return compileNumber(expr);
+    case "StringLit":
+      // A placeholder compiles in the scope that holds it, so `"${i}"` inside a
+      // function reads `i` as that function's slot rather than asking for it by
+      // name. Its parsed expression is shared by every literal with the same
+      // text, which is safe only because the compiled form is cached per scope:
+      // two scopes reach the same node and each keeps its own thunk for it.
+      return compileString(expr, (inner) => compileIn(inner, scope));
+    case "InstantLit":
+      return compileInstant(expr);
+    case "BoolLit":
+      return constant(expr.value === "true");
+    case "NullLit":
+      return constant(null);
+    case "Ref":
+      return compileRef(expr.name, scope);
+    case "FnExpr":
+      // A function made here captures this environment to reach the names
+      // around it, so there has to be one for it to capture.
+      scope.dynamic = true;
+      return compileFnExpr(expr, compileIn);
+    default:
+      return operation(expr, (inner) => compileIn(inner, scope));
+  }
+}
+
+function operation(expr: Expr, compile: Compile): Thunk {
+  switch (expr.$type) {
+    case "Member":
+      return compileMember(expr, compile);
+    case "FnExpr":
+      return compileFnExpr(expr, compileIn);
+    case "Call":
+      return compileCall(expr, compile);
+    case "Index":
+      return compileIndex(expr, compile);
+    case "Binary":
+      return compileBinary(expr, compile);
+    case "Unary":
+      return compileUnary(expr, compile);
+    case "Ternary":
+      return compileTernary(expr, compile);
+    case "ListLit":
+      return compileList(expr, compile);
+    case "MapLit":
+      return compileMap(expr, compile);
+    default:
+      // Not a node the grammar can produce: the only one left is the value a
+      // decorator's `.setValue` put here.
+      return constThunk(expr) ?? NOTHING;
+  }
+}
+
+/**
+ * Compile a name into the cheapest read available.
+ *
+ * A name the enclosing function binds is an index into the frame. Anything else
+ * (a top-level binding, a namespace, the prelude) is a cell the closure
+ * resolved when it was built, which is an index too.
+ *
+ * The lookup fallback stays for environments that hand out no cells: a function
+ * nested inside another reads its parent's frame, and an expression compiled at
+ * the root has no closure at all.
+ */
+function compileRef(name: string, scope: LexScope): Thunk {
+  const slot = scope.names.indexOf(name);
+  // The one name a bare body binds is the value it was handed, unwrapped.
+  if (slot === 0 && scope.bare) return (env) => env;
+  if (slot !== -1) return slotThunk(slot);
+  // One closure owns this body, so the cell can be held right here: no frame to
+  // carry it, and no chain to walk.
+  const own = scope.cellOf?.(name);
+  if (own) return () => own.value;
+  const up = freeSlot(scope, name);
+  if (up === undefined) return (env) => env.lookup(name);
+  return (env) => {
+    const cells = (env as Frame).up;
+    return cells === undefined ? env.lookup(name) : (cells[up] as Cell).value;
+  };
+}
+
+/**
+ * Reading one slot, written for the slot it reads.
+ *
+ * The first three are fields of the frame, so each gets a thunk naming that
+ * field outright: one property load, and the same one every time this thunk
+ * runs, which is what lets V8 settle the site.
+ */
+function slotThunk(slot: number): Thunk {
+  if (slot === 0) return (env) => (env as Frame).s0;
+  if (slot === 1) return (env) => (env as Frame).s1;
+  if (slot === 2) return (env) => (env as Frame).s2;
+  const at = slot - 3;
+  return (env) => ((env as Frame).rest as unknown[])[at];
+}

package/src/compile/compile.types.ts

@@ -0,0 +1,40 @@
+import type { EvalEnv } from "../expr/eval-env.types.js";
+import type { Expr } from "../generated/ast.js";
+
+/**
+ * A compiled expression: everything the source decided is already captured, so
+ * running it needs only the environment.
+ */
+export type Thunk = (env: EvalEnv) => unknown;
+
+/**
+ * Compile a sub-expression.
+ *
+ * Passed into each node's compiler rather than imported, so a compiler for one
+ * kind of node never depends on the dispatcher that reaches it.
+ */
+export type Compile = (expr: Expr) => Thunk;
+
+/** A function body, compiled: its local bindings in order, then its result. */
+export interface CompiledBody {
+  /** Every name that gets a slot: the parameters first, then the locals. */
+  readonly names: readonly string[];
+  /** How many names spill past the frame's inline slots. Usually none. */
+  readonly extra: number;
+  /** Every name the body reads but does not bind, in cell order. */
+  readonly free: readonly string[];
+  /**
+   * The body binds one name, reads nothing else, and asks for nothing by text,
+   * so a call hands the argument straight to `result` with no frame between.
+   */
+  readonly bare: boolean;
+  readonly locals: readonly CompiledLocal[];
+  readonly result: Thunk;
+}
+
+/** One of the body's `let` bindings, compiled. Filled in declaration order. */
+export interface CompiledLocal {
+  /** Which slot of the frame this local writes to. */
+  readonly slot: number;
+  readonly value: Thunk;
+}

package/src/compile/index.ts

@@ -0,0 +1,3 @@
+export { closureOfDecl, compileExpr } from "./compile.js";
+export type { Compile, CompiledBody, CompiledLocal, Thunk } from "./compile.types.js";
+export { constLit } from "./nodes/index.js";

package/src/compile/lex-scope.ts

@@ -0,0 +1,78 @@
+import type { Cell } from "../expr/cell.types.js";
+import type { Expr, FnBody, ParamList } from "../generated/ast.js";
+import type { Thunk } from "./compile.types.js";
+
+/**
+ * What the compiler knows by name at one point in the source: the parameters
+ * and locals of the function being compiled, in slot order.
+ *
+ * Only the *current* function. A name from an enclosing one is left dynamic:
+ * resolving across frames would mean walking a chain at run time, which is the
+ * cost slots exist to remove.
+ */
+export interface LexScope {
+  readonly names: readonly string[];
+  /**
+   * Compiled nodes for this scope. Per scope, not global: a placeholder's
+   * expression is shared between every string literal with the same text, so a
+   * single cache would hand one scope's slot numbers to another.
+   */
+  readonly cache: WeakMap<Expr, Thunk>;
+  /**
+   * Names the body reads but does not bind, in the order they were first seen.
+   * Each becomes a cell the closure resolves once, so reading one costs an
+   * index rather than a walk up the environment chain.
+   *
+   * Absent at the root, where there is no closure to hold the cells and a
+   * shared list would grow across every program the process ever compiles.
+   */
+  readonly free?: string[];
+  /**
+   * This body binds one name and nothing else, so the value bound to it *is*
+   * the environment: there is no frame, and reading the parameter is reading
+   * the argument. Set optimistically and withdrawn by whoever compiled the body
+   * if it turns out to need an environment after all.
+   */
+  bare?: boolean;
+  /** The body asks for some name as text, so it needs a real environment. */
+  dynamic?: boolean;
+  /**
+   * The cell a free name resolves to, when this body belongs to exactly one
+   * closure and so may hold cells of its own. Absent for a `fn (…) => …`, whose
+   * compiled body is shared by every closure the expression produces.
+   */
+  cellOf?: (name: string) => Cell;
+}
+
+/** Outside any function: every name is looked up by asking the environment. */
+export function rootScope(): LexScope {
+  return { names: [], cache: new WeakMap() };
+}
+
+/**
+ * The scope inside a function: its parameters, then its locals. A local that
+ * repeats a parameter's name takes that slot, the way an assignment would.
+ */
+export function scopeOf(params: ParamList | undefined, body: FnBody): LexScope {
+  const names: string[] = (params?.params ?? []).map((param) => param.name);
+  for (const local of body.locals) {
+    if (!names.includes(local.name)) names.push(local.name);
+  }
+  // Worth trying without a frame: one name, and nothing bound after it.
+  const bare = names.length === 1 && body.locals.length === 0;
+  return { names, cache: new WeakMap(), free: [], bare };
+}
+
+/** Whether a body compiled optimistically can keep doing without a frame. */
+export function stayedBare(scope: LexScope): boolean {
+  return Boolean(scope.bare) && !scope.dynamic && (scope.free?.length ?? 0) === 0;
+}
+
+/** Where a free name sits in this scope's cell list, adding it if new. */
+export function freeSlot(scope: LexScope, name: string): number | undefined {
+  const free = scope.free;
+  if (!free) return undefined;
+  const at = free.indexOf(name);
+  if (at !== -1) return at;
+  return free.push(name) - 1;
+}

package/src/compile/nodes/binary.ts

@@ -0,0 +1,56 @@
+import { applyBinary, negate } from "../../expr/operators.js";
+import { isWaiting } from "../../expr/pending.js";
+import type { Binary, Unary } from "../../generated/ast.js";
+import { isNumeric, truthy } from "../../value/index.js";
+import type { Compile, Thunk } from "../compile.types.js";
+import { FAST_BINARY } from "./fast-binary.js";
+
+/** A binary operation, with its operator resolved at compile time. */
+export function compileBinary(expr: Binary, compile: Compile): Thunk {
+  const op = expr.operator;
+  if (op === "&&" || op === "||" || op === "??") return compileLogical(op, expr, compile);
+  const left = compile(expr.left);
+  const right = compile(expr.right);
+  // Two plain numbers take the short way, in a thunk written for this operator
+  // alone; anything else falls back to units.
+  const fast = FAST_BINARY[op];
+  if (fast) return fast(left, right);
+  return (env) => applyBinary(op, left(env), right(env));
+}
+
+function compileLogical(op: string, expr: Binary, compile: Compile): Thunk {
+  const left = compile(expr.left);
+  const right = compile(expr.right);
+  // The left side is evaluated once and kept: an action can sit in expression
+  // position, and running it twice would be a second request.
+  if (op === "&&")
+    return (env) => {
+      const a = left(env);
+      return truthy(a) ? right(env) : a;
+    };
+  if (op === "||")
+    return (env) => {
+      const a = left(env);
+      return truthy(a) ? a : right(env);
+    };
+  return (env) => left(env) ?? right(env);
+}
+
+/** `!x` and `-x`, taking the settled value straight through when it is one. */
+export function compileUnary(expr: Unary, compile: Compile): Thunk {
+  const operand = compile(expr.operand);
+  if (expr.operator === "!") {
+    return (env) => {
+      const value = operand(env);
+      return isWaiting(value) ? value.then((v) => !truthy(v)) : !truthy(value);
+    };
+  }
+  return (env) => {
+    const value = operand(env);
+    return isWaiting(value) ? value.then(negated) : negated(value);
+  };
+}
+
+function negated(value: unknown): unknown {
+  return isNumeric(value) ? negate(value) : -Number(value);
+}

package/src/compile/nodes/call.ts

@@ -0,0 +1,50 @@
+import { invoke, invoke1 } from "../../expr/invoke.js";
+import { isWaiting, whenAllReady, whenBothReady } from "../../expr/pending.js";
+import type { Call } from "../../generated/ast.js";
+import type { Compile, Thunk } from "../compile.types.js";
+
+/**
+ * A call, with its argument list compiled.
+ *
+ * A call is the hottest thing a program does, so the common arities get their
+ * own thunk and build the argument array from a literal rather than with `map`.
+ */
+export function compileCall(expr: Call, compile: Compile): Thunk {
+  const callee = compile(expr.callee);
+  const args = (expr.args?.args ?? []).map((arg) => compile(arg.value));
+  if (args.length === 0) return (env) => call(callee(env), []);
+  if (args.length === 1) return oneArg(callee, args[0] as Thunk);
+  if (args.length === 2) return twoArgs(callee, args[0] as Thunk, args[1] as Thunk);
+  return (env) =>
+    call(
+      callee(env),
+      args.map((arg) => arg(env)),
+    );
+}
+
+function oneArg(callee: Thunk, first: Thunk): Thunk {
+  return (env) => {
+    const fn = callee(env);
+    const arg = first(env);
+    // The overwhelmingly common shape: nothing is waiting, so the value goes
+    // straight in, with no list built to hold one thing.
+    if (!isWaiting(fn) && !isWaiting(arg)) return invoke1(fn, arg);
+    return call(fn, [arg]);
+  };
+}
+
+function twoArgs(callee: Thunk, first: Thunk, second: Thunk): Thunk {
+  return (env) => {
+    const fn = callee(env);
+    const a = first(env);
+    const b = second(env);
+    if (!isWaiting(fn) && !isWaiting(a) && !isWaiting(b)) return invoke(fn, [a, b]);
+    return call(fn, [a, b]);
+  };
+}
+
+/** Wait for whatever is not here yet: the function, or what it is given. */
+function call(callee: unknown, values: unknown[]): unknown {
+  if (!isWaiting(callee)) return whenAllReady(values, (ready) => invoke(callee, ready));
+  return whenBothReady(callee, Promise.all(values), (fn, ready) => invoke(fn, ready as unknown[]));
+}