@telorun/cel 0.0.0-stage → 0.108.0

package/dist/closure-backend.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The closure backend: a tree compiled into nested closures, with **no `eval`, no
+ * `new Function` and no disk**.
+ *
+ * Everything an expression's shape decides is decided once, at compile time — which name
+ * is a bound slot, which select is a dotted activation read, which call is a macro — so
+ * evaluating is calling closures over a frame. Semantics are not here: every operator and
+ * function is the runtime library's (`runtime-library.ts`), every comprehension is
+ * `comprehension-runtime.ts`, every member read, name read and call-site dispatch is
+ * `backend-runtime.ts`. The emitter (`js-emitter.ts`) emits calls into exactly those, which
+ * is the only way two backends can be held to one answer.
+ */
+import type { CelStep, CompileTarget } from "./backend-runtime.js";
+import type { CelNode } from "./syntax-tree.js";
+export interface CompiledTree {
+    readonly step: CelStep;
+    /** How many binding slots a frame needs. */
+    readonly slots: number;
+}
+export declare function compileTree(root: CelNode, target: CompileTarget): CompiledTree;
+//# sourceMappingURL=closure-backend.d.ts.map

package/dist/closure-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closure-backend.d.ts","sourceRoot":"","sources":["../src/closure-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyBH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiBnE,OAAO,KAAK,EAAE,OAAO,EAA8B,MAAM,kBAAkB,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAcD,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,YAAY,CAI9E"}

package/dist/closure-backend.js

