@venn-lang/core 0.1.0

package/src/compile/nodes/collection.ts

@@ -0,0 +1,83 @@
+import { isWaiting } from "../../expr/pending.js";
+import type { ListLit, MapLit, Ternary } from "../../generated/ast.js";
+import { truthy } from "../../value/index.js";
+import type { Compile, Thunk } from "../compile.types.js";
+import { UNROLLED_MAP } from "./map-fields.js";
+
+/**
+ * A list literal, built in one pass.
+ *
+ * The values are collected and watched for at the same time: walking the list
+ * again to ask whether anything is waiting would cost a second pass on every
+ * literal, which a program shaping many records feels.
+ */
+export function compileList(expr: ListLit, compile: Compile): Thunk {
+  const items = expr.items.map(compile);
+  return (env) => {
+    const out: unknown[] = [];
+    let waiting = false;
+    for (let at = 0; at < items.length; at += 1) {
+      const value = (items[at] as Thunk)(env);
+      waiting = waiting || isWaiting(value);
+      out.push(value);
+    }
+    return waiting ? Promise.all(out) : out;
+  };
+}
+
+/**
+ * A map literal, filled field by field into an empty object.
+ *
+ * Writing the whole literal at once with computed keys builds faster and is a
+ * trap: the object it makes shares no shape with the next one, so every later
+ * read of a field is slow. Records are built once and read many times, so the
+ * assignment order must stay.
+ */
+export function compileMap(expr: MapLit, compile: Compile): Thunk {
+  // Keys are fixed by the source; only the values are computed.
+  const keys = expr.entries.map((entry) => entry.key);
+  const values = expr.entries.map((entry) => compile(entry.value));
+  const build = UNROLLED_MAP[keys.length];
+  if (build) return build(keys, values, settleFields);
+  return (env) => {
+    const out: Record<string, unknown> = {};
+    let waiting = false;
+    for (let at = 0; at < keys.length; at += 1) {
+      const value = (values[at] as Thunk)(env);
+      waiting = waiting || isWaiting(value);
+      out[keys[at] as string] = value;
+    }
+    return waiting ? settleFields(out, keys) : out;
+  };
+}
+
+/** Replace each field with what it was waiting for, keeping the same shape. */
+async function settleFields(
+  out: Record<string, unknown>,
+  keys: readonly string[],
+): Promise<Record<string, unknown>> {
+  const ready = await Promise.all(keys.map((key) => out[key]));
+  keys.forEach((key, at) => {
+    out[key] = ready[at];
+  });
+  return out;
+}
+
+/**
+ * `cond ? a : b`, branching without allocating to do it.
+ *
+ * Handing the continuation to `whenReady` reads better, but the continuation
+ * closes over `env`, so it costs a fresh function object per evaluation. The
+ * waiting branch pays that willingly: there it is a real suspension, and one
+ * allocation is the least of it.
+ */
+export function compileTernary(expr: Ternary, compile: Compile): Thunk {
+  const condition = compile(expr.condition);
+  const then = compile(expr.then);
+  const otherwise = compile(expr.otherwise);
+  return (env) => {
+    const cond = condition(env);
+    if (!isWaiting(cond)) return truthy(cond) ? then(env) : otherwise(env);
+    return cond.then((ready) => (truthy(ready) ? then(env) : otherwise(env)));
+  };
+}

package/src/compile/nodes/const-lit.ts

@@ -0,0 +1,30 @@
+import type { Expr } from "../../generated/ast.js";
+import type { Thunk } from "../compile.types.js";
+import { constant } from "./literal.js";
+
+/** A value standing where an expression was. Only expansion ever writes one. */
+interface ConstLit {
+  $type: "ConstLit";
+  value: unknown;
+}
+
+const CONST_LIT = "ConstLit";
+
+/**
+ * Wrap a value as an expression node.
+ *
+ * A decorator's `.setValue` binds a value, and the grammar has no node that
+ * holds one: every literal it produces is text still to be read. Expansion
+ * writes this instead, so a changed binding is a change to the tree itself
+ * rather than to a lookup table kept beside it.
+ */
+export function constLit(value: unknown): Expr {
+  return { $type: CONST_LIT, value } as unknown as Expr;
+}
+
+/** The thunk for a node expansion put there, or nothing for anything else. */
+export function constThunk(expr: unknown): Thunk | undefined {
+  const written = expr as ConstLit | undefined;
+  if (written?.$type !== CONST_LIT) return undefined;
+  return constant(written.value);
+}

