@venn-lang/core 0.1.0

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

@@ -0,0 +1,24 @@
+import type { EvalEnv } from "../../expr/index.js";
+import { PRELUDE_VALUES } from "../../expr/index.js";
+
+/**
+ * What a decorator body can see: its own parameters, its own `let`s, and the
+ * prelude.
+ *
+ * Nothing else, and deliberately so. The body runs before the program exists: no
+ * flow has started and no plugin has been asked for anything, so a name it did
+ * not bind itself cannot mean anything yet. The runner says exactly that instead
+ * of quietly evaluating to nothing.
+ */
+export class DecoEnv implements EvalEnv {
+  constructor(private readonly bindings: Record<string, unknown>) {}
+
+  lookup(name: string): unknown {
+    if (Object.hasOwn(this.bindings, name)) return this.bindings[name];
+    return PRELUDE_VALUES[name];
+  }
+
+  bind(name: string, value: unknown): void {
+    this.bindings[name] = value;
+  }
+}

package/src/expand/deco/deco.types.ts

@@ -0,0 +1,43 @@
+import type { Block, DecoDecl } from "../../generated/ast.js";
+import type { Problem } from "../../problem/index.js";
+import type { TargetKind } from "../handles/index.js";
+import type { DecoEnv } from "./deco-env.js";
+
+/**
+ * A `deco`'s parameter list, read as what it means: the first parameter is the
+ * thing decorated and its type is what may be decorated; the rest are the
+ * decorator's own arguments, bound from `@name(…)`.
+ */
+export interface DecoSignature {
+  /** The name the body calls its target by. */
+  readonly target: string;
+  /** The kinds the declared type allows. Several when it is a union. */
+  readonly kinds: readonly TargetKind[];
+  /** The remaining parameter names, in the order `@name(…)` fills them. */
+  readonly args: readonly string[];
+}
+
+/** A signature that reads, or the one-line reason it does not. */
+export type SignatureResult =
+  | { readonly ok: true; readonly signature: DecoSignature }
+  | { readonly ok: false; readonly title: string };
+
+/**
+ * A `pub deco` another file exported, with the file it was written in.
+ *
+ * The uri travels with the declaration because a fault in it (a signature that
+ * does not read, a verb its kind has not got) belongs to the line that wrote it,
+ * not to the line that imported it.
+ */
+export interface ImportedDeco {
+  readonly decl: DecoDecl;
+  readonly uri: string;
+}
+
+/** Everything running one decorator's body needs. */
+export interface DecoBodyArgs {
+  readonly body: Block;
+  readonly env: DecoEnv;
+  readonly uri: string;
+  readonly reject: (problem: Problem) => void;
+}

package/src/expand/deco/document-decos.ts