@@ -0,0 +1,487 @@
+/**
+ * The closure backend: a tree compiled into nested closures, with **no `eval`, no
+ * `new Function` and no disk**.
+ *
+ * Everything an expression's shape decides is decided once, at compile time — which name
+ * is a bound slot, which select is a dotted activation read, which call is a macro — so
+ * evaluating is calling closures over a frame. Semantics are not here: every operator and
+ * function is the runtime library's (`runtime-library.ts`), every comprehension is
+ * `comprehension-runtime.ts`, every member read, name read and call-site dispatch is
+ * `backend-runtime.ts`. The emitter (`js-emitter.ts`) emits calls into exactly those, which
+ * is the only way two backends can be held to one answer.
+ */
+import { celMapFromEntries } from "./cel-map-value.js";
+import { splitDeclaredChain } from "./declared-chain.js";
+import { celError, asyncValueRefused, celNone, celSome, isCelError, isCelOptional, literalValue, } from "./cel-value.js";
+import { celAll, celExists, celExistsOne, celFilter, celMapComprehension, } from "./comprehension-runtime.js";
+import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
+import { isMacroCall } from "./macro-check.js";
+import { celIterable } from "./member-read.js";
+import { boolOperand, callSiteOf, CelCompileError, plainMemberChain, hasMember, optionalEntry, prefixCandidates, readHostValue, readName, readNameChain, readThrough, searchNameChain, } from "./backend-runtime.js";
+import { optionalOfNonZero } from "./runtime-library.js";
+function boundSlot(scope, name) {
+    for (let at = scope; at; at = at.outer)
+        if (at.name === name)
+            return at.slot;
+    return undefined;
+}
+export function compileTree(root, target) {
+    const compiler = new Compiler(target);
+    const step = compiler.compile(root, undefined);
+    return { step, slots: compiler.slots };
+}
+class Compiler {
+    target;
+    slots = 0;
+    constructor(target) {
+        this.target = target;
+    }
+    compile(node, scope) {
+        switch (node.kind) {
+            case "literal":
+                return constantStep(literalValue(node.literal));
+            case "ident":
+                return this.identStep(node, scope);
+            case "list":
+                return this.listStep(node, scope);
+            case "map":
+                return this.mapStep(node, scope);
+            case "select":
+                return this.selectStep(node, scope);
+            case "index":
+                return this.indexStep(node, scope);
+            case "unary":
+                return this.callStep(node.operator, "global", [this.compile(node.operand, scope)], node.range);
+            case "binary":
+                return this.binaryStep(node, scope);
+            case "conditional":
+                return this.conditionalStep(node, scope);
+            case "call":
+            case "receiverCall":
+                return this.anyCallStep(node, scope);
+            case "qcall":
+                return this.qualifiedCallStep(node, scope);
+            case "unparsed":
+                throw new CelCompileError("the expression could not be read whole, so it cannot be compiled");
+        }
+    }
+    // --- names --------------------------------------------------------------
+    identStep(node, scope) {
+        if (!node.absolute) {
+            const slot = boundSlot(scope, node.name);
+            if (slot !== undefined)
+                return (frame) => frame.slots[slot];
+        }
+        const { name, range } = node;
+        const { constants } = this.target;
+        return (frame) => readName(frame.activation, constants, name, range);
+    }
+    /**
+     * A chain of plain member names rooted at a free name: one activation lookup over the
+     * longest declared prefix, the rest read through the seam. The checker resolves the
+     * same chain the same way, so a host holding `a.b.c` reads that name and one holding
+     * only `a.b` reads the map's entry.
+     */
+    qualifiedChainStep(segments, range) {
+        const { constants, declares } = this.target;
+        // **A DECLARED chain splits at compile time**, through the same function the checker
+        // splits it with (`declared-chain.ts`), so evaluation performs exactly one activation
+        // read and then member reads — no search over prefixes, and no chance of reading a
+        // different name than the one the checker typed. A declared name the activation does not
+        // hold is `no_such_variable` for THAT name: falling back to a shorter prefix would read a
+        // value of a name the host did not mean.
+        const declaredSplit = splitDeclaredChain(segments, declares);
+        if (declaredSplit) {
+            const { name, rest } = declaredSplit;
+            return (frame) => readNameChain(frame.activation, constants, name, rest, range);
+        }
+        // Nothing declares a prefix of this chain, so there is nothing to split it on and the
+        // checker has no opinion either: the activation is searched, longest prefix first. Every
+        // conformance row that binds a dotted key reads this way.
+        const candidates = prefixCandidates(segments);
+        const written = segments.join(".");
+        return (frame) => searchNameChain(frame.activation, constants, candidates, written, range);
+    }
+    // --- aggregates ---------------------------------------------------------
+    listStep(node, scope) {
+        const elements = node.elements.map((element) => ({
+            step: this.compile(element.value, scope),
+            optional: element.optional,
+        }));
+        const { range } = node;
+        return (frame) => {
+            const out = [];
+            for (const element of elements) {
+                const value = element.step(frame);
+                if (isCelError(value))
+                    return value;
+                if (!element.optional) {
+                    out.push(value);
+                    continue;
+                }
+                const held = optionalEntry(value, range);
+                if (isCelError(held))
+                    return held;
+                // An absent optional entry leaves no element: the aggregate shrinks, which is
+                // the whole reason to write one.
+                if (held.present)
+                    out.push(held.held);
+            }
+            return out;
+        };
+    }
+    mapStep(node, scope) {
+        const entries = node.entries.map((entry) => ({
+            key: this.compile(entry.key, scope),
+            value: this.compile(entry.value, scope),
+            optional: entry.optional,
+        }));
+        const { range } = node;
+        return (frame) => {
+            // Flat — key, value, key, value — so a literal of n entries costs one allocation
+            // rather than one per entry. The emitter writes the same call.
+            const flat = [];
+            for (const entry of entries) {
+                const key = entry.key(frame);
+                if (isCelError(key))
+                    return key;
+                const value = entry.value(frame);
+                if (isCelError(value))
+                    return value;
+                if (!entry.optional) {
+                    flat.push(key, value);
+                    continue;
+                }
+                const held = optionalEntry(value, range);
+                if (isCelError(held))
+                    return held;
+                if (held.present)
+                    flat.push(key, held.held);
+            }
+            return celMapFromEntries(flat, range);
+        };
+    }
+    // --- member reads -------------------------------------------------------
+    selectStep(node, scope) {
+        const chain = plainMemberChain(node, (name) => boundSlot(scope, name) !== undefined);
+        if (chain)
+            return this.qualifiedChainStep(chain, node.range);
+        const operand = this.compile(node.operand, scope);
+        const { field, optional, range } = node;
+        return (frame) => {
+            const held = operand(frame);
+            if (isCelError(held))
+                return held;
+            return readThrough(held, field, optional, range);
+        };
+    }
+    indexStep(node, scope) {
+        const operand = this.compile(node.operand, scope);
+        const index = this.compile(node.index, scope);
+        const { optional, range } = node;
+        return (frame) => {
+            const held = operand(frame);
+            if (isCelError(held))
+                return held;
+            const key = index(frame);
+            if (isCelError(key))
+                return key;
+            return readThrough(held, key, optional, range);
+        };
+    }
+    // --- operators ----------------------------------------------------------
+    /**
+     * `&&` and `||` carry an error-valued operand through: `false && <error>` is `false`
+     * and `true || <error>` is `true`, whichever side the error is on. That is why a CEL
+     * error is a value — an exception thrown where it was found could not be discarded
+     * here.
+     */
+    binaryStep(node, scope) {
+        if (node.operator !== "&&" && node.operator !== "||") {
+            return this.callStep(node.operator, "global", [this.compile(node.left, scope), this.compile(node.right, scope)], node.range);
+        }
+        const left = this.compile(node.left, scope);
+        const right = this.compile(node.right, scope);
+        const { range } = node;
+        const decided = node.operator === "&&" ? false : true;
+        return (frame) => {
+            const a = boolOperand(left(frame), range);
+            if (a === decided)
+                return decided;
+            const b = boolOperand(right(frame), range);
+            if (b === decided)
+                return decided;
+            if (isCelError(a))
+                return a;
+            if (isCelError(b))
+                return b;
+            return !decided;
+        };
+    }
+    conditionalStep(node, scope) {
+        const condition = this.compile(node.condition, scope);
+        const whenTrue = this.compile(node.whenTrue, scope);
+        const whenFalse = this.compile(node.whenFalse, scope);
+        const { range } = node;
+        return (frame) => {
+            const held = boolOperand(condition(frame), range);
+            if (isCelError(held))
+                return held;
+            return held ? whenTrue(frame) : whenFalse(frame);
+        };
+    }
+    // --- calls --------------------------------------------------------------
+    anyCallStep(node, scope) {
+        // The same question the checker asks, in the same place: a macro is not a function,
+        // and it is recognised before any overload is looked for.
+        if (isMacroCall(node))
+            return this.macroStep(node, scope);
+        const form = node.kind === "call" ? "global" : "receiver";
+        const args = [
+            ...(node.kind === "receiverCall" ? [this.compile(node.receiver, scope)] : []),
+            ...node.args.map((argument) => this.compile(argument, scope)),
+        ];
+        return this.callStep(node.name, form, args, node.range);
+    }
+    /**
+     * One dispatch: evaluate the arguments, carry the first error out, then hand the values
+     * to the site **positionally**, which resolves the overload on their own types. The arity
+     * is the dispatch key's and known at compile time, so the step is chosen once here and no
+     * argument array is built per call — the same choice the emitter writes into its text.
+     */
+    callStep(name, form, args, range) {
+        const site = callSiteOf(this.target, name, form, range);
+        const [first, second, third, fourth] = args;
+        switch (args.length) {
+            case 0:
+                return () => site.call0();
+            case 1:
+                return (frame) => {
+                    const a = first(frame);
+                    return isCelError(a) ? a : site.call1(a);
+                };
+            case 2:
+                return (frame) => {
+                    const a = first(frame);
+                    if (isCelError(a))
+                        return a;
+                    const b = second(frame);
+                    return isCelError(b) ? b : site.call2(a, b);
+                };
+            case 3:
+                return (frame) => {
+                    const a = first(frame);
+                    if (isCelError(a))
+                        return a;
+                    const b = second(frame);
+                    if (isCelError(b))
+                        return b;
+                    const c = third(frame);
+                    return isCelError(c) ? c : site.call3(a, b, c);
+                };
+            case 4:
+                return (frame) => {
+                    const a = first(frame);
+                    if (isCelError(a))
+                        return a;
+                    const b = second(frame);
+                    if (isCelError(b))
+                        return b;
+                    const c = third(frame);
+                    if (isCelError(c))
+                        return c;
+                    const d = fourth(frame);
+                    return isCelError(d) ? d : site.call4(a, b, c, d);
+                };
+            default: {
+                // A call written wider than any signature may be. Its arguments are still evaluated
+                // in order, so an error in one carries out ahead of the refusal.
+                const count = args.length;
+                return (frame) => {
+                    const values = new Array(count);
+                    for (let at = 0; at < count; at += 1) {
+                        const held = args[at](frame);
+                        if (isCelError(held))
+                            return held;
+                        values[at] = held;
+                    }
+                    return site.call(values);
+                };
+            }
+        }
+    }
+    qualifiedCallStep(node, scope) {
+        const args = node.args.map((argument) => this.compile(argument, scope));
+        const { namespace, name, range } = node;
+        return (frame) => {
+            const implementation = frame.namespaceFunction?.(namespace, name);
+            if (!implementation) {
+                return celError("unbound_function", `unbound function '${namespace}.${name}' — nothing is bound under that name here`, range);
+            }
+            const values = [];
+            for (const step of args) {
+                const value = step(frame);
+                if (isCelError(value))
+                    return value;
+                values.push(value);
+            }
+            return readHostValue(implementation(values, { range }), range);
+        };
+    }
+    // --- macros -------------------------------------------------------------
+    /**
+     * Lowering a macro. There is no comprehension node to lower *to*: the macro's meaning
+     * is a call into the comprehension runtime with the body as a closure, which is the
+     * same shape the emitter produces.
+     */
+    macroStep(node, scope) {
+        if (node.kind === "call")
+            return this.hasStep(node, scope);
+        const receiver = node.receiver;
+        if (receiver.kind === "ident" && receiver.name === "cel" && node.name === "bind") {
+            return this.bindStep(node, scope);
+        }
+        if (receiver.kind === "ident" && receiver.name === "optional") {
+            return this.optionalNamespaceStep(node, scope);
+        }
+        if ((node.name === "optMap" || node.name === "optFlatMap") && node.args.length === 2) {
+            return this.optionalBindingStep(node, scope);
+        }
+        return this.comprehensionStep(node, scope);
+    }
+    /** `has(a.b)` — presence, which a missing key answers `false` rather than erroring. */
+    hasStep(node, scope) {
+        const argument = node.args[0];
+        if (argument.kind !== "select") {
+            throw new CelCompileError("has() asks about a member, so its argument ends in a select");
+        }
+        const operand = this.compile(argument.operand, scope);
+        const { field } = argument;
+        const { range } = node;
+        return (frame) => {
+            const held = operand(frame);
+            if (isCelError(held))
+                return held;
+            return hasMember(held, field, range);
+        };
+    }
+    bindStep(node, scope) {
+        const binding = namespaceMacroBinding("cel", node.name, node.args.length);
+        if (!binding) {
+            throw new CelCompileError("cel.bind(name, value, body) takes a name, its value and a body");
+        }
+        const name = node.args[binding.variableArgument];
+        if (name.kind !== "ident")
+            throw new CelCompileError("cel.bind binds a name");
+        const value = this.compile(node.args[1], scope);
+        const slot = this.slots++;
+        const body = this.compile(node.args[2], { name: name.name, slot, outer: scope });
+        const { range } = node;
+        return (frame) => {
+            const held = value(frame);
+            if (isCelError(held))
+                return held;
+            // A name is bound to a VALUE, so a value that must be awaited is refused here rather
+            // than inside the body, where every read of the name would meet it again.
+            const refused = asyncValueRefused(held, range);
+            if (refused)
+                return refused;
+            frame.slots[slot] = held;
+            return body(frame);
+        };
+    }
+    /** `optional.of(v)`, `optional.ofNonZeroValue(v)` and `optional.none()`. */
+    optionalNamespaceStep(node, scope) {
+        if (node.name === "none")
+            return constantStep(celNone());
+        if (node.args.length !== 1) {
+            throw new CelCompileError(`optional.${node.name}(value) takes one argument`);
+        }
+        const value = this.compile(node.args[0], scope);
+        const nonZero = node.name === "ofNonZeroValue";
+        return (frame) => {
+            const held = value(frame);
+            if (isCelError(held))
+                return held;
+            return nonZero ? optionalOfNonZero(held) : celSome(held);
+        };
+    }
+    /** `opt.optMap(v, body)` wraps what the body answers; `optFlatMap` does not. */
+    optionalBindingStep(node, scope) {
+        const name = node.args[0];
+        if (name.kind !== "ident")
+            throw new CelCompileError(`${node.name} binds a name`);
+        const receiver = this.compile(node.receiver, scope);
+        const slot = this.slots++;
+        const body = this.compile(node.args[1], { name: name.name, slot, outer: scope });
+        const wrap = node.name === "optMap";
+        const { range } = node;
+        return (frame) => {
+            const held = receiver(frame);
+            if (isCelError(held))
+                return held;
+            if (!isCelOptional(held)) {
+                return celError("no_matching_overload", `${JSON.stringify(node.name)} reads an optional`, range);
+            }
+            if (!held.present)
+                return celNone();
+            // A host may hand over the optional itself, so what it HOLDS is a door of its own.
+            const refused = asyncValueRefused(held.held, range);
+            if (refused)
+                return refused;
+            frame.slots[slot] = held.held;
+            const answered = body(frame);
+            if (isCelError(answered))
+                return answered;
+            if (wrap)
+                return celSome(answered);
+            if (isCelOptional(answered))
+                return answered;
+            return celError("no_matching_overload", "optFlatMap's body answers an optional", range);
+        };
+    }
+    comprehensionStep(node, scope) {
+        const binding = receiverMacroBinding(node.name, node.args.length);
+        if (!binding)
+            throw new CelCompileError(`${node.name} is not a comprehension`);
+        const name = node.args[binding.variableArgument];
+        if (name.kind !== "ident")
+            throw new CelCompileError(`${node.name} binds a name`);
+        const receiver = this.compile(node.receiver, scope);
+        const slot = this.slots++;
+        const inner = { name: name.name, slot, outer: scope };
+        const scoped = binding.scopedArguments.map((at) => this.compile(node.args[at], inner));
+        const { range } = node;
+        const macro = node.name;
+        return (frame) => {
+            const held = receiver(frame);
+            if (isCelError(held))
+                return held;
+            const elements = celIterable(held, range);
+            if (isCelError(elements))
+                return elements;
+            const run = (step) => (element) => {
+                frame.slots[slot] = element;
+                return step(frame);
+            };
+            switch (macro) {
+                case "all":
+                    return celAll(elements, run(scoped[0]), range);
+                case "exists":
+                    return celExists(elements, run(scoped[0]), range);
+                case "exists_one":
+                    return celExistsOne(elements, run(scoped[0]), range);
+                case "filter":
+                    return celFilter(elements, run(scoped[0]), range);
+                default:
+                    return scoped.length === 2
+                        ? celMapComprehension(elements, run(scoped[1]), run(scoped[0]), range)
+                        : celMapComprehension(elements, run(scoped[0]), undefined, range);
+            }
+        };
+    }
+}
+// --- the pieces the steps are built from ------------------------------------
+function constantStep(value) {
+    return () => value;
+}