package/src/compile/nodes/fast-binary.ts

@@ -0,0 +1,71 @@
+import { applyBinary } from "../../expr/operators.js";
+import type { Thunk } from "../compile.types.js";
+
+/**
+ * One thunk builder per arithmetic operator, with the operation written out.
+ *
+ * The repetition is the point. Sharing `(a, b) => a + b` and calling it from
+ * the compiled thunk gives one call site eleven different callees, which is
+ * megamorphic and stops V8 inlining it. Writing `a + b` into each thunk gives
+ * every operator its own site with one callee.
+ *
+ * Two plain numbers take the short way; anything else (units, strings, values
+ * still arriving) falls through to `applyBinary`.
+ */
+export const FAST_BINARY: Readonly<Record<string, (left: Thunk, right: Thunk) => Thunk>> = {
+  "+": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a + b : applyBinary("+", a, b);
+  },
+  "-": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a - b : applyBinary("-", a, b);
+  },
+  "*": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a * b : applyBinary("*", a, b);
+  },
+  "/": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a / b : applyBinary("/", a, b);
+  },
+  "%": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a % b : applyBinary("%", a, b);
+  },
+  "<": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a < b : applyBinary("<", a, b);
+  },
+  "<=": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a <= b : applyBinary("<=", a, b);
+  },
+  ">": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a > b : applyBinary(">", a, b);
+  },
+  ">=": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a >= b : applyBinary(">=", a, b);
+  },
+  "==": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a === b : applyBinary("==", a, b);
+  },
+  "!=": (l, r) => (env) => {
+    const a = l(env);
+    const b = r(env);
+    return typeof a === "number" && typeof b === "number" ? a !== b : applyBinary("!=", a, b);
+  },
+};

package/src/compile/nodes/fn.ts

@@ -0,0 +1,87 @@
+import type { Cell } from "../../expr/cell.types.js";
+import { hasCells } from "../../expr/cell.types.js";
+import { makeClosure } from "../../expr/closure.js";
+import type { Closure } from "../../expr/closure.types.js";
+import type { EvalEnv } from "../../expr/eval-env.types.js";
+import { INLINE_SLOTS } from "../../expr/frame.js";
+import type { FnBody, FnDecl, FnExpr, ParamList } from "../../generated/ast.js";
+import type { CompiledBody, Thunk } from "../compile.types.js";
+import { type LexScope, scopeOf, stayedBare } from "../lex-scope.js";
+
+/** How the dispatcher compiles a sub-expression in a given scope. */
+export type CompileIn = (expr: FnBody["result"], scope: LexScope) => Thunk;
+
+/** `fn (…) => …` as a value: the body is compiled here, not on every evaluation. */
+export function compileFnExpr(expr: FnExpr, compileIn: CompileIn): Thunk {
+  const params = paramNames(expr.params);
+  // No `cellOf`: this body is compiled once and shared by every closure the
+  // expression makes, so it cannot hold cells belonging to one of them.
+  const body = compileBody({ params: expr.params, body: expr.body, compileIn });
+  return (env) => makeClosure(params, body, env);
+}
+
+/**
+ * A top-level `fn name(…)`, bound into a scope.
+ *
+ * This body is compiled per closure, and there is exactly one closure per
+ * declaration, so the cells its free names resolve to can be captured in the
+ * thunks that read them. That is what lets a recursive function keep its own
+ * name without needing an environment to find it in, which in turn is what lets
+ * it run without a frame.
+ */
+export function closureIn(decl: FnDecl, env: EvalEnv, compileIn: CompileIn): Closure {
+  const cellOf = hasCells(env) ? (name: string) => env.cell(name) : undefined;
+  const body = compileBody({ params: decl.params, body: decl.body, compileIn, cellOf });
+  return makeClosure(paramNames(decl.params), body, env);
+}
+
+interface BodyArgs {
+  params: ParamList | undefined;
+  body: FnBody;
+  compileIn: CompileIn;
+  /** Absent when the body is shared by more than one closure. */
+  cellOf?: (name: string) => Cell;
+}
+
+/**
+ * Compile a body, first assuming it needs no frame.
+ *
+ * Whether it does is known only once it has been compiled: a free name needs
+ * cells to reach, and a `"${…}"` asks for names as text. So the optimistic pass
+ * runs and is thrown away when it was wrong, which costs one extra compile of
+ * one body against an allocation saved on every call it will ever receive.
+ */
+function compileBody(args: BodyArgs): CompiledBody {
+  const first = compileInScope(scoped(args), args);
+  if (first.bare || !first.wasBare) return first.compiled;
+  const plain = scoped(args);
+  plain.bare = false;
+  return compileInScope(plain, args).compiled;
+}
+
+function scoped(args: BodyArgs): LexScope {
+  const scope = scopeOf(args.params, args.body);
+  scope.cellOf = args.cellOf;
+  return scope;
+}
+
+function compileInScope(
+  scope: LexScope,
+  args: BodyArgs,
+): { compiled: CompiledBody; bare: boolean; wasBare: boolean } {
+  const { body, compileIn } = args;
+  const wasBare = Boolean(scope.bare);
+  const locals = body.locals.map((local) => ({
+    slot: scope.names.indexOf(local.name),
+    value: compileIn(local.value, scope),
+  }));
+  const result = compileIn(body.result, scope);
+  const bare = stayedBare(scope);
+  const extra = Math.max(0, scope.names.length - INLINE_SLOTS);
+  const free = scope.free ?? [];
+  return { compiled: { names: scope.names, extra, free, locals, result, bare }, bare, wasBare };
+}
+
+function paramNames(params: ParamList | undefined): readonly string[] {
+  return (params?.params ?? []).map((param) => param.name);
+}