@@ -0,0 +1,64 @@
+import type { Document } from "../../generated/ast.js";
+import { isDecoDecl } from "../../generated/ast.js";
+import type { Problem } from "../../problem/index.js";
+import type { DecoratorDefinition, DecoratorSource } from "../expand.types.js";
+import type { ImportedDeco } from "./deco.types.js";
+import { decoDecorator } from "./deco-decorator.js";
+
+/** Every `deco` one document can reach, and the file it is being expanded for. */
+export interface DocumentDecoArgs {
+  document: Document;
+  decorators: DecoratorSource;
+  uri: string;
+  problems: Problem[];
+  /** The `pub deco`s this file's imports reach, by name. */
+  imported?: ReadonlyMap<string, ImportedDeco>;
+}
+
+/**
+ * The document's own `deco`s, then the ones it imported, layered over whatever
+ * the host contributed.
+ *
+ * A local declaration wins against a plugin's and against a built-in of the same
+ * name: the more local one is what the author is looking at. All of them arrive
+ * as ordinary members of one {@link DecoratorSource}, so `@memoize` resolves
+ * without expansion ever asking where a decorator came from.
+ */
+export function withDocumentDecos(args: DocumentDecoArgs): DecoratorSource {
+  const own = ownDecos(args);
+  const shared = sharedDecos(args);
+  if (own.size === 0 && !shared) return args.decorators;
+  return { get: (name) => own.get(name) ?? shared?.(name) ?? args.decorators.get(name) };
+}
+
+/** Built up front: a signature that does not read is reported where it is written. */
+function ownDecos(args: DocumentDecoArgs): Map<string, DecoratorDefinition> {
+  const own = new Map<string, DecoratorDefinition>();
+  for (const decl of args.document.decls) {
+    if (isDecoDecl(decl)) own.set(decl.name, decoDecorator({ ...args, decl }));
+  }
+  return own;
+}
+
+type Found = DecoratorDefinition | undefined;
+
+/**
+ * Built on first use, and remembered.
+ *
+ * An imported file exports every `pub deco` it has, and this one may write none
+ * of them: reading a signature nobody asked for would charge another file's
+ * fault to this one, for a decorator that was never applied.
+ */
+function sharedDecos(args: DocumentDecoArgs): ((name: string) => Found) | undefined {
+  const imported = args.imported;
+  if (!imported || imported.size === 0) return undefined;
+  const built = new Map<string, Found>();
+  return (name) => {
+    if (built.has(name)) return built.get(name);
+    const from = imported.get(name);
+    // Its own uri, so a fault in it points at the line that wrote it.
+    const made = from && decoDecorator({ ...args, decl: from.decl, uri: from.uri });
+    built.set(name, made);
+    return made;
+  };
+}

package/src/expand/deco/index.ts

@@ -0,0 +1,7 @@
+export type { DecoBodyArgs, DecoSignature, ImportedDeco, SignatureResult } from "./deco.types.js";
+export { decoDecorator } from "./deco-decorator.js";
+export { DecoEnv } from "./deco-env.js";
+export type { DocumentDecoArgs } from "./document-decos.js";
+export { withDocumentDecos } from "./document-decos.js";
+export { readSignature } from "./read-signature.js";
+export { impure as decoCannotCall, runDecoBody } from "./run-body.js";

package/src/expand/deco/read-signature.ts

@@ -0,0 +1,57 @@
+import type { DecoDecl, Param, TypeRef } from "../../generated/ast.js";
+import { acceptedKinds, decoTarget } from "../accepted-kinds.js";
+import type { TargetKind } from "../handles/index.js";
+import { everyKindWritten } from "../wrong-kind.js";
+import type { SignatureResult } from "./deco.types.js";
+
+/**
+ * Read a `deco`'s parameters as what they mean.
+ *
+ * The first parameter *is* the target and its type is what may carry the
+ * decorator; the rest are the decorator's own arguments, filled by `@name(…)` in
+ * order. Nobody writing a decorator ever names a node of the compiler's tree,
+ * and what it decorates follows from the signature rather than from a list kept
+ * beside it.
+ *
+ * @returns the signature, or the one-line reason it does not read.
+ */
+export function readSignature(decl: DecoDecl): SignatureResult {
+  const target = decoTarget(decl);
+  if (!target) return { ok: false, title: needsTarget(decl.name) };
+  if (!target.paramType) return { ok: false, title: needsType(decl.name, target.name) };
+  const kinds = acceptedKinds(decl);
+  // A union may name several kinds; one word that is not a kind spoils it all.
+  if (kinds.length !== target.paramType.members.length) {
+    return { ok: false, title: notAKind(decl.name, target.paramType) };
+  }
+  return signature(target, kinds, decl.params?.params ?? []);
+}
+
+function signature(
+  target: Param,
+  kinds: readonly TargetKind[],
+  params: readonly Param[],
+): SignatureResult {
+  return {
+    ok: true,
+    signature: { target: target.name, kinds, args: params.slice(1).map((one) => one.name) },
+  };
+}
+
+function written(type: TypeRef): string {
+  return type.members.map((member) => (member as { name?: string }).name ?? "?").join(" | ");
+}
+
+function needsTarget(name: string): string {
+  return `\`deco ${name}\` needs a first parameter — the thing it decorates.`;
+}
+
+function needsType(name: string, target: string): string {
+  const kinds = everyKindWritten();
+  return `\`deco ${name}\` must say what it decorates: give \`${target}\` a type — ${kinds}.`;
+}
+
+function notAKind(name: string, type: TypeRef): string {
+  const kinds = everyKindWritten();
+  return `\`deco ${name}\` decorates \`${written(type)}\`, which is not a kind — say ${kinds}.`;
+}