package/dist/comprehension-bindings.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Which calls bind a name, and where that name is in scope.
+ *
+ * The comprehension macros and `cel.bind` introduce an identifier that is written
+ * as an ordinary argument: in `xs.map(i, i + 1)` the first `i` declares a name and
+ * the second reads it. Nothing expands these calls in the front end, so the free
+ * variables of an expression cannot be found without knowing this — otherwise `i`
+ * would be reported as a name the expression reads from its environment.
+ *
+ * It is DATA, so the checker and a backend lower exactly the forms the
+ * free-variable query already accounts for. An arity not listed here binds nothing:
+ * `xs.all(k, v, p)` is not a form the language has, and inventing a binding for it
+ * would hide the name `k` from a reader of the query.
+ */
+export interface ComprehensionBinding {
+    /** The argument that is the bound name. */
+    readonly variableArgument: number;
+    /** The arguments evaluated with that name in scope. */
+    readonly scopedArguments: readonly number[];
+}
+/**
+ * Every form that binds a value into a body, as the table keys them — the receiver macros and
+ * `cel.bind`.
+ *
+ * It is here because the table is the only enumeration of them there is, and two places that
+ * list the binding forms is how one of them comes to be missing a form: a value entering a
+ * body is a door a host value comes through, and `tests/evaluate.test.ts` holds this list to a
+ * probe per form, so a tenth form cannot be added without being guarded.
+ */
+export declare const BINDING_FORMS: readonly string[];
+export declare function receiverMacroBinding(name: string, arity: number): ComprehensionBinding | undefined;
+export declare function namespaceMacroBinding(namespace: string, name: string, arity: number): ComprehensionBinding | undefined;
+//# sourceMappingURL=comprehension-bindings.d.ts.map