package/src/compile/nodes/index.ts

@@ -0,0 +1,8 @@
+export { compileBinary, compileUnary } from "./binary.js";
+export { compileCall } from "./call.js";
+export { compileList, compileMap, compileTernary } from "./collection.js";
+export { constLit, constThunk } from "./const-lit.js";
+export type { CompileIn } from "./fn.js";
+export { closureIn, compileFnExpr } from "./fn.js";
+export { compileInstant, compileNumber, compileString, constant } from "./literal.js";
+export { compileIndex, compileMember } from "./member.js";

package/src/compile/nodes/literal.ts

@@ -0,0 +1,86 @@
+import { buildProblem, CODES } from "../../codes/index.js";
+import { isWaiting } from "../../expr/pending.js";
+import type { NumberLit, StringLit } from "../../generated/ast.js";
+import { compileTemplate, type TemplateHole } from "../../interpolation/index.js";
+import { ProblemError } from "../../problem/index.js";
+import { isUnitValue, parseInstant, parseNumber, type UnitValue } from "../../units/index.js";
+import type { Compile, Thunk } from "../compile.types.js";
+
+const NO_SPAN = { uri: "", offset: 0, length: 0, line: 1, column: 1 };
+
+/** A literal is a constant: read the lexeme once, then hand back the value. */
+export function constant(value: unknown): Thunk {
+  return () => value;
+}
+
+export function compileNumber(expr: NumberLit): Thunk {
+  return constant(parseNumber(expr.raw));
+}
+
+export function compileInstant(expr: { value: string }): Thunk {
+  return constant(parseInstant(expr.value));
+}
+
+/**
+ * A string with no `${…}` is a constant. One with placeholders becomes the
+ * literal chunks plus a compiled thunk per hole: the scanning, the parsing and
+ * the splitting all happen here, never again.
+ */
+export function compileString(expr: StringLit, compile: Compile): Thunk {
+  const { chunks, holes } = compileTemplate(expr.value);
+  if (holes.length === 0) return constant(expr.value);
+  const fills = holes.map((hole) => compileHole(hole, compile));
+  // Filled in one pass, watching as it goes for a placeholder still arriving.
+  // `map` with a continuation reads better but builds two function objects per
+  // evaluation, both closing over `env`. The values still land in an array
+  // because a hole cannot be evaluated twice: one of them may be an action.
+  return (env) => {
+    const values = new Array<unknown>(fills.length);
+    let waiting = false;
+    for (let at = 0; at < fills.length; at += 1) {
+      const value = (fills[at] as Thunk)(env);
+      waiting = waiting || isWaiting(value);
+      values[at] = value;
+    }
+    return waiting ? settleJoin(chunks, values) : join(chunks, values);
+  };
+}
+
+/** The waiting path: every hole settled, then the same join. */
+async function settleJoin(chunks: readonly string[], values: unknown[]): Promise<string> {
+  return join(chunks, await Promise.all(values));
+}
+
+function join(chunks: readonly string[], values: readonly unknown[]): string {
+  let out = chunks[0] ?? "";
+  for (let at = 0; at < values.length; at += 1) {
+    out += stringify(values[at]) + (chunks[at + 1] ?? "");
+  }
+  return out;
+}
+
+/** A placeholder that does not parse is a mistake worth reporting, not an empty string. */
+function compileHole(hole: TemplateHole, compile: Compile): Thunk {
+  if (hole.expr) return compile(hole.expr);
+  return () => {
+    throw new ProblemError(
+      buildProblem({
+        spec: CODES.VN1002_PARSE,
+        span: NO_SPAN,
+        title: `Cannot read \`\${${hole.source}}\` — that is not an expression.`,
+      }),
+    );
+  };
+}
+
+function stringify(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (isUnitValue(value)) return stringifyUnit(value);
+  return String(value);
+}
+
+function stringifyUnit(value: UnitValue): string {
+  if (value.kind === "duration") return `${value.ms}ms`;
+  if (value.kind === "size") return `${value.bytes}b`;
+  return `${value.ratio * 100}%`;
+}