package/src/expand/deco/run-body.ts

@@ -0,0 +1,119 @@
+import type { AstNode } from "langium";
+import { callArgs } from "../../ast/index.js";
+import { buildProblem, CODES } from "../../codes/index.js";
+import { evaluate, invoke, memberValue } from "../../expr/index.js";
+import type { ActionCall, Block, IfStmt, LetStmt, Statement } from "../../generated/ast.js";
+import { type Problem, ProblemError } from "../../problem/index.js";
+import { truthy } from "../../value/index.js";
+import { handleSurface, missingVerb } from "../handles/index.js";
+import { spanOf } from "../node-span.js";
+import type { DecoBodyArgs } from "./deco.types.js";
+
+/**
+ * Run a decorator's body, at expansion time, over the handle it was given.
+ *
+ * It understands `let`/`const`, `if`, and a call on something it can already
+ * see. Nothing else, because nothing else exists yet: a call whose head it
+ * cannot find is a plugin's verb, and saying so is more use than a lookup that
+ * quietly yields nothing and a `TypeError` two lines later.
+ *
+ * Nothing is thrown. Every refusal reaches `args.reject` as a `Problem` pointing
+ * at the statement that caused it.
+ */
+export function runDecoBody(args: DecoBodyArgs): void {
+  runStmts(args.body.stmts, args);
+}
+
+function runStmts(stmts: readonly Statement[], args: DecoBodyArgs): void {
+  for (const stmt of stmts) {
+    try {
+      dispatch(stmt, args);
+    } catch (error) {
+      args.reject(located(error, stmt, args.uri));
+    }
+  }
+}
+
+function dispatch(stmt: Statement, args: DecoBodyArgs): void {
+  if (stmt.$type === "LetStmt") {
+    bind(stmt as LetStmt, args);
+  } else if (stmt.$type === "ActionCall") {
+    callVerb(stmt as ActionCall, args);
+  } else if (stmt.$type === "IfStmt") {
+    branch(stmt as IfStmt, args);
+  } else {
+    throw refuse(UNSUPPORTED);
+  }
+}
+
+/** `const cache = {}`. Trailing arguments would make it an action, which it cannot be. */
+function bind(stmt: LetStmt, args: DecoBodyArgs): void {
+  if (stmt.args.length > 0 || stmt.opts) throw refuse(IMPURE_LET);
+  args.env.bind(stmt.name, evaluate(stmt.value, args.env));
+}
+
+/** `target.wrap(f)`, `target.meta "retry" 3`: a verb on something already in hand. */
+function callVerb(stmt: ActionCall, args: DecoBodyArgs): void {
+  const path = stmt.target.split(".");
+  const root = args.env.lookup(path[0] as string);
+  if (root === undefined) throw refuse(impure(stmt.target));
+  const callee = path.slice(1).reduce<unknown>(reach, root);
+  invoke(callee, values(stmt, args));
+}
+
+/** A handle answers only to its own verbs; anything else is refused by name. */
+function reach(held: unknown, name: string): unknown {
+  const surface = handleSurface(held);
+  if (surface && !surface.offered.includes(name)) {
+    throw missingVerb({ verb: name, kind: surface.kind, offered: surface.offered });
+  }
+  return memberValue(held, name);
+}
+
+function values(stmt: ActionCall, args: DecoBodyArgs): unknown[] {
+  const given = callArgs(stmt).map((arg) => evaluate(arg, args.env));
+  if (stmt.opts) given.push(evaluate(stmt.opts, args.env));
+  return given;
+}
+
+function branch(stmt: IfStmt, args: DecoBodyArgs): void {
+  if (truthy(evaluate(stmt.cond, args.env))) {
+    runStmts(stmt.then.stmts, args);
+    return;
+  }
+  const other = stmt.otherwise;
+  if (!other) return;
+  // `else if` is another statement; a plain `else` is a block of them.
+  if (other.$type === "Block") runStmts((other as Block).stmts, args);
+  else dispatch(other as Statement, args);
+}
+
+const IMPURE_LET =
+  "A decorator runs before the program exists, so this binding cannot call an action.";
+
+const UNSUPPORTED =
+  "A decorator body understands `let`, `const`, `if` and verbs on what it was given — this is none of them.";
+
+/**
+ * The one sentence for a verb a decorator cannot reach.
+ *
+ * Exported because the static pass notices the same thing without ever running
+ * the body, and two wordings for one fact is how they start to disagree.
+ */
+export function impure(target: string): string {
+  return `A decorator runs before the program exists, so it cannot call \`${target}\`.`;
+}
+
+/** Located later, by the statement that asked. */
+const NO_SPAN = { uri: "", offset: 0, length: 0, line: 1, column: 1 };
+
+function refuse(title: string): ProblemError {
+  return new ProblemError(buildProblem({ spec: CODES.VN2016_DECO_IMPURE, span: NO_SPAN, title }));
+}
+
+/** Whatever went wrong, pointed at the line of the body that asked for it. */
+function located(error: unknown, stmt: AstNode, uri: string): Problem {
+  if (error instanceof ProblemError) return { ...error.problem, span: spanOf(stmt, uri) };
+  const title = (error as { message?: string })?.message ?? String(error);
+  return buildProblem({ spec: CODES.VN2016_DECO_IMPURE, span: spanOf(stmt, uri), title });
+}

