@cotal-ai/lang 0.23.0 → 0.24.0

package/dist/grammar.js

@@ -12,7 +12,10 @@
  */
 import { parse } from "acorn";
 import { LangError, LangErrors } from "./errors.js";
-import { BUILTINS, FORBIDDEN_GLOBALS, NOTIFY_BOUND, PRIMITIVES, PROMISE_NAMES, RESERVED_NAMES, STEP_NAME_RE, primitiveDoc, } from "./primitives.js";
+import { BUILTINS, FORBIDDEN_GLOBALS, HOST_GLOBAL_HINTS, NOTIFY_BOUND, PRIMITIVES, PROMISE_NAMES, RESERVED_NAMES, STEP_NAME_RE, primitiveDoc, } from "./primitives.js";
+import { KEY_RESERVED_RE } from "./keys.js";
+import { ADMITTED_NODES, FORBIDDEN_NODES, STRUCTURAL_NODES } from "./syntax.js";
+import { MUTATING_METHODS } from "./library.js";
 const ACORN_OPTIONS = {
     ecmaVersion: 2023,
     sourceType: "module",
@@ -27,6 +30,24 @@ class Validator {
     file;
     errors = [];
     warnings = [];
+    /**
+     * Named functions, by name, for L2032's reach.
+     *
+     * A branch does not have to be written at the combinator call — `parallel({ a, b })` names two
+     * functions declared elsewhere, and an inline branch can call a helper that writes the outer
+     * binding on its behalf. Both are the same defect and neither is visible from the call site
+     * alone, so the names are resolved here. A name bound to two different functions maps to `null`:
+     * it cannot be resolved, and guessing which one a branch meant is worse than saying so.
+     */
+    functions = new Map();
+    /**
+     * The parent of every call, recorded by the shape walk for the resolution walk.
+     *
+     * L2013 is a rule about POSITION (awaited, returned, or a combinator's thunk) and, for a user
+     * function, about the callee's declaration (async or not). The shape walk sees the position and
+     * the resolution walk sees the declaration, so the position is carried across.
+     */
+    parents = new WeakMap();
     constructor(source, file) {
         this.source = source;
         this.file = file;
@@ -53,88 +74,16 @@ class Validator {
     }
 }
 // ---- walk 1: shape ------------------------------------------------------------------------
-/** Node types rejected outright, with the code and the repair to suggest. */
-const FORBIDDEN_NODES = Object.freeze({
-    ClassDeclaration: {
-        code: "L1001",
-        cause: "There are no classes in this language. State lives in records and behaviour lives in functions.",
-        fix: "Replace the class with a function that returns a record.",
-    },
-    ClassExpression: {
-        code: "L1001",
-        cause: "There are no classes in this language. State lives in records and behaviour lives in functions.",
-        fix: "Replace the class with a function that returns a record.",
-    },
-    ThisExpression: {
-        code: "L1002",
-        cause: "`this` does not exist, so nothing can capture a calling context by accident.",
-        fix: "Pass what the function needs as an argument.",
-    },
-    ForInStatement: {
-        code: "L1004",
-        cause: "`for...in` walks an unspecified order and reaches inherited names, so it cannot be deterministic.",
-        fix: "Iterate explicitly: `for (const k of keys(record)) { ... }`.",
-    },
-    WithStatement: {
-        code: "L1013",
-        cause: "`with` makes name resolution dynamic, and every name here resolves at parse time.",
-        fix: "Reference the record's fields directly.",
-    },
-    TaggedTemplateExpression: {
-        code: "L1018",
-        cause: "A tagged template runs user code during evaluation of a literal, which hides an effect inside what looks like data.",
-        fix: "Use a plain template literal, or call the function explicitly.",
-    },
-    NewExpression: {
-        code: "L1019",
-        cause: "There are no constructors, so `new` has nothing to construct.",
-        fix: "Build a record literal, or call a function that returns one.",
-    },
-    ImportDeclaration: {
-        code: "L1020",
-        cause: "A program is exactly one module, because a run pins to the content hash of its source.",
-        fix: "Define the function in this file. Shared procedures are ordinary functions.",
-    },
-    ExportNamedDeclaration: {
-        code: "L1020",
-        cause: "A program is exactly one module and has nothing to export to.",
-        fix: "Remove the `export`.",
-    },
-    ExportDefaultDeclaration: {
-        code: "L1020",
-        cause: "A program is exactly one module and has nothing to export to.",
-        fix: "Remove the `export`.",
-    },
-    ExportAllDeclaration: {
-        code: "L1020",
-        cause: "A program is exactly one module and has nothing to export to.",
-        fix: "Remove the `export`.",
-    },
-    DoWhileStatement: {
-        code: "L1022",
-        cause: "`do...while` is not in the language.",
-        fix: "Use `while` with the condition checked first, or a `for` loop.",
-    },
-    LabeledStatement: {
-        code: "L1017",
-        cause: "Labels turn the derived flowchart's back-edges into arbitrary jumps.",
-        fix: "Restructure with a helper function or a boolean flag.",
-    },
-    BreakStatement: {
-        code: "L1017",
-        cause: "A labelled break is an arbitrary jump.",
-        fix: "Restructure with a helper function or a boolean flag.",
-    },
-    ContinueStatement: {
-        code: "L1017",
-        cause: "A labelled continue is an arbitrary jump.",
-        fix: "Restructure with a helper function or a boolean flag.",
-    },
-    AwaitExpression: {
-        code: "L1023",
-        cause: "This `await` sits inside a function that is not `async`. Every effect is awaited, so a function that performs one is async.",
-        fix: "Mark the enclosing function `async`: `async function name(...) { ... }`.",
-    },
+/** The two conditional refusals the table cannot carry: a LABELLED jump and an `await` outside async. */
+const LABELLED_JUMP = Object.freeze({
+    code: "L1017",
+    cause: "A labelled break or continue is an arbitrary jump.",
+    fix: "Restructure with a helper function or a boolean flag.",
+});
+const AWAIT_OUTSIDE_ASYNC = Object.freeze({
+    code: "L1023",
+    cause: "This `await` sits inside a function that is not `async`. Every effect is awaited, so a function that performs one is async.",
+    fix: "Mark the enclosing function `async`: `async function name(...) { ... }`.",
 });
 /**
  * Automatic semicolon insertion is ALLOWED, against Jessie, and this is a declared deviation.
@@ -196,6 +145,13 @@ const PARSE_ERROR_MAP = [
         cause: "A program has no return value. Its outcome is what it did: the journal of its effects, and whatever it published onto the run record. There is nobody for a top-level `return` to return to.",
         fix: "Publish the result onto the run record, or use `log(...)` if you only wanted it in the trace.",
     },
+    {
+        // A program is a module, so it is strict, and acorn refuses `with` before any walk sees it.
+        test: /'with' in strict mode/i,
+        code: "L1013",
+        cause: "`with` makes name resolution dynamic, and every name here resolves at parse time.",
+        fix: "Reference the record's fields directly.",
+    },
     {
         test: /keyword 'await' outside an async function|await is only valid in async/i,
         code: "L1023",
@@ -225,34 +181,83 @@ function children(node) {
 function isNode(v) {
     return v !== null && typeof v === "object" && typeof v.type === "string";
 }
-function walkShape(node, v, inAsync, parent = null) {
+/** True when a statement always leaves its `switch` case: a terminator, or a block/if made of them. */
+function terminates(stmt) {
+    switch (stmt.type) {
+        case "ReturnStatement":
+        case "BreakStatement":
+        case "ContinueStatement":
+        case "ThrowStatement":
+            return true;
+        case "BlockStatement": {
+            const body = stmt.body ?? [];
+            const last = body[body.length - 1];
+            return last !== undefined && terminates(last);
+        }
+        case "IfStatement":
+            return (isNode(stmt.consequent) &&
+                terminates(stmt.consequent) &&
+                isNode(stmt.alternate) &&
+                terminates(stmt.alternate));
+        default:
+            return false;
+    }
+}
+/** The static name of a member access: `x.a` and `x["a"]` both name `a`; `x[k]` names nothing. */
+function memberName(member) {
+    const property = member.property;
+    if (property === undefined)
+        return null;
+    if (member.computed !== true)
+        return property.type === "Identifier" ? property.name : null;
+    return property.type === "Literal" && typeof property.value === "string" ? property.value : null;
+}
+/** The name of a non-computed property key, or null when it is computed. */
+function propertyKeyName(node) {
+    if (node.computed === true)
+        return null;
+    const key = node.key;
+    if (key === undefined)
+        return null;
+    if (key.type === "Identifier")
+        return key.name;
+    if (key.type === "Literal")
+        return String(key.value);
+    return null;
+}
+function walkShape(node, v, inAsync, parent = null, 
+/** An ancestor already carried a forbidden row, so this node's own presence needs no second error. */
+underForbidden = false) {
     const type = node.type;
     // Labels and labelled jumps: a bare break/continue is fine, a labelled one is not.
-    if (type === "BreakStatement" || type === "ContinueStatement") {
-        if (node.label !== null && node.label !== undefined) {
-            const r = FORBIDDEN_NODES[type];
-            if (r !== undefined)
-                v.fail(r.code, node, r.cause, r.fix);
-        }
+    if ((type === "BreakStatement" || type === "ContinueStatement") && node.label !== null && node.label !== undefined) {
+        v.fail(LABELLED_JUMP.code, node, LABELLED_JUMP.cause, LABELLED_JUMP.fix);
         return;
     }
     // `await` is legal only inside an async function.
     if (type === "AwaitExpression" && !inAsync) {
-        const r = FORBIDDEN_NODES.AwaitExpression;
-        if (r !== undefined)
-            v.fail(r.code, node, r.cause, r.fix);
+        v.fail(AWAIT_OUTSIDE_ASYNC.code, node, AWAIT_OUTSIDE_ASYNC.cause, AWAIT_OUTSIDE_ASYNC.fix);
     }
-    const rule = type === "AwaitExpression" ? undefined : FORBIDDEN_NODES[type];
+    // THE TABLE. A node is admitted, structural, on a forbidden row, or outside the language.
+    const rule = FORBIDDEN_NODES[type];
+    let forbidden = underForbidden;
     if (rule !== undefined) {
         v.fail(rule.code, node, rule.cause, rule.fix);
+        forbidden = true;
+    }
+    else if (!ADMITTED_NODES.has(type) && !STRUCTURAL_NODES.has(type) && !underForbidden) {
+        v.fail("L1029", node, `\`${type}\` is valid JavaScript but is not in this language, which is a fixed subset of it.`, "Rewrite with the constructs the language has: functions, records, arrays, loops, conditionals, try/catch, and the effect primitives.");
+        forbidden = true;
     }
     if (type === "Program" || type === "BlockStatement")
         checkAsiHazards(node, v);
     if (type === "CallExpression" || (type === "MemberExpression" && node.computed === true)) {
         checkContinuationHazard(node, v);
     }
-    if (type === "CallExpression")
+    if (type === "CallExpression") {
+        v.parents.set(node, parent);
         checkAsyncCallPosition(node, parent, v);
+    }
     switch (type) {
         case "VariableDeclaration":
             if (node.kind === "var") {
@@ -270,6 +275,9 @@ function walkShape(node, v, inAsync, parent = null) {
             if (node.regex !== undefined) {
                 v.fail("L1007", node, "There are no regular expressions, so a program cannot spend unbounded time in a match.", "Use `contains`, `startsWith`, `endsWith`, or `split`.");
             }
+            if (node.bigint !== undefined || typeof node.value === "bigint") {
+                v.fail("L1030", node, "Numbers here are IEEE doubles with a canonical JSON form; a bigint has neither, so it could not be journalled or cross an effect boundary.", "Use a number, or a string for an identifier that exceeds 2^53.");
+            }
             break;
         case "IfStatement": {
             for (const branch of ["consequent", "alternate"]) {
@@ -293,8 +301,10 @@ function walkShape(node, v, inAsync, parent = null) {
             const consequent = node.consequent;
             if (Array.isArray(consequent) && consequent.length > 0) {
                 const last = consequent[consequent.length - 1];
-                const terminators = ["ReturnStatement", "BreakStatement", "ContinueStatement", "ThrowStatement"];
-                if (isNode(last) && !terminators.includes(last.type)) {
+                // The check looks THROUGH a braced case body: the language asks for blocks everywhere
+                // else, so `case 1: { ...; break; }` is the shape it invites, and refusing it read as a
+                // rule against the block rather than against the fall-through.
+                if (isNode(last) && !terminates(last)) {
                     v.fail("L1010", node, "A case that falls through to the next one is nearly always a missing `break`.", "End the case with `return`, `break`, `continue`, or `throw`.");
                 }
             }
@@ -302,7 +312,10 @@ function walkShape(node, v, inAsync, parent = null) {
         }
         case "Property":
             if (node.computed === true) {
-                v.fail("L1011", node, "A computed key means the record's shape is not visible in the source, so neither the validator nor the flowchart can read it.", "Use a literal key, or build the record with `merge`.");
+                v.fail("L1011", node, "A computed key means the record's shape is not visible in the source, so neither the validator nor the flowchart can read it.", "Use a literal key, or build the record with `merge`, or write it as `record[key] = value`.");
+            }
+            if (parent?.type === "ObjectExpression" && propertyKeyName(node) === "__proto__") {
+                v.fail("L1028", node, "`__proto__` names an object's prototype, and there are no prototypes here: a record has exactly the fields written on it.", "Choose another field name.");
             }
             if (node.kind === "get" || node.kind === "set") {
                 v.fail("L1015", node, "An accessor runs code when a property is read, which hides an effect behind what looks like data.", "Store the value, or call a function explicitly.");
@@ -314,6 +327,9 @@ function walkShape(node, v, inAsync, parent = null) {
             }
             break;
         case "BinaryExpression":
+            if (node.operator === "==" || node.operator === "!=") {
+                v.fail("L1025", node, `\`${node.operator}\` coerces its operands before comparing them, so \`0 == ""\` and \`null == undefined\` are true and a comparison's answer depends on rules nobody wrote down here.`, `Use \`${node.operator === "==" ? "===" : "!=="}\`, and \`?? \` or \`=== null\` when the question is about a missing value.`);
+            }
             if (node.operator === "instanceof") {
                 v.fail("L1016", node, "There are no classes or prototypes, so `instanceof` can only probe host objects.", "Compare a field instead, for example `value.status === \"done\"`.");
             }
@@ -322,6 +338,9 @@ function walkShape(node, v, inAsync, parent = null) {
             }
             break;
         case "UnaryExpression":
+            if (node.operator === "void") {
+                v.fail("L1027", node, "`void` evaluates an expression and discards it, which is only ever used to hide a value or to spell `undefined` obscurely.", "Write `undefined` when you mean it, or drop the expression.");
+            }
             if (node.operator === "delete") {
                 v.fail("L1021", node, "Records that cross an effect boundary are frozen, and deleting from a live one makes its shape depend on control flow.", "Build a new record with the fields you want.");
             }
@@ -333,17 +352,51 @@ function walkShape(node, v, inAsync, parent = null) {
         ? node.async === true
         : inAsync;
     for (const child of children(node))
-        walkShape(child, v, nowAsync, node);
+        walkShape(child, v, nowAsync, node, forbidden);
 }
 // ---- walk 2: resolution and effect call shape --------------------------------------------
 class Scope {
     parent;
     names = new Map();
+    /** The function node a name is bound to HERE, when it is bound to one at all. */
+    fns = new Map();
+    /**
+     * Names declared LATER in this scope than the point the walk has reached. A `let`/`const` binds
+     * the WHOLE block it is in, so a reference above the declaration resolves to it — and, executed,
+     * would find a binding that does not hold a value yet (JavaScript's temporal dead zone, a
+     * guaranteed runtime ReferenceError in straight-line code). This language refuses it when the
+     * program is read (L2004), the way it already refuses an unknown name (L2001) that JavaScript
+     * would also only catch at runtime. A reference from inside a NESTED FUNCTION is exempt: the
+     * function runs later, when the binding may well be initialized — that is the mutual-recursion
+     * shape — so the walk only refuses what straight-line execution is certain to hit.
+     */
+    pending = new Set();
+    /** True where this scope is a function body: references from inside it to a pending outer name are deferred, not certain. */
+    fnBoundary = false;
     constructor(parent) {
         this.parent = parent;
     }
-    declare(name, kind) {
+    declare(name, kind, fn) {
         this.names.set(name, kind);
+        if (fn !== undefined)
+            this.fns.set(name, fn);
+        else
+            this.fns.delete(name);
+    }
+    /**
+     * Is a reference to `name` FROM this scope certain to land in a dead zone? True only when the
+     * scope that owns the binding still has it pending and no function boundary lies between the
+     * reference and the owner.
+     */
+    refersToPending(name) {
+        let crossedFn = false;
+        for (let s = this; s !== null; s = s.parent) {
+            if (s.names.has(name))
+                return s.pending.has(name) && !crossedFn;
+            if (s.fnBoundary)
+                crossedFn = true;
+        }
+        return false;
     }
     lookup(name) {
         for (let s = this; s !== null; s = s.parent) {
@@ -353,6 +406,23 @@ class Scope {
         }
         return undefined;
     }
+    /**
+     * The function this name is bound to AT THIS POINT IN THE PROGRAM, or nothing.
+     *
+     * The nearest binding decides, and a binding that is not a function answers `undefined` rather
+     * than deferring outward — that is the difference between resolving a name and resolving a
+     * BINDING. A program-wide name map cannot tell `parallel({ branch })` inside
+     * `function use(branch)` from the top-level `function branch()` of the same name, and blaming a
+     * clean program for what an unrelated declaration elsewhere happens to write is worse than
+     * leaving one branch unproven: an unproven branch is still refused at runtime by the depth check.
+     */
+    lookupFn(name) {
+        for (let s = this; s !== null; s = s.parent) {
+            if (s.names.has(name))
+                return s.fns.get(name);
+        }
+        return undefined;
+    }
 }
 /** Collect the identifiers a binding pattern introduces. */
 function patternNames(node, out) {
@@ -514,31 +584,44 @@ function checkAsyncCallPosition(node, parent, v) {
     if (!isNode(callee) || callee.type !== "Identifier")
         return;
     const name = callee.name;
-    // Primitives are always effects; a user function is only interesting if it was declared async,
-    // which the resolution walk cannot know here, so both are treated the same way: the POSITION
-    // is what is checked, not the callee's nature.
-    const isEffect = PRIMITIVES[name] !== undefined;
-    if (!isEffect)
+    // Primitives are always effects and are checked here, where the position is known. A user
+    // function is an effect only if it was declared async, which only the resolution walk can see:
+    // {@link checkCall} applies the same rule to those, reading the position back from `v.parents`.
+    if (PRIMITIVES[name] === undefined)
         return;
-    if (parent === null)
+    if (parent === null || asyncCallPositionOk(parent))
         return;
-    // Only two positions are legal: awaited, or the concise body of an arrow that a combinator
-    // owns as a thunk. Everything else, including a bare statement, starts work nothing waits for.
-    const ok = parent.type === "AwaitExpression" ||
+    v.fail("L2013", node, unawaitedCause(name), unawaitedFix(name), name);
+}
+/**
+ * Only two positions are legal for a call that starts an effect: awaited, or the concise body of
+ * an arrow that a combinator owns as a thunk (a `return` is the braced spelling of the same thing).
+ * Everything else, including a bare statement, starts work nothing waits for.
+ */
+function asyncCallPositionOk(parent) {
+    return (parent.type === "AwaitExpression" ||
         parent.type === "ArrowFunctionExpression" ||
-        parent.type === "ReturnStatement";
-    if (ok)
-        return;
-    v.fail("L2013", node, `This \`${name}\` is not awaited, so it starts work whose result nothing waits for. Read literally the program says one thing and the runtime does another: calls outside a combinator run in sequence, not concurrently.`, `Await it (\`await ${name}(...)\`), return it, or make it a branch of \`parallel\`, \`race\` or \`fanOut\`.`, name);
+        parent.type === "ReturnStatement");
 }
-function checkCall(node, v) {
+const unawaitedCause = (name) => `This \`${name}\` is not awaited, so it starts work whose result nothing waits for. Read literally the program says one thing and the runtime does another: calls outside a combinator run in sequence, not concurrently.`;
+const unawaitedFix = (name) => `Await it (\`await ${name}(...)\`), return it, or make it a branch of \`parallel\`, \`race\` or \`fanOut\`.`;
+function checkCall(node, v, scope) {
     const callee = node.callee;
     if (!isNode(callee) || callee.type !== "Identifier")
         return;
     const name = callee.name;
     const spec = PRIMITIVES[name];
-    if (spec === undefined)
+    if (spec === undefined) {
+        // L2013's other half: a USER function declared `async` (or a const bound to an async function
+        // expression) is an effect the moment it is called, and holding its call in a binding is the
+        // rule's own motivating example: `const pa = work(a); const pb = work(b);`.
+        const fn = scope.lookupFn(name);
+        const parent = v.parents.get(node) ?? null;
+        if (fn !== undefined && fn.async === true && parent !== null && !asyncCallPositionOk(parent)) {
+            v.fail("L2013", node, unawaitedCause(name), unawaitedFix(name));
+        }
         return;
+    }
     const args = node.arguments ?? [];
     // `checkpoint` takes its name positionally; every other primitive takes it in the option bag.
     if (name === "checkpoint") {
@@ -573,16 +656,35 @@ function checkCall(node, v) {
             v.fail("L3011", prop, `\`${name}\` has no option named \`${key}\`, and option bags are closed so a typo cannot be silently dropped.`, `Accepted keys: ${spec.options.join(", ")}.`, name);
         }
     }
-    // Required step names.
-    if (spec.nameRequired && name !== "checkpoint") {
+    // Step names: REQUIRED-ness and VALIDITY are separate questions and must not share one gate.
+    //
+    // Required-ness is a statement about the caller's obligation; validity is a statement about the
+    // sink. `nameRequired` is false for 7 of the 13 primitives, so behind one gate a name supplied on
+    // any of those reaches `stepKeyString` unchecked: the optional path, which is the one nobody
+    // writes tests for, feeds the same durable journal key as the required one. A name containing the
+    // characters the key grammar reserves forges structure: two different programs then print one
+    // identical key, and with matching inputs the collision is entirely silent.
+    if (name !== "checkpoint") {
         const prop = given.get("name");
         if (prop === undefined) {
-            v.fail("L3012", node, `Every \`${name}\` needs a name, because its journal entry is keyed by that name rather than by its position. Without one, a resumed run cannot tell this step from any other.`, `Add a kebab-case name literal: ${name}(..., { name: "..." })`, name);
+            if (spec.nameRequired) {
+                v.fail("L3012", node, `Every \`${name}\` needs a name, because its journal entry is keyed by that name rather than by its position. Without one, a resumed run cannot tell this step from any other.`, `Add a kebab-case name literal: ${name}(..., { name: "..." })`, name);
+            }
         }
         else {
             const value = prop.value;
-            if (value.type !== "Literal" || typeof value.value !== "string") {
-                v.fail("L3013", value, "A step name must be a string literal, because the flowchart, the linter, and the migration report all read it without running the program.", 'Use a literal: { name: "build" }', name);
+            const isLiteral = value.type === "Literal" && typeof value.value === "string";
+            // L3013 stays gated on `nameRequired`. Widening it to every present name refused
+            // `fanOut([...], async (lens) => sleep("1m", { name: lens }))` — naming a branch's step after
+            // its item, which is idiomatic and is how a fan-out gets distinct keys at all. That is the
+            // cost this restriction would have had, and it is too high for what it buys: the SHAPE check
+            // below is what closes the forgery, and it does not need the name to be static.
+            if (!isLiteral) {
+                if (spec.nameRequired) {
+                    v.fail("L3013", value, "A step name must be a string literal, because the flowchart, the linter, and the migration report all read it without running the program.", 'Use a literal: { name: "build" }', name);
+                }
+                // A COMPUTED name cannot be checked here at all, and it reaches the same journal key. The
+                // refusal for that one lives at key construction, where the value exists — see keys.ts.
             }
             else if (!STEP_NAME_RE.test(value.value)) {
                 v.fail("L3014", value, `"${value.value}" is not a well-formed step name.`, 'Use kebab-case, 1 to 64 characters: { name: "build" }', name);
@@ -610,11 +712,287 @@ function checkCall(node, v) {
             v.warn("L3023", branches, "Array branches are keyed by index, so inserting a branch shifts every later branch's journal namespace and re-runs its steps.", `Use the record form: ${name}({ lint: () => ..., tests: () => ... }, { name: "checks" })`, name);
         }
     }
+    // A record-form branch KEY becomes a path segment verbatim: `frameString` builds
+    // `/kind:name#occ/b:${branch}` by concatenation and escapes nothing. So a key containing one of
+    // the three characters the key grammar reserves forges structure — a single branch named
+    // `a/parallel:inner#0/b:b` prints the identical key to a genuinely nested `a` → `inner` → `b`,
+    // and the journal cannot tell the two locations apart. With different inputs that surfaces as a
+    // spurious L5001 divergence for a program that never diverged; with matching inputs it is
+    // SILENT, one durable row serving both, and a replay hands the second location the first's
+    // recorded effect.
+    //
+    // Only the reserved characters are rejected, NOT the full step-name pattern: branch keys are
+    // ordinary object keys and `{ runTests: ... }` is legitimate, so requiring kebab-case here would
+    // refuse correct programs to fix a forgery that needs `/`, `#` or `:`. The restriction is the
+    // narrowest one that closes it.
+    if (name === "parallel" || name === "race" || name === "fanOut") {
+        const branches = args[0];
+        if (branches !== undefined && branches.type === "ObjectExpression") {
+            for (const prop of branches.properties ?? []) {
+                const key = prop.key;
+                if (key === undefined)
+                    continue;
+                const text = key.type === "Identifier" ? key.name
+                    : key.type === "Literal" && typeof key.value === "string" ? key.value
+                        : undefined;
+                if (text === undefined || !KEY_RESERVED_RE.test(text))
+                    continue;
+                v.fail("L3025", key, `The branch key "${text}" contains a character the step-key grammar reserves (\`/\`, \`#\` or \`:\`). Branch keys are written into the journal key verbatim, so this one can spell a path that a genuinely nested scope also produces — and two different locations that share a key share a durable row, silently when their inputs match.`, "Use a branch key without `/`, `#` or `:`.", name);
+            }
+        }
+    }
+    // L2032: a branch that WRITES a binding declared outside it.
+    //
+    // Freeze-on-share does not see this one, because nothing crosses an effect boundary: the branches
+    // set a scalar in the enclosing scope. And the damage is silent. Live, the branches write in
+    // COMPLETION order; on resume the journalled effects return instantly, so they write in LAUNCH
+    // order, the binding ends up holding a different value, and the resumed run takes a path it never
+    // recorded — with no divergence raised, because no effect's inputs changed.
+    //
+    // `conclave` is deliberately not here. Its body is a single thunk with nothing to race, so a
+    // write from inside it is as ordered as a write anywhere else in the program.
+    if (name === "parallel" || name === "race" || name === "fanOut") {
+        // One `seen` set per combinator call: two branches calling the same helper is one defect in
+        // that helper, not two, and reporting it twice tells an author to fix one line twice.
+        const seen = new Set();
+        const thunks = name === "fanOut" ? branchThunks(args[1], v, scope) : branchThunks(args[0], v, scope);
+        for (const thunk of thunks)
+            checkCapturedWrites(thunk, name, v, seen);
+    }
+}
+function isFunctionNode(node) {
+    return (node.type === "ArrowFunctionExpression" ||
+        node.type === "FunctionExpression" ||
+        node.type === "FunctionDeclaration");
+}
+/**
+ * Index every function the program names, so L2032 can follow a branch that is not written at the
+ * combinator call. Ambiguous names (two functions, one name) index as `null` and resolve to
+ * nothing — an unproven branch is left to the interpreter's runtime check rather than guessed at.
+ */
+function indexFunctions(node, v) {
+    const put = (name, fn) => {
+        const prior = v.functions.get(name);
+        v.functions.set(name, prior === undefined || prior === fn ? fn : null);
+    };
+    if (node.type === "FunctionDeclaration" && isNode(node.id)) {
+        put(node.id.name, node);
+    }
+    if (node.type === "VariableDeclarator" && isNode(node.id) && node.id.type === "Identifier") {
+        const init = node.init;
+        if (isNode(init) && isFunctionNode(init))
+            put(node.id.name, init);
+    }
+    for (const c of children(node))
+        indexFunctions(c, v);
+}
+/**
+ * Resolve a branch to the function it names, or to nothing.
+ *
+ * A NAMED branch resolves through its lexical binding at the combinator call, never through the
+ * program-wide name map: `async function use(branch) { await parallel({ branch }) }` passes its own
+ * parameter, and resolving that name to a same-named top-level declaration made a clean program
+ * unwriteable — L2032 blamed a write in a function the program never even called. A name bound to
+ * something that is not a function is UNPROVEN, and unproven is the interpreter's depth check to
+ * refuse at runtime, not the validator's to guess at.
+ */
+function resolveFunction(node, v, scope) {
+    if (isFunctionNode(node))
+        return node;
+    if (node.type !== "Identifier")
+        return undefined;
+    const name = node.name;
+    // Bound here: the binding answers, whatever it is bound to. Unbound: walk 2 has already raised
+    // L2001 for it, so the module index is the fallback.
+    if (scope.lookup(name) !== undefined)
+        return scope.lookupFn(name);
+    return v.functions.get(name) ?? undefined;
+}
+/**
+ * The thunks a combinator owns, in every form the language accepts.
+ *
+ * `parallel({ a: () => …, b })` mixes an inline branch and a NAMED one, and a first version of this
+ * dropped the named half — so a captured-write program written with two named
+ * `async function`s instead of two arrows, was accepted. A branch is a branch however it is
+ * spelled.
+ */
+function branchThunks(node, v, scope) {
+    if (node === undefined)
+        return [];
+    const one = resolveFunction(node, v, scope);
+    if (one !== undefined)
+        return [one];
+    const out = [];
+    if (node.type === "ObjectExpression") {
+        for (const p of node.properties ?? []) {
+            if (p.type !== "Property" || !isNode(p.value))
+                continue;
+            const fn = resolveFunction(p.value, v, scope);
+            if (fn !== undefined)
+                out.push(fn);
+        }
+    }
+    if (node.type === "ArrayExpression") {
+        for (const el of node.elements ?? []) {
+            if (el === null || !isNode(el))
+                continue;
+            const fn = resolveFunction(el, v, scope);
+            if (fn !== undefined)
+                out.push(fn);
+        }
+    }
+    return out;
+}
+/** The identifier a write lands on: `x` for `x`, `x.a`, `x[i].b` and `x?.a`. */
+function rootIdentifier(node) {
+    if (node === undefined || !isNode(node))
+        return undefined;
+    if (node.type === "Identifier")
+        return node;
+    if (node.type === "MemberExpression")
+        return rootIdentifier(node.object);
+    if (node.type === "ChainExpression")
+        return rootIdentifier(node.expression);
+    return undefined;
+}
+function capturedWrite(at, name, combinator, v) {
+    v.fail("L2032", at, `\`${name}\` is declared outside this branch and written inside it. Two branches racing to write one place is nondeterministic, and freezing does not cover it because nothing crosses an effect boundary. It is also silent: live, the branches write in completion order, but on resume the recorded effects return instantly and they write in launch order, so \`${name}\` holds a different value and the run takes a path it never recorded — with no divergence raised, because no effect's inputs changed.`, `Return the value from the branch and read it out of \`${combinator}\`'s result, or use \`race\`, which yields its winner.`, combinator);
+}
+/** Walk one branch thunk with its OWN scope chain: anything it did not declare, it captured. */
+function checkCapturedWrites(fn, combinator, v, seen) {
+    if (seen.has(fn))
+        return;
+    seen.add(fn);
+    const local = new Scope(null);
+    for (const p of fn.params ?? []) {
+        const names = [];
+        patternNames(p, names);
+        for (const n of names)
+            local.declare(n, "param");
+    }
+    if (isNode(fn.body))
+        walkCaptured(fn.body, local, combinator, v, seen);
+}
+function walkCaptured(node, scope, combinator, v, seen) {
+    switch (node.type) {
+        case "VariableDeclaration": {
+            const kind = node.kind === "const" ? "const" : "let";
+            for (const d of node.declarations ?? []) {
+                if (isNode(d.init))
+                    walkCaptured(d.init, scope, combinator, v, seen);
+                const names = [];
+                patternNames(d.id, names);
+                for (const n of names)
+                    scope.declare(n, kind);
+            }
+            return;
+        }
+        case "AssignmentExpression":
+        case "UpdateExpression": {
+            // `x = 1`, `x += 1`, `x++`, `x.a = 1` and `x[i] += 1` are the same defect: something declared
+            // outside the branch is written inside it. A write through a member expression reaches the
+            // VALUE the outer binding holds, which is no more ordered across branches than the binding
+            // itself; the runtime half (values carry the depth they were born at) covers what a value
+            // reached through an alias hides from this walk.
+            const target = (node.type === "AssignmentExpression" ? node.left : node.argument);
+            const root = rootIdentifier(target);
+            if (root !== undefined && scope.lookup(root.name) === undefined) {
+                capturedWrite(root, root.name, combinator, v);
+            }
+            for (const c of children(node))
+                walkCaptured(c, scope, combinator, v, seen);
+            return;
+        }
+        case "CallExpression": {
+            // FOLLOW THE CALL. A branch that writes nothing itself and calls a helper that writes the
+            // outer binding is the same defect one level down, and it is invisible at the combinator call.
+            // The helper is checked as a branch in its own right, with its own scope, so the blame lands
+            // on the line that actually writes — and a helper that only touches its own locals is clean,
+            // which is what keeps ordinary shared procedures usable.
+            const callee = node.callee;
+            if (isNode(callee) && callee.type === "Identifier") {
+                const nm = callee.name;
+                // A locally-declared name is a local binding, not the program-level function of that name.
+                if (scope.lookup(nm) === undefined) {
+                    const target = v.functions.get(nm);
+                    if (target !== undefined && target !== null)
+                        checkCapturedWrites(target, combinator, v, seen);
+                }
+            }
+            // `outer.push(x)` from a branch is `outer[len(outer)] = x` spelled as a method.
+            if (isNode(callee) && callee.type === "MemberExpression") {
+                const member = callee;
+                const method = memberName(member);
+                const root = rootIdentifier(member.object);
+                if (method !== null &&
+                    MUTATING_METHODS.has(method) &&
+                    root !== undefined &&
+                    scope.lookup(root.name) === undefined) {
+                    capturedWrite(root, root.name, combinator, v);
+                }
+            }
+            for (const c of children(node))
+                walkCaptured(c, scope, combinator, v, seen);
+            return;
+        }
+        case "FunctionDeclaration":
+        case "FunctionExpression":
+        case "ArrowFunctionExpression": {
+            if (node.type === "FunctionDeclaration" && isNode(node.id)) {
+                scope.declare(node.id.name, "const");
+            }
+            const inner = new Scope(scope);
+            for (const p of node.params ?? []) {
+                const names = [];
+                patternNames(p, names);
+                for (const n of names)
+                    inner.declare(n, "param");
+            }
+            if (isNode(node.body))
+                walkCaptured(node.body, inner, combinator, v, seen);
+            return;
+        }
+        case "BlockStatement": {
+            const inner = new Scope(scope);
+            hoistFunctions(node, inner);
+            for (const s of node.body ?? [])
+                walkCaptured(s, inner, combinator, v, seen);
+            return;
+        }
+        case "CatchClause": {
+            const inner = new Scope(scope);
+            if (isNode(node.param)) {
+                const names = [];
+                patternNames(node.param, names);
+                for (const n of names)
+                    inner.declare(n, "const");
+            }
+            if (isNode(node.body))
+                walkCaptured(node.body, inner, combinator, v, seen);
+            return;
+        }
+        case "ForStatement":
+        case "ForOfStatement": {
+            const inner = new Scope(scope);
+            for (const c of children(node))
+                walkCaptured(c, inner, combinator, v, seen);
+            return;
+        }
+        default: {
+            for (const c of children(node))
+                walkCaptured(c, scope, combinator, v, seen);
+            return;
+        }
+    }
 }
 function walkResolve(node, v, scope) {
     switch (node.type) {
         case "Identifier": {
             const name = node.name;
+            if (scope.refersToPending(name)) {
+                v.fail("L2004", node, `\`${name}\` is declared later in this block, and a \`let\` or \`const\` binds the whole block: executed, this line would find a binding that holds no value yet (JavaScript's temporal dead zone, a guaranteed runtime error in straight-line code).`, "Move the declaration above its first use, or rename one of the two.");
+                return;
+            }
             if (scope.lookup(name) !== undefined)
                 return;
             if (RESERVED_NAMES.has(name))
@@ -624,7 +1002,8 @@ function walkResolve(node, v, scope) {
                 return;
             }
             if (FORBIDDEN_GLOBALS.has(name)) {
-                v.fail("L2012", node, `\`${name}\` is a host global. There is no ambient IO, clock, or randomness here: the interpreter has nothing nondeterministic to offer.`, "Use `now()` for time, `random()` for randomness, `sleep()` to wait, and `log()` for output.");
+                v.fail("L2012", node, `\`${name}\` is a host global. There is no ambient IO, clock, or randomness here: the interpreter has nothing nondeterministic to offer.`, HOST_GLOBAL_HINTS[name] ??
+                    "Use `now()` for time, `random()` for randomness, `sleep()` to wait, and `log()` for output.");
                 return;
             }
             v.fail("L2001", node, `\`${name}\` is not defined anywhere in this program. Every name resolves when the program is read, so this is never a runtime surprise.`, `Define it, or check the spelling. The builtins are: ${BUILTINS.join(", ")}.`);
@@ -638,11 +1017,18 @@ function walkResolve(node, v, scope) {
                     walkResolve(init, v, scope);
                 const names = [];
                 patternNames(d.id, names);
+                // `const b = async () => {...}` binds a FUNCTION, and a branch named `b` must resolve to
+                // it. Only the plain `id = function` form does: a destructured name holds whatever the
+                // pattern pulled out, which is not statically a function.
+                const bound = isNode(d.id) && d.id.type === "Identifier" && isNode(init) && isFunctionNode(init)
+                    ? init
+                    : undefined;
                 for (const n of names) {
                     if (RESERVED_NAMES.has(n)) {
                         v.fail("L2002", d.id, `\`${n}\` is a builtin, so shadowing it would make a call to \`${n}\` mean two different things in one program.`, `Rename the binding, for example \`${n}Result\`.`);
                     }
-                    scope.declare(n, kind);
+                    scope.declare(n, kind, bound);
+                    scope.pending.delete(n);
                 }
             }
             return;
@@ -681,21 +1067,46 @@ function walkResolve(node, v, scope) {
                 if (RESERVED_NAMES.has(fname)) {
                     v.fail("L2002", node.id, `\`${fname}\` is a builtin, so a function of that name would shadow it.`, "Rename the function.");
                 }
-                scope.declare(fname, "const");
+                scope.declare(fname, "const", node);
             }
             const inner = new Scope(scope);
-            for (const p of node.params ?? []) {
+            inner.fnBoundary = true;
+            // A NAMED function expression binds its own name inside itself, which is how a function
+            // assigned to a `const` recurses: `const f = function walk(n) { ... walk(n - 1) ... }`.
+            if (node.type === "FunctionExpression" && isNode(node.id)) {
+                const fname = node.id.name;
+                if (RESERVED_NAMES.has(fname)) {
+                    v.fail("L2002", node.id, `\`${fname}\` is a builtin, so a function expression of that name would shadow it inside itself.`, "Rename the function.");
+                }
+                inner.declare(fname, "const", node);
+            }
+            // Parameters bind LEFT TO RIGHT, and a default sees only the parameters before it: every
+            // name is pre-declared pending, and each parameter leaves the dead zone only after its own
+            // default was walked, so `(a = b, b = 1)` and `(a = a)` are L2004 the way straight-line
+            // block references are — JavaScript would throw the same at every call that evaluates the
+            // default, and a default that cannot ever evaluate is a landmine, not a feature.
+            const params = node.params ?? [];
+            const paramNames = params.map((p) => {
                 const names = [];
                 patternNames(p, names);
-                for (const n of names) {
+                return names;
+            });
+            for (let i = 0; i < params.length; i += 1) {
+                const p = params[i];
+                for (const n of paramNames[i]) {
                     if (RESERVED_NAMES.has(n)) {
                         v.fail("L2002", p, `\`${n}\` is a builtin, so a parameter of that name would shadow it inside this function.`, "Rename the parameter.");
                     }
                     inner.declare(n, "param");
+                    inner.pending.add(n);
                 }
-                // Default values are evaluated in the inner scope.
+            }
+            for (let i = 0; i < params.length; i += 1) {
+                const p = params[i];
                 if (p.type === "AssignmentPattern" && isNode(p.right))
                     walkResolve(p.right, v, inner);
+                for (const n of paramNames[i])
+                    inner.pending.delete(n);
             }
             if (isNode(node.body))
                 walkResolve(node.body, v, inner);
@@ -704,6 +1115,7 @@ function walkResolve(node, v, scope) {
         case "BlockStatement": {
             const inner = new Scope(scope);
             hoistFunctions(node, inner);
+            hoistBindings(node, inner);
             for (const s of node.body ?? [])
                 walkResolve(s, v, inner);
             return;
@@ -728,7 +1140,7 @@ function walkResolve(node, v, scope) {
             return;
         }
         case "CallExpression": {
-            checkCall(node, v);
+            checkCall(node, v, scope);
             for (const c of children(node))
                 walkResolve(c, v, scope);
             return;
@@ -744,7 +1156,26 @@ function walkResolve(node, v, scope) {
 function hoistFunctions(block, scope) {
     for (const s of block.body ?? []) {
         if (s.type === "FunctionDeclaration" && isNode(s.id)) {
-            scope.declare(s.id.name, "const");
+            scope.declare(s.id.name, "const", s);
+        }
+    }
+}
+/**
+ * `let`/`const` bind the whole block too — as PENDING, so a straight-line reference above the
+ * declaration is L2004 rather than a resolution to whatever outer binding shares the name.
+ */
+function hoistBindings(block, scope) {
+    for (const s of block.body ?? []) {
+        if (s.type !== "VariableDeclaration")
+            continue;
+        const kind = s.kind === "const" ? "const" : "let";
+        for (const d of s.declarations ?? []) {
+            const names = [];
+            patternNames(d.id, names);
+            for (const n of names) {
+                scope.declare(n, kind);
+                scope.pending.add(n);
+            }
         }
     }
 }
@@ -782,8 +1213,10 @@ export function validate(source, file = "program.cotal.js") {
     }
     // The module body is an async context: a program's top level is where the workflow lives.
     walkShape(ast, v, true);
+    indexFunctions(ast, v);
     const top = new Scope(null);
     hoistFunctions(ast, top);
+    hoistBindings(ast, top);
     for (const s of ast.body ?? [])
         walkResolve(s, v, top);
     if (v.errors.length > 0)