package/src/compile/nodes/map-fields.ts

@@ -0,0 +1,79 @@
+import { isWaiting } from "../../expr/pending.js";
+import type { Thunk } from "../compile.types.js";
+
+/** Replace each field with what it was waiting for, keeping the same shape. */
+type Settle = (out: Record<string, unknown>, keys: readonly string[]) => Promise<unknown>;
+
+/** How a map of a known size is built, given its keys and its value thunks. */
+type Build = (keys: readonly string[], values: readonly Thunk[], settle: Settle) => Thunk;
+
+/**
+ * Map literals of the everyday sizes, with the loop written out.
+ *
+ * The object is still made empty and filled by assignment, which is what gives
+ * every map from one site the same shape and so makes reading a field fast.
+ * What goes is the loop: reading `keys[at]` and `values[at]` per field, and
+ * carrying a flag for whether anything was waiting.
+ *
+ * Writing the literal in one go (`{ [k0]: a, [k1]: b }`) is faster to build and
+ * much slower to read, because those objects share no shape with each other.
+ * Records are built once and read many times, so it is the wrong trade.
+ */
+export const UNROLLED_MAP: Readonly<Record<number, Build>> = {
+  1: (keys, values, settle) => {
+    const k0 = keys[0] as string;
+    const v0 = values[0] as Thunk;
+    return (env) => {
+      const a = v0(env);
+      const out: Record<string, unknown> = {};
+      out[k0] = a;
+      return isWaiting(a) ? settle(out, keys) : out;
+    };
+  },
+  2: (keys, values, settle) => {
+    const [k0, k1] = keys as [string, string];
+    const [v0, v1] = values as [Thunk, Thunk];
+    return (env) => {
+      const a = v0(env);
+      const b = v1(env);
+      const out: Record<string, unknown> = {};
+      out[k0] = a;
+      out[k1] = b;
+      return isWaiting(a) || isWaiting(b) ? settle(out, keys) : out;
+    };
+  },
+  3: (keys, values, settle) => {
+    const [k0, k1, k2] = keys as [string, string, string];
+    const [v0, v1, v2] = values as [Thunk, Thunk, Thunk];
+    return (env) => {
+      const a = v0(env);
+      const b = v1(env);
+      const c = v2(env);
+      const out: Record<string, unknown> = {};
+      out[k0] = a;
+      out[k1] = b;
+      out[k2] = c;
+      return isWaiting(a) || isWaiting(b) || isWaiting(c) ? settle(out, keys) : out;
+    };
+  },
+  4: (keys, values, settle) => {
+    const [k0, k1, k2, k3] = keys as [string, string, string, string];
+    const [v0, v1, v2, v3] = values as [Thunk, Thunk, Thunk, Thunk];
+    return (env) => {
+      const a = v0(env);
+      const b = v1(env);
+      const c = v2(env);
+      const d = v3(env);
+      const out: Record<string, unknown> = {};
+      out[k0] = a;
+      out[k1] = b;
+      out[k2] = c;
+      out[k3] = d;
+      return waiting4(a, b, c, d) ? settle(out, keys) : out;
+    };
+  },
+};
+
+function waiting4(a: unknown, b: unknown, c: unknown, d: unknown): boolean {
+  return isWaiting(a) || isWaiting(b) || isWaiting(c) || isWaiting(d);
+}

package/src/compile/nodes/member.ts