package/src/expand/decorate-callable.ts

@@ -0,0 +1,49 @@
+import { invoke, nativeFn } from "../expr/index.js";
+import { type Decorations, readDecorations } from "./decorations.js";
+
+/** A call, reduced to the one thing a middleware needs: values in, value out. */
+type Call = (values: readonly unknown[]) => unknown;
+
+/**
+ * The callable a decorated `fn` binds to: its own body with every `.wrap`,
+ * `.before` and `.after` a `deco` asked for already around it.
+ *
+ * An untouched function is handed straight back, so nothing pays for a feature
+ * it did not use.
+ */
+export function decorateCallable(node: object, base: unknown): unknown {
+  const around = readDecorations(node);
+  if (!around) return base;
+  const chain = wrapChain(around.wrap, base);
+  return nativeFn((values) => aroundCall({ chain, around, values }));
+}
+
+function aroundCall(args: {
+  chain: Call;
+  around: Decorations;
+  values: readonly unknown[];
+}): unknown {
+  for (const fn of args.around.before) invoke(fn, [args.values]);
+  const result = args.chain(args.values);
+  for (const fn of args.around.after) invoke(fn, [args.values, result]);
+  return result;
+}
+
+/** The first-written wrap ends up outermost: it decides whether the rest runs. */
+function wrapChain(wraps: readonly unknown[], base: unknown): Call {
+  let next: Call = (values) => invoke(base, values);
+  for (let at = wraps.length - 1; at >= 0; at -= 1) next = oneWrap(wraps[at], next);
+  return next;
+}
+
+function oneWrap(wrap: unknown, inner: Call): Call {
+  const through = nativeFn((given) => inner(passedOn(given)));
+  return (values) => invoke(wrap, [through, values]);
+}
+
+/** `call(args)` passes the list straight along; `call(a, b)` passes both. */
+function passedOn(given: readonly unknown[]): readonly unknown[] {
+  const first = given[0];
+  if (given.length === 1 && Array.isArray(first)) return first;
+  return given;
+}

package/src/expand/decorations.ts