package/dist/comprehension-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comprehension-bindings.d.ts","sourceRoot":"","sources":["../src/comprehension-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAqBD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAG1C,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAElG;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,oBAAoB,GAAG,SAAS,CAElC"}

package/dist/comprehension-bindings.js

@@ -0,0 +1,50 @@
+/**
+ * Which calls bind a name, and where that name is in scope.
+ *
+ * The comprehension macros and `cel.bind` introduce an identifier that is written
+ * as an ordinary argument: in `xs.map(i, i + 1)` the first `i` declares a name and
+ * the second reads it. Nothing expands these calls in the front end, so the free
+ * variables of an expression cannot be found without knowing this — otherwise `i`
+ * would be reported as a name the expression reads from its environment.
+ *
+ * It is DATA, so the checker and a backend lower exactly the forms the
+ * free-variable query already accounts for. An arity not listed here binds nothing:
+ * `xs.all(k, v, p)` is not a form the language has, and inventing a binding for it
+ * would hide the name `k` from a reader of the query.
+ */
+/** Keyed by `<name>/<arity>` for a call on a value. */
+const RECEIVER_MACROS = new Map([
+    ["all/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["exists/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["exists_one/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["filter/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["map/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["map/3", { variableArgument: 0, scopedArguments: [1, 2] }],
+    // The optional library's two: each binds the held value under a name, for the one
+    // expression that reads it.
+    ["optMap/2", { variableArgument: 0, scopedArguments: [1] }],
+    ["optFlatMap/2", { variableArgument: 0, scopedArguments: [1] }],
+]);
+/** Keyed by `<namespace>.<name>/<arity>` for a call on a reserved namespace. */
+const NAMESPACE_MACROS = new Map([
+    ["cel.bind/3", { variableArgument: 0, scopedArguments: [2] }],
+]);
+/**
+ * Every form that binds a value into a body, as the table keys them — the receiver macros and
+ * `cel.bind`.
+ *
+ * It is here because the table is the only enumeration of them there is, and two places that
+ * list the binding forms is how one of them comes to be missing a form: a value entering a
+ * body is a door a host value comes through, and `tests/evaluate.test.ts` holds this list to a
+ * probe per form, so a tenth form cannot be added without being guarded.
+ */
+export const BINDING_FORMS = [
+    ...RECEIVER_MACROS.keys(),
+    ...NAMESPACE_MACROS.keys(),
+];
+export function receiverMacroBinding(name, arity) {
+    return RECEIVER_MACROS.get(`${name}/${arity}`);
+}
+export function namespaceMacroBinding(namespace, name, arity) {
+    return NAMESPACE_MACROS.get(`${namespace}.${name}/${arity}`);
+}

package/dist/comprehension-runtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a comprehension macro **does**, as a function of its range and its body.
+ *
+ * The macros are lowered by each backend — there is no comprehension node in the tree,
+ * because expanding one at read time would make the source unwritable from the tree —
+ * but what the lowering *means* lives here, once. The closure backend passes a closure
+ * as the body and the emitter will pass an emitted function, and both get the same
+ * answers, including the error rules.
+ *
+ * **An error does not win over a decided answer**, with the one exception named below: `all`
+ * is `false` as soon as one element is false even if another errors, and `exists` is `true` as
+ * soon as one is true. That is the same rule `&&` and `||` follow, and it is what makes a
+ * comprehension over partly-unreadable data usable at all.
+ *
+ * **An element entering a body is a door a host value comes through**, and it is checked for a
+ * thenable here — in the one place a comprehension's meaning lives, so both backends inherit it
+ * rather than each remembering to. It is not the leak it looks like: `xs.all(e, true)` over a
+ * host list holding a promise used to answer **`true`**, having decided something about a value
+ * it never touched, which is the worse half of the failure class. The cost is one `typeof` per
+ * element, the same check the member read already makes, on a loop that already calls a closure
+ * per element.
+ *
+ * **That refusal is TERMINAL, and it is the one error here that does not short-circuit.** It is
+ * checked where the element is BOUND, before the body runs, and it ends the comprehension
+ * whatever a later element would have decided — so `xs.all(e, false)` and `xs.exists(e, true)`
+ * refuse rather than answering `false` and `true` off the one element that is readable. The
+ * distinction is what the error is ABOUT: `no_such_key` is a fact about one datum, so a decided
+ * answer may legitimately outrank it, while a value that must be awaited says the host handed
+ * this engine something it cannot evaluate at all. Carrying that past a convenient element makes
+ * the answer depend on how many elements happen to be readable and in what order — and the rule
+ * is subtle enough that two readers in a row took the discardable refusal for a leak instead.
+ */
+import type { CelValue } from "./cel-value.js";
+import type { SourceRange } from "./syntax-tree.js";
+/** The body of a comprehension: the value its expression answers for one element. */
+export type ComprehensionBody = (element: CelValue) => CelValue;
+export declare function celAll(elements: readonly CelValue[], body: ComprehensionBody, range?: SourceRange): CelValue;
+export declare function celExists(elements: readonly CelValue[], body: ComprehensionBody, range?: SourceRange): CelValue;
+/** Exactly one element satisfies the test. An error anywhere leaves no count to trust. */
+export declare function celExistsOne(elements: readonly CelValue[], body: ComprehensionBody, range?: SourceRange): CelValue;
+export declare function celFilter(elements: readonly CelValue[], body: ComprehensionBody, range?: SourceRange): CelValue;
+/** `map` in both arities: with a filter, an element the filter drops is not transformed. */
+export declare function celMapComprehension(elements: readonly CelValue[], transform: ComprehensionBody, filter?: ComprehensionBody, range?: SourceRange): CelValue;
+//# sourceMappingURL=comprehension-runtime.d.ts.map

package/dist/comprehension-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comprehension-runtime.d.ts","sourceRoot":"","sources":["../src/comprehension-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAgChE,wBAAgB,MAAM,CACpB,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,WAAW,GAClB,QAAQ,CAUV;AAED,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,WAAW,GAClB,QAAQ,CAUV;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,WAAW,GAClB,QAAQ,CAUV;AAED,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,IAAI,EAAE,iBAAiB,EACvB,KAAK,CAAC,EAAE,WAAW,GAClB,QAAQ,CAUV;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAC7B,SAAS,EAAE,iBAAiB,EAC5B,MAAM,CAAC,EAAE,iBAAiB,EAC1B,KAAK,CAAC,EAAE,WAAW,GAClB,QAAQ,CAeV"}