@@ -0,0 +1,32 @@
+import { memberValue } from "../../expr/member-value.js";
+import { isWaiting, whenBothReady } from "../../expr/pending.js";
+import type { Index, Member } from "../../generated/ast.js";
+import type { Compile, Thunk } from "../compile.types.js";
+
+/** `x.member`, with the member name fixed by the source. */
+export function compileMember(expr: Member, compile: Compile): Thunk {
+  const receiver = compile(expr.receiver);
+  const member = expr.member;
+  return (env) => memberValue(receiver(env), member);
+}
+
+/**
+ * `xs[i]`, reading straight through when neither side is still arriving.
+ *
+ * Indexing `null` gives undefined rather than throwing, so a missing path along
+ * a chain reads as absent instead of stopping the flow.
+ */
+export function compileIndex(expr: Index, compile: Compile): Thunk {
+  const receiver = compile(expr.receiver);
+  const key = compile(expr.index);
+  return (env) => {
+    const target = receiver(env);
+    const at = key(env);
+    if (!isWaiting(target) && !isWaiting(at)) return elementAt(target, at);
+    return whenBothReady(target, at, elementAt);
+  };
+}
+
+function elementAt(target: unknown, at: unknown): unknown {
+  return target == null ? undefined : (target as Record<string, unknown>)[at as string];
+}

package/src/events/envelope.types.ts

@@ -0,0 +1,17 @@
+import type { EventData, EventKind } from "./event-data.types.js";
+import type { NodePath, RunId } from "./ids.types.js";
+
+/** The single contract between runner, host, and UI. Everything else derives from it. */
+export interface Envelope<K extends EventKind = EventKind> {
+  /** Monotonic per run; the UI detects a gap and asks for a resync. */
+  seq: number;
+  /** ISO-8601 with milliseconds, from the runner's clock. */
+  ts: string;
+  run: RunId;
+  kind: K;
+  node?: NodePath;
+  parent?: NodePath;
+  /** Which parallel worker emitted this, so interleaved output can be split. */
+  worker?: number;
+  data: EventData[K];
+}

package/src/events/event-data.types.ts

@@ -0,0 +1,25 @@
+import type { Problem } from "../problem/index.js";
+import type { RunPlan } from "./run-plan.types.js";
+import type { Status } from "./status.types.js";
+
+/**
+ * The payload per event kind. EventKind is DERIVED from these keys, so adding an
+ * event is a single edit here. This is the M1 subset of the §15 taxonomy.
+ */
+export interface EventData {
+  "run.started": { plan: RunPlan };
+  "run.finished": { passed: number; failed: number; durationMs: number };
+  "flow.started": { title: string };
+  "flow.finished": { title: string; status: Status };
+  "flow.retrying": { title: string; attempt: number; reason: string };
+  "step.started": { title: string };
+  "step.finished": { title: string; status: Status };
+  "action.started": { namespace: string; action: string };
+  "action.finished": { namespace: string; action: string; status: Status; durationMs: number };
+  "expect.passed": { source: string };
+  "expect.failed": { problem: Problem };
+  log: { level: string; message: string };
+}
+
+/** Every event name, derived from {@link EventData}. */
+export type EventKind = keyof EventData;

package/src/events/ids.types.ts

@@ -0,0 +1,10 @@
+/** A run identifier (ULID). Branded so it is not confused with a plain string. */
+export type RunId = string & { readonly __brand: "RunId" };
+
+/**
+ * A node path derived from `@id`, e.g. "checkout/flow-checkout/step-cart".
+ *
+ * The join key across the node graph, the editor margin, and the execution
+ * tree. Never a numeric index: an edit would silently desync history.
+ */
+export type NodePath = string & { readonly __brand: "NodePath" };

package/src/events/index.ts

@@ -0,0 +1,5 @@
+export type { Envelope } from "./envelope.types.js";
+export type { EventData, EventKind } from "./event-data.types.js";
+export type { NodePath, RunId } from "./ids.types.js";
+export type { PlannedFlow, PlannedStep, RunPlan } from "./run-plan.types.js";
+export type { Status } from "./status.types.js";

package/src/events/run-plan.types.ts

@@ -0,0 +1,18 @@
+/** One step of a {@link RunPlan}. */
+export interface PlannedStep {
+  title: string;
+}
+
+/** One flow of a {@link RunPlan}, with the steps it will take. */
+export interface PlannedFlow {
+  title: string;
+  steps: PlannedStep[];
+}
+
+/**
+ * What the run intends to do, carried on `run.started`. The UI draws it in
+ * grey before anything executes, so the shape of the run is visible up front.
+ */
+export interface RunPlan {
+  flows: PlannedFlow[];
+}

package/src/events/status.types.ts