@@ -0,0 +1,41 @@
+import { readMeta, writeMeta } from "./node-meta.js";
+
+/**
+ * Where `.wrap`, `.before` and `.after` leave their closures.
+ *
+ * Prefixed, because `meta` is open to any key a decorator invents and a program
+ * that writes `target.meta "before" x` must not be mistaken for one that wrote
+ * `target.before(f)`.
+ */
+export const AROUND_KEYS = {
+  wrap: "deco.wrap",
+  before: "deco.before",
+  after: "deco.after",
+} as const;
+
+/** The closures a `deco` asked to run around this declaration. */
+export interface Decorations {
+  readonly wrap: readonly unknown[];
+  readonly before: readonly unknown[];
+  readonly after: readonly unknown[];
+}
+
+/**
+ * What the behavioural verbs left on this node, or nothing at all.
+ *
+ * The language has no syntax for "around this body", so `.wrap` cannot rewrite
+ * the tree the way `.addParam` does. It records a fact about the declaration
+ * and the scheduler honours it.
+ */
+export function readDecorations(node: object): Decorations | undefined {
+  const wrap = readMeta<unknown[]>(node, AROUND_KEYS.wrap);
+  const before = readMeta<unknown[]>(node, AROUND_KEYS.before);
+  const after = readMeta<unknown[]>(node, AROUND_KEYS.after);
+  if (!wrap && !before && !after) return undefined;
+  return { wrap: wrap ?? [], before: before ?? [], after: after ?? [] };
+}
+
+/** Append one closure to a behavioural list, keeping the order they were written. */
+export function addDecoration(node: object, key: string, fn: unknown): void {
+  writeMeta(node, key, [...(readMeta<unknown[]>(node, key) ?? []), fn]);
+}

package/src/expand/expand.ts