@@ -0,0 +1,2 @@
+/** Where a flow, step or action stands when an event reports it. */
+export type Status = "passed" | "failed" | "skipped" | "running";

package/src/expand/accepted-kinds.ts

@@ -0,0 +1,23 @@
+import type { DecoDecl, Param } from "../generated/ast.js";
+import { isTargetKind, type TargetKind } from "./handles/index.js";
+
+/** The parameter that *is* the target: the first one, always. */
+export function decoTarget(decl: DecoDecl): Param | undefined {
+  return decl.params?.params[0];
+}
+
+/**
+ * The kinds a `deco` decorates, read off the type on its first parameter.
+ *
+ * The signature is the only statement of what a decorator is for; a separate
+ * list of node names would drift from it. Empty means the signature never said
+ * (no parameter, or one typed with something that is not a kind). That fault is
+ * reported where the `deco` is declared, so a use site stays quiet about a
+ * mistake it did not make.
+ *
+ * @returns the kinds the first parameter's type names, in written order.
+ */
+export function acceptedKinds(decl: DecoDecl): readonly TargetKind[] {
+  const written = decoTarget(decl)?.paramType?.members ?? [];
+  return written.map((member) => (member as { name?: string }).name ?? "").filter(isTargetKind);
+}

package/src/expand/deco/deco-decorator.ts

@@ -0,0 +1,77 @@
+import { buildProblem, CODES } from "../../codes/index.js";
+import type { DecoDecl } from "../../generated/ast.js";
+import type { Problem } from "../../problem/index.js";
+import type { DecoratorDefinition, ExpandContext } from "../expand.types.js";
+import { kindOf, makeHandle } from "../handles/index.js";
+import { spanOf } from "../node-span.js";
+import type { DecoSignature } from "./deco.types.js";
+import { DecoEnv } from "./deco-env.js";
+import { readSignature } from "./read-signature.js";
+import { runDecoBody } from "./run-body.js";
+
+/** A `deco` and everything reporting about it needs. */
+interface DecoArgs {
+  decl: DecoDecl;
+  uri: string;
+  problems: Problem[];
+}
+
+/**
+ * A `deco` written in the language, as a decorator the expansion phase applies.
+ *
+ * This is the very {@link DecoratorDefinition} a plugin's TypeScript
+ * `defineDecorator` produces: one mechanism, two doors. What the signature says
+ * it decorates becomes `accepts`, so the type error for `@memoize` on a flow
+ * comes from how the author wrote the parameters rather than from a list kept by
+ * hand beside them.
+ *
+ * @returns a definition that does nothing when the signature does not read. The
+ * reason is pushed onto `args.problems` once, here, rather than at every use.
+ */
+export function decoDecorator(args: DecoArgs): DecoratorDefinition {
+  const read = readSignature(args.decl);
+  if (read.ok) return definition({ ...args, sig: read.signature });
+  args.problems.push(signatureProblem(args, read.title));
+  // Still resolvable, doing nothing: a fault committed once, where the `deco` is
+  // written, must not be repeated at every use of it.
+  return { name: args.decl.name, expand: () => {} };
+}
+
+function definition(args: DecoArgs & { sig: DecoSignature }): DecoratorDefinition {
+  return {
+    name: args.decl.name,
+    accepts: args.sig.kinds,
+    expand: (ctx) => apply({ ...args, ctx }),
+  };
+}
+
+function apply(args: DecoArgs & { sig: DecoSignature; ctx: ExpandContext }): void {
+  const handle = makeHandle({ node: args.ctx.node, kind: kindOf(args.ctx.node) });
+  runDecoBody({
+    body: args.decl.body,
+    env: new DecoEnv(bindings(args.sig, handle, args.ctx.args)),
+    uri: args.uri,
+    reject: (problem) => args.problems.push(problem),
+  });
+}
+
+/** The target under the name the body calls it by, then `@name(…)` in order. */
+function bindings(
+  sig: DecoSignature,
+  handle: unknown,
+  given: readonly unknown[],
+): Record<string, unknown> {
+  const bound: Record<string, unknown> = { [sig.target]: handle };
+  sig.args.forEach((name, at) => {
+    bound[name] = given[at];
+  });
+  return bound;
+}
+
+function signatureProblem(args: DecoArgs, title: string): Problem {
+  return buildProblem({
+    spec: CODES.VN2015_DECO_SIGNATURE,
+    span: spanOf(args.decl, args.uri),
+    title,
+  });
+}