@@ -0,0 +1,108 @@
+import type { AstNode } from "langium";
+import { walkAst } from "../ast/index.js";
+import { buildProblem, CODES } from "../codes/index.js";
+import type { Annotation, Document } from "../generated/ast.js";
+import type { Problem } from "../problem/index.js";
+import type { ImportedDeco } from "./deco/index.js";
+import { withDocumentDecos } from "./deco/index.js";
+import type { DecoratorDefinition, DecoratorSource, ExpandResult } from "./expand.types.js";
+import { makeContext } from "./make-context.js";
+import { spanOf } from "./node-span.js";
+import { wrongKind, wrongTargetTitle } from "./wrong-kind.js";
+
+/** What one decorated node needs for its decorators to run. */
+interface Site {
+  node: AstNode & { annotations: Annotation[] };
+  decorators: DecoratorSource;
+  uri: string;
+  problems: Problem[];
+}
+
+/**
+ * Run every decorator the program wrote, before anything else reads the program.
+ *
+ * This is the one place a `@name` means anything. The kernel does not know what
+ * `@retry` is; it knows that a name written with an `@` is looked up, handed the
+ * node it sits on, and allowed to rewrite it. Built-in decorators come through
+ * here too, so there is no shorter path for them.
+ *
+ * Applied innermost first, so a decorator that rewrites a body finds a body its
+ * own decorators have already finished with.
+ *
+ * A `deco` the document declares, or one imported from a file that wrote `pub`,
+ * joins the same source the built-ins live in before any of them run. Nothing
+ * below here can tell whether `@memoize` was written in TypeScript, in this
+ * file, or in the one next to it.
+ *
+ * @returns the problems raised. The document itself is rewritten in place.
+ */
+export function expand(args: {
+  document: Document;
+  decorators: DecoratorSource;
+  uri?: string;
+  /** The `pub deco`s this file's imports reach, by name. */
+  imported?: ReadonlyMap<string, ImportedDeco>;
+}): ExpandResult {
+  const problems: Problem[] = [];
+  const uri = args.uri ?? "memory://inline.vn";
+  const decorators = withDocumentDecos({ ...args, uri, problems });
+  const sites = walkAst(args.document).filter(decorated);
+  for (const node of sites.reverse()) {
+    applyAll({ node, decorators, uri, problems });
+  }
+  return { problems };
+}
+
+function decorated(node: AstNode): node is AstNode & { annotations: Annotation[] } {
+  return ((node as { annotations?: Annotation[] }).annotations ?? []).length > 0;
+}
+
+function applyAll(site: Site): void {
+  // A copy: a decorator is allowed to rewrite the list it is standing in.
+  for (const annotation of [...site.node.annotations]) applyOne(site, annotation);
+}
+
+function applyOne(site: Site, annotation: Annotation): void {
+  const found = site.decorators.get(annotation.name);
+  if (!found) {
+    refuse(site, annotation, unknownTitle(annotation), CODES.VN2013_UNKNOWN_DECORATOR.code);
+    return;
+  }
+  const misplaced = wrongPlace(found, site.node, annotation);
+  if (misplaced) {
+    refuse(site, annotation, misplaced, CODES.VN2014_DECORATOR_TARGET.code);
+    return;
+  }
+  found.expand(
+    makeContext({ node: site.node, annotation, uri: site.uri, problems: site.problems }),
+  );
+}
+
+/**
+ * Why a decorator does not belong here, if it does not.
+ *
+ * A `deco` says what it decorates by typing its first parameter, so the answer
+ * is phrased in the words the author used. A plugin's decorator still names node
+ * types, because it is handed the raw node and nothing shorter describes what it
+ * is able to read.
+ */
+function wrongPlace(
+  found: DecoratorDefinition,
+  node: AstNode,
+  annotation: Annotation,
+): string | undefined {
+  const name = annotation.name;
+  if (found.accepts) return wrongKind({ name, kinds: found.accepts, node });
+  if (!found.targets || found.targets.includes(node.$type)) return undefined;
+  return wrongTargetTitle({ name, targets: found.targets, node });
+}
+
+function unknownTitle(annotation: Annotation): string {
+  return `No decorator is named "@${annotation.name}".`;
+}
+
+function refuse(site: Site, annotation: Annotation, title: string, code: string): void {
+  site.problems.push(
+    buildProblem({ spec: { code, severity: "error" }, span: spanOf(annotation, site.uri), title }),
+  );
+}

package/src/expand/expand.types.ts

@@ -0,0 +1,78 @@
+import type { AstNode } from "langium";
+import type { Problem } from "../problem/index.js";
+import type { TargetKind } from "./handles/index.js";
+
+/**
+ * A node a decorator may be attached to, as the decorator sees it.
+ *
+ * Deliberately structural: a decorator receives the real tree, not a copy and
+ * not a facade, so it can read anything the grammar produced and rewrite it.
+ * `$type` is how it knows what it is holding.
+ */
+export type DecoratedNode = AstNode;
+
+/** What a decorator writes for the runtime to read later. */
+export type NodeMeta = Record<string, unknown>;
+
+/**
+ * Everything a decorator is handed when it runs.
+ *
+ * Expansion happens once, between parsing and everything else, so a decorator
+ * sees the whole program before a single statement has run. What it leaves
+ * behind is what the checker checks and the runtime runs.
+ */
+export interface ExpandContext {
+  /** The node carrying this decorator. */
+  readonly node: DecoratedNode;
+  /** The arguments, evaluated: `@retry(2, { backoff: 500ms })` gives `[2, {…}]`. */
+  readonly args: readonly unknown[];
+  /** The same arguments as syntax, for a decorator that transforms rather than reads. */
+  readonly written: readonly DecoratedNode[];
+  /** Where the node sits, for a decorator that needs to look around or reattach. */
+  readonly parent: DecoratedNode | undefined;
+  /** Put this node in place of the decorated one. */
+  replace(node: DecoratedNode): void;
+  /** Take the decorated node out of the tree entirely. */
+  remove(): void;
+  /** Leave something for the runtime, keyed by name. */
+  meta(key: string, value: unknown): void;
+  /** Refuse the program, in the language's own error vocabulary. */
+  reject(args: { code: string; title: string }): void;
+}
+
+/**
+ * A decorator: a named transformation of the tree, contributed by the kernel or
+ * by a plugin, and applied wherever a program writes `@name`.
+ */
+export interface DecoratorDefinition {
+  readonly name: string;
+  readonly doc?: string;
+  /**
+   * The `$type`s this may decorate, such as `["FlowDecl", "StepDecl"]`. Omitted
+   * means anywhere: a decorator that reads nothing about its target constrains
+   * nothing about it.
+   *
+   * Node names are the plugin author's spelling, and they stay. A TypeScript
+   * decorator is handed the raw node, so nothing shorter describes what it is
+   * able to read.
+   */
+  readonly targets?: readonly string[];
+  /**
+   * The kinds this decorates, as a `deco` declared them, read off the type of
+   * its first parameter with `acceptedKinds`. Present only for a decorator the
+   * language itself declared, and it wins over `targets`: a signature says in
+   * the user's words what a list of node names only approximates.
+   */
+  readonly accepts?: readonly TargetKind[];
+  expand(ctx: ExpandContext): void;
+}
+
+/** Where expansion looks a decorator up. The kernel does not know what plugins are. */
+export interface DecoratorSource {
+  get(name: string): DecoratorDefinition | undefined;
+}
+
+/** What expansion reports. The tree itself is rewritten in place. */
+export interface ExpandResult {
+  problems: Problem[];
+}

package/src/expand/handles/around-verbs.ts

@@ -0,0 +1,35 @@
+import { nativeFn } from "../../expr/index.js";
+import { AROUND_KEYS, addDecoration } from "../decorations.js";
+import type { Verb, VerbTable } from "./handle.types.js";
+
+/** Everything a function's call can be surrounded with. */
+export const CALL_AROUND_VERBS: VerbTable = {
+  props: {},
+  calls: { wrap: around(AROUND_KEYS.wrap), before: before(), after: after() },
+};
+
+/**
+ * A flow and a step have no `wrap`: there is no call to intercept and no return
+ * to replace, only a body that runs. Offering it would be a verb that does
+ * nothing, which is worse than not having it.
+ */
+export const BODY_AROUND_VERBS: VerbTable = {
+  props: {},
+  calls: { before: before(), after: after() },
+};
+
+function before(): Verb {
+  return around(AROUND_KEYS.before);
+}
+
+function after(): Verb {
+  return around(AROUND_KEYS.after);
+}
+
+function around(key: string): Verb {
+  return (node) =>
+    nativeFn((args) => {
+      addDecoration(node, key, args[0]);
+      return null;
+    });
+}

package/src/expand/handles/binding-verbs.ts

@@ -0,0 +1,27 @@
+import { constLit } from "../../compile/index.js";
+import { evaluate, nativeFn } from "../../expr/index.js";
+import type { LetStmt } from "../../generated/ast.js";
+import type { VerbTable } from "./handle.types.js";
+
+/** Nothing is bound yet, so what a binding's value refers to is nothing either. */
+const NOTHING = { lookup: () => undefined };
+
+/**
+ * A `let` or `const`: what it was bound to, and binding it to something else.
+ *
+ * `.value` reads the expression as written, against an empty scope. Expansion
+ * happens before any of the program's own names exist, so a binding whose value
+ * depends on one answers with nothing rather than with a guess.
+ */
+export const BINDING_VERBS: VerbTable = {
+  props: { value: (node) => evaluate((node as LetStmt).value, NOTHING) },
+  calls: { setValue: (node) => nativeFn((args) => setValue(node as LetStmt, args[0])) },
+};
+
+function setValue(stmt: LetStmt, value: unknown): null {
+  const written = constLit(value) as { $container?: object; $containerProperty?: string };
+  written.$container = stmt;
+  written.$containerProperty = "value";
+  stmt.value = written as LetStmt["value"];
+  return null;
+}