@telorun/cel 0.107.0 → 0.108.0

package/src/cel-value.ts

@@ -82,12 +82,20 @@ export interface CelMapValueEntry {
 }
 
 /**
- * A map. Entries live in a `Map` keyed by the canonical text of each key, so the map
- * holds int, uint, bool and string keys alike and **no key is ever a property name**:
+ * What identifies a key inside a map's entries. A `Map` distinguishes its own keys **by
+ * type**, so the four CEL key types collapse onto three JS ones with no namespace to
+ * separate by hand: a string key is itself, a bool is itself, and an int, a uint and a
+ * whole double are all the `bigint` CEL equality makes them.
+ */
+export type CelMapKey = string | bigint | boolean;
+
+/**
+ * A map. Entries live in a `Map` keyed by each key's own `CelMapKey`, so the map holds
+ * int, uint, bool and string keys alike and **no key is ever a property name**:
  * `__proto__`, `constructor` and `prototype` are data here, as they are in any map.
  */
 export interface CelMap extends Branded<"map"> {
-  readonly entries: ReadonlyMap<string, CelMapValueEntry>;
+  readonly entries: ReadonlyMap<CelMapKey, CelMapValueEntry>;
 }
 
 /** Every evaluation failure this engine names. A code is never derived from a message. */

package/src/check-diagnostic.ts

@@ -67,12 +67,14 @@ export interface CelCheckDiagnostic {
  * refusal to compile a tree the front end already reported a syntax diagnostic for,
  * which is a question the caller should have asked before compiling, and
  * `emitted_module_rejected` is the refusal to run a loaded module whose integrity header
- * is not the one the emission asked for.
+ * is not the one the emission asked for, and `signature_too_wide` is a registration
+ * declaring more values than an implementation receives.
  */
 export type CelEngineErrorCode =
   | "namespaces_mismatch"
   | "unreadable_expression"
-  | "emitted_module_rejected";
+  | "emitted_module_rejected"
+  | "signature_too_wide";
 
 export class CelEngineError extends Error {
   readonly code: CelEngineErrorCode;

package/src/checker.ts

@@ -80,6 +80,15 @@ export interface NamespaceFunction {
   readonly parameters?: readonly CelType[];
   /** How the declaration is written, for a listing; absent with the parameters. */
   readonly signature?: string;
+  /**
+   * Types the declaration named that nothing is registered under, in the order written.
+   *
+   * The declaration is accepted and reads `dyn` where one stands: a host's declaration is
+   * data out of someone's manifest, so a name its own registry does not carry is the host
+   * disagreeing with itself — reported at the call, where there is a range, rather than
+   * thrown at registration, where there is none. Same rule as an unjudged schema node.
+   */
+  readonly unregisteredTypes?: readonly string[];
   readonly deterministic?: boolean;
   readonly hostBacked?: boolean;
   readonly throws?: readonly string[];
@@ -171,6 +180,10 @@ class Checker implements MacroHost {
     }
   }
 
+  typeOfPresence(node: Extract<CelNode, { kind: "select" }>): CelType {
+    return this.selectType(node, true);
+  }
+
   // --- the walk -----------------------------------------------------------
 
   typeOf(node: CelNode): CelType {
@@ -186,7 +199,7 @@ class Checker implements MacroHost {
       case "map":
         return this.mapType(node);
       case "select":
-        return this.selectType(node);
+        return this.selectType(node, node.optional);
       case "index":
         return this.indexType(node);
       case "unary":
@@ -318,13 +331,19 @@ class Checker implements MacroHost {
     return reduced;
   }
 
-  private selectType(node: Extract<CelNode, { kind: "select" }>): CelType {
+  /**
+   * `presence` is whether the read asks whether the member is THERE — written `.?b`, or
+   * standing as the argument of `has()`. It decides nothing about a type that is known to
+   * hold no members, which both forms refuse; it decides what a UNION's member-less
+   * branches are, which is the absence case a presence-shaped read answers for.
+   */
+  private selectType(node: Extract<CelNode, { kind: "select" }>, presence: boolean): CelType {
     const qualified = this.qualifiedVariableType(node);
     if (qualified) return qualified;
     const operand = this.typeOf(node.operand);
     if (node.field === "") return DYN;
     const guarded = this.checkNullable(node.operand, operand, `.${node.field}`, node.fieldRange);
-    const held = this.memberType(guarded, node.field, node.fieldRange);
+    const held = this.memberType(guarded, node.field, node.fieldRange, presence);
     // Reading through an optional answers an optional, whichever form the read is
     // written in: that is what makes a chain of reads over a value that may be absent
     // stay one expression instead of needing a guard at every step.
@@ -367,11 +386,22 @@ class Checker implements MacroHost {
   }
 
   /** The type of a named member, reported against whatever the operand turned out to be. */
-  private memberType(operand: CelType, field: string, range: SourceRange): CelType {
+  private memberType(
+    operand: CelType,
+    field: string,
+    range: SourceRange,
+    presence = false,
+  ): CelType {
     if (isDyn(operand) || operand.kind === "parameter") return DYN;
-    if (operand.kind === "optional") return this.memberType(operand.value, field, range);
+    if (operand.kind === "optional") {
+      return this.memberType(operand.value, field, range, presence);
+    }
     if (operand.kind === "union") {
-      return unionOf(operand.members.map((member) => this.memberType(member, field, range)));
+      return unionOf(
+        presenceBranches(operand, holdsMembers, presence).map((member) =>
+          this.memberType(member, field, range, presence),
+        ),
+      );
     }
     if (operand.kind === "record") return this.recordMemberType(operand, field, range);
     if (operand.kind === "map") {
@@ -406,7 +436,7 @@ class Checker implements MacroHost {
     const operand = this.typeOf(node.operand);
     const index = this.typeOf(node.index);
     const guarded = this.checkNullable(node.operand, operand, "[…]", node.range);
-    const held = this.elementType(guarded, index, node);
+    const held = this.elementType(guarded, index, node, node.optional);
     return node.optional || guarded.kind === "optional" ? optionalOf(unwrapOptional(held)) : held;
   }
 
@@ -414,11 +444,18 @@ class Checker implements MacroHost {
     operand: CelType,
     index: CelType,
     node: Extract<CelNode, { kind: "index" }>,
+    presence = false,
   ): CelType {
     if (isDyn(operand) || operand.kind === "parameter") return DYN;
-    if (operand.kind === "optional") return this.elementType(operand.value, index, node);
+    if (operand.kind === "optional") {
+      return this.elementType(operand.value, index, node, presence);
+    }
     if (operand.kind === "union") {
-      return unionOf(operand.members.map((member) => this.elementType(member, index, node)));
+      return unionOf(
+        presenceBranches(operand, holdsElements, presence).map((member) =>
+          this.elementType(member, index, node, presence),
+        ),
+      );
     }
     if (operand.kind === "list") {
       if (!assignable(index, INT) && !isDyn(index)) {
@@ -659,7 +696,7 @@ class Checker implements MacroHost {
     if (failure.reason === "unknown") {
       this.report(
         "CEL_UNKNOWN_FUNCTION",
-        `no function named ${JSON.stringify(node.name)} is registered`,
+        `no function named ${JSON.stringify(node.name)} is registered${this.closestNames(node.name, form, args.length)}`,
         node.range,
         this.renameFix(node),
       );
@@ -690,6 +727,28 @@ class Checker implements MacroHost {
     );
   }
 
+  /**
+   * What a call on an unregistered name is offered instead: the registered names that
+   * accept its form and arity, nearest first, as a clause to hang off the refusal.
+   *
+   * **The alternatives belong in the MESSAGE, and the fix stays singular.** A reader of
+   * `no('x')` is one name away from the five functions that would have worked, and the
+   * engine this one replaces said so; losing it is a real loss of help. A list of five
+   * repairs, though, is not a repair — an editor applying one would be guessing which
+   * function the author meant — so the single rename fix is still offered only where
+   * exactly one name is a case-insensitive match.
+   *
+   * It names no command and no tool: which listing a host offers is the host's, and an
+   * engine embedded in one with no CLI would be pointing at nothing.
+   */
+  private closestNames(name: string, form: CallForm, arity: number): string {
+    const candidates = this.context.registry.candidateNames(name, form, arity);
+    if (candidates.length === 0) return "";
+    const written = arity === 0 ? "no arguments" : arity === 1 ? "1 argument" : `${arity} arguments`;
+    const shape = form === "receiver" ? `written on a value with ${written}` : `taking ${written}`;
+    return ` — the closest ${shape}: ${candidates.join(", ")}`;
+  }
+
   /** The one registered name this call might have meant, as a whole-source repair. */
   private renameFix(node: CelCallNode | CelReceiverCallNode): CelDiagnosticFix | undefined {
     const wanted = node.name.toLowerCase();
@@ -757,6 +816,7 @@ class Checker implements MacroHost {
         namespace: node.namespace,
         arity: args.length,
         range: node.range,
+        argumentTypes: args.map((type) => formatType(withoutParameters(type))),
       });
       // An OPEN namespace declares only part of what it reaches, so a name it does not
       // carry is not this engine's to refuse — it is listed and left to the host.
@@ -775,12 +835,27 @@ class Checker implements MacroHost {
       namespace: node.namespace,
       arity: args.length,
       range: node.range,
+      argumentTypes: args.map((type) => formatType(withoutParameters(type))),
       ...(declared.signature === undefined ? {} : { signature: declared.signature }),
       returns: formatType(withoutParameters(declared.returns)),
       deterministic: declared.deterministic ?? true,
       hostBacked: declared.hostBacked ?? false,
       ...(declared.throws ? { throws: declared.throws } : {}),
     });
+    // A type the host named and its own registry does not carry: the declaration stands,
+    // reads `dyn` where that type stood, and the disagreement is a verdict HERE — this is
+    // the only place the name has a range.
+    const unregistered = declared.unregisteredTypes ?? [];
+    if (unregistered.length > 0) {
+      const names = unregistered.map((name) => JSON.stringify(name)).join(", ");
+      this.report(
+        "CEL_TYPE_ERROR",
+        unregistered.length === 1
+          ? `${qualified} is declared over the type ${names}, and no type is registered under that name`
+          : `${qualified} is declared over the types ${names}, and no type is registered under those names`,
+        node.range,
+      );
+    }
     // Parameters withheld: the host judges arity and arguments against its own, richer
     // signature grammar, and this engine types the result and says nothing else.
     if (parameters === undefined) return declared.returns;
@@ -815,6 +890,44 @@ function isNullTest(args: readonly CelType[]): boolean {
   return (isNull(left) && admitsNull(right)) || (isNull(right) && admitsNull(left));
 }
 
+/**
+ * Which branches of a union a read is judged against.
+ *
+ * A **presence-shaped** read — `a.?b`, `a[?k]`, `has(a.b)` — asks whether the member is
+ * THERE, so a branch that can hold no member at all is the absence case it answers
+ * `optional.none()` / `false` for at runtime, not a mistake in the expression: that is how
+ * a two-shape field is discriminated without a type test. Where **no** branch can hold one
+ * the read is judged against them all, so an operand that is known to hold no members is
+ * still refused in the presence form exactly as in the plain one.
+ */
+function presenceBranches(
+  union: Extract<CelType, { kind: "union" }>,
+  holds: (type: CelType) => boolean,
+  presence: boolean,
+): readonly CelType[] {
+  if (!presence) return union.members;
+  const holding = union.members.filter(holds);
+  return holding.length > 0 ? holding : union.members;
+}
+
+/** Whether a type can hold a named member at all — what `memberType` reads one of. */
+function holdsMembers(type: CelType): boolean {
+  if (isDyn(type) || type.kind === "parameter") return true;
+  if (type.kind === "record" || type.kind === "map") return true;
+  if (type.kind === "optional") return holdsMembers(type.value);
+  if (type.kind === "union") return type.members.some(holdsMembers);
+  return false;
+}
+
+/** Whether a type can hold an element at all — what `elementType` reads one of. */
+function holdsElements(type: CelType): boolean {
+  if (isDyn(type) || type.kind === "parameter") return true;
+  if (type.kind === "record" || type.kind === "map" || type.kind === "list") return true;
+  if (type.kind === "optional") return holdsElements(type.value);
+  if (type.kind === "union") return type.members.some(holdsElements);
+  return false;
+}
+
 /** An optional of an optional is one optional; a chain of reads does not nest them. */
 function unwrapOptional(type: CelType): CelType {
   return type.kind === "optional" ? unwrapOptional(type.value) : type;

package/src/closure-backend.ts

@@ -186,21 +186,23 @@ class Compiler {
     }));
     const { range } = node;
     return (frame) => {
-      const pairs: [CelValue, CelValue][] = [];
+      // 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: CelValue[] = [];
       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) {
-          pairs.push([key, value]);
+          flat.push(key, value);
           continue;
         }
         const held = optionalEntry(value, range);
         if (isCelError(held)) return held;
-        if (held.present) pairs.push([key, held.held as CelValue]);
+        if (held.present) flat.push(key, held.held as CelValue);
       }
-      return celMapFromEntries(pairs, range);
+      return celMapFromEntries(flat, range);
     };
   }
 
@@ -297,20 +299,63 @@ class Compiler {
 
   /**
    * One dispatch: evaluate the arguments, carry the first error out, then hand the values
-   * to the site, which resolves the overload on their own types.
+   * 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.
    */
   private callStep(name: string, form: CallForm, args: readonly CelStep[], range: SourceRange): CelStep {
     const site = callSiteOf(this.target, name, form, range);
-    const count = args.length;
-    return (frame) => {
-      const values: CelValue[] = new Array<CelValue>(count);
-      for (let at = 0; at < count; at += 1) {
-        const value = args[at]!(frame);
-        if (isCelError(value)) return value;
-        values[at] = value;
+    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: CelValue[] = new Array<CelValue>(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);
+        };
       }
-      return site.call(values);
-    };
+    }
   }
 
   private qualifiedCallStep(

package/src/duration-value.ts

@@ -23,7 +23,7 @@
  * own spelling, and the one plain encoding a duration has wherever it is written down.
  */
 
-import { celError, CEL_VALUE_TYPE, type CelDuration, type CelError } from "./cel-value.js";
+import { celError, CEL_VALUE_TYPE, isCelError, type CelDuration, type CelError } from "./cel-value.js";
 import type { SourceRange } from "./syntax-tree.js";
 
 /** The widest and narrowest total a duration holds, in nanoseconds: int64. */
@@ -78,6 +78,21 @@ const PART = /([0-9]*)(?:\.([0-9]*))?(ns|us|µs|μs|ms|s|m|h)/g;
  * `ns`, `us`, `ms`, `s`, `m` and `h` (`1h30m`, `1.5s`, `-10m`).
  */
 export function parseDuration(text: string, range?: SourceRange): CelDuration | CelError {
+  const total = durationNanosFromText(text, range);
+  return isCelError(total) ? total : celDurationFromNanos(total, range);
+}
+
+/**
+ * The same text as a TOTAL OF NANOSECONDS, with no range applied.
+ *
+ * The grammar and the range are separate questions, and a consumer outside CEL has the same
+ * grammar with a different range: protobuf's `google.protobuf.Duration` reaches ±10,000
+ * years, which **cannot be held in an int64 of nanoseconds at all**, so a reader that must
+ * carry one (a journal entry, a value off a transport) cannot go through `parseDuration` and
+ * would otherwise restate this grammar. It answers an unbounded `bigint`; applying a range
+ * is the caller's, and `celDurationFromNanos` is what applies CEL's.
+ */
+export function durationNanosFromText(text: string, range?: SourceRange): bigint | CelError {
   const refuse = () =>
     celError("invalid_conversion", `${JSON.stringify(text)} is not a duration`, range);
   let body = text;
@@ -86,7 +101,7 @@ export function parseDuration(text: string, range?: SourceRange): CelDuration |
     negative = body.startsWith("-");
     body = body.slice(1);
   }
-  if (body === "0") return celDurationFromNanos(0n, range);
+  if (body === "0") return 0n;
   if (body === "") return refuse();
   PART.lastIndex = 0;
   let total = 0n;
@@ -104,7 +119,7 @@ export function parseDuration(text: string, range?: SourceRange): CelDuration |
     at += whole.length;
   }
   if (at !== body.length) return refuse();
-  return celDurationFromNanos(negative ? -total : total, range);
+  return negative ? -total : total;
 }
 
 /** Seconds with an `s` suffix, the fraction trimmed to what it carries. */

package/src/emitted-module.ts

@@ -94,7 +94,7 @@ import type { CelNode } from "./syntax-tree.js";
  * code the emitter writes for a corpus drawn from the package's own total enumerations, beside
  * this number, so a change to that text fails naming the bump it owes.
  */
-export const EMITTER_FORMAT_GENERATION = 1;
+export const EMITTER_FORMAT_GENERATION = 2;
 
 /** The prefix of the one line a stored module's header is read from. */
 const HEADER_PREFIX = "//@telo.cel ";

package/src/engine-version.ts

@@ -6,4 +6,4 @@
 // integrity header, so a module one build wrote is never run by another.
 
 /** This build of the CEL engine, as an emitted module names it. */
-export const ENGINE_VERSION = "0.107.0";
+export const ENGINE_VERSION = "0.108.0";

package/src/environment.ts

@@ -37,7 +37,7 @@ import { environmentDigest } from "./environment-digest.js";
 import type { CelValue } from "./cel-value.js";
 import { CEL_VALUE_KEYS } from "./cel-value.js";
 import type { CelType } from "./cel-type.js";
-import { formatType } from "./cel-type.js";
+import { DYN, formatType } from "./cel-type.js";
 import { CelEngineError } from "./check-diagnostic.js";
 import type { CheckResult, NamespaceFunction } from "./checker.js";
 import { checkExpression } from "./checker.js";
@@ -182,6 +182,14 @@ export interface SchemaRegistrationReport {
  * by construction rather than by a flag: a declaration that carried parameters and asked for
  * them to be ignored would hold a list nothing reads, which no reader can tell from a list
  * that is simply wrong.
+ *
+ * **A type name this environment registers nothing under is accepted and reads `dyn`**, and
+ * every call to such a function carries a ranged `CEL_TYPE_ERROR` naming it. A declaration
+ * is a host's own data — a module function's declared result out of a manifest — so a typo
+ * in one is the host disagreeing with its own registry, which is reported where there is a
+ * range rather than thrown where there is none. A type registered AFTER a declaration naming
+ * it does not change that declaration: a declaration resolves its types once, when it is
+ * made.
  */
 export type NamespaceFunctionDeclaration = (
   | { readonly signature: string; readonly name?: never; readonly returns?: never }
@@ -443,8 +451,21 @@ export class CelEnvironment {
         ...(entry.hostBacked === undefined ? {} : { hostBacked: entry.hostBacked }),
         ...(entry.throws === undefined ? {} : { throws: entry.throws }),
       };
+      // A name this environment registers no type under is RECORDED and read as `dyn`,
+      // never thrown: a namespace declaration is a host's own data — a module function's
+      // declared result out of a manifest — so a typo there would otherwise be a crash
+      // with no line, and the consumer that knows where it was written is the one that
+      // can anchor the diagnostic. The checker reports it at each call.
+      const unregistered: string[] = [];
+      const resolver: NominalResolver = (named, args) => {
+        const resolved = this.nominalResolver(named, args);
+        if (resolved) return resolved;
+        if (!unregistered.includes(named)) unregistered.push(named);
+        return DYN;
+      };
+      const recorded = () => (unregistered.length > 0 ? { unregisteredTypes: [...unregistered] } : {});
       if (entry.signature !== undefined) {
-        const signature = parseSignature(entry.signature, this.nominalResolver);
+        const signature = parseSignature(entry.signature, resolver);
         if (signature.form !== "global") {
           throw new CelTypeRegistrationError(
             `a namespaced function is declared without a receiver: ${JSON.stringify(entry.signature)}`,
@@ -455,6 +476,7 @@ export class CelEnvironment {
           returns: signature.returns,
           parameters: signature.parameters,
           signature: formatSignature(signature),
+          ...recorded(),
           ...flags,
         });
         continue;
@@ -462,9 +484,8 @@ export class CelEnvironment {
       declared.set(entry.name, {
         name: entry.name,
         returns:
-          typeof entry.returns === "string"
-            ? parseTypeExpression(entry.returns, this.nominalResolver)
-            : entry.returns,
+          typeof entry.returns === "string" ? parseTypeExpression(entry.returns, resolver) : entry.returns,
+        ...recorded(),
         ...flags,
       });
     }

package/src/function-registry.ts

@@ -15,10 +15,13 @@
  * once, with the candidates it considered.
  */
 
+import { CelEngineError } from "./check-diagnostic.js";
 import type { CelType } from "./cel-type.js";
-import { assignable, DYN, formatType, isDyn } from "./cel-type.js";
+import { assignable, DYN, formatType, isDyn, typesEqual } from "./cel-type.js";
 import type { CallForm, CelSignature, FunctionMetadata } from "./signature.js";
 import { formatSignature, signatureKey } from "./signature.js";
+import { CALL_SITE_DIRECT_ARITY } from "./runtime-library.js";
+import { isIdentifierSpelling, isReservedWord } from "./reserved-words.js";
 
 export interface RegisteredFunction {
   readonly signature: CelSignature;
@@ -33,6 +36,16 @@ export type ResolutionFailure =
   /** The name and form are registered; no overload takes these arguments. */
   | { readonly reason: "no-overload"; readonly candidates: readonly RegisteredFunction[] };
 
+/**
+ * How many names a refused call may name as candidates.
+ *
+ * It is **declared** rather than left to a message's taste, because the conformance
+ * vectors pin that message byte for byte: a bound and an order a second engine cannot
+ * reproduce would be a row no port can pass. The order is edit distance then name, both
+ * over the name exactly as it was written.
+ */
+export const UNKNOWN_FUNCTION_CANDIDATES = 5;
+
 export interface Resolution {
   readonly resolved: RegisteredFunction;
   /** The return type with every type parameter substituted by what this call bound. */
@@ -51,6 +64,16 @@ export class FunctionRegistry {
 
   /** Registers a function, replacing any registration answering the same call. */
   register(signature: CelSignature, metadata: FunctionMetadata = {}): void {
+    // An implementation receives its arguments positionally, up to the bound, so a wider
+    // signature is refused HERE rather than resolved and then called with its tail dropped.
+    // A declared bound nothing enforces is the silent wrong answer it exists to prevent.
+    const arity = signature.parameters.length + (signature.form === "receiver" ? 1 : 0);
+    if (arity > CALL_SITE_DIRECT_ARITY) {
+      throw new CelEngineError(
+        "signature_too_wide",
+        `${formatSignature(signature)} takes ${arity} values and an implementation receives at most ${CALL_SITE_DIRECT_ARITY}`,
+      );
+    }
     const entries = this.byName.get(signature.name) ?? [];
     const key = signatureKey(signature);
     const at = entries.findIndex((entry) => signatureKey(entry.signature) === key);
@@ -93,6 +116,38 @@ export class FunctionRegistry {
     return this.byName.get(name) ?? [];
   }
 
+  /**
+   * The names this environment registers that would accept a call of that form and
+   * arity, nearest first — what a call on a name nothing registers is offered instead.
+   *
+   * **Form and arity are a filter rather than a ranking**, because a nearer name a call
+   * cannot be written on is not a repair: `'a'.size()` is not helped by `size`. A name
+   * that is not a name is filtered for the same reason — the operators register under
+   * their own symbols (`!`, `-`, `+`), and `no(1)` offered `!` and `-` as its two
+   * nearest spellings, neither of which can be written as a call at all. Among what
+   * passes the filter the order is edit distance then name, and the list is cut at
+   * {@link UNKNOWN_FUNCTION_CANDIDATES} — a declared bound and a declared order, so the
+   * message is the same text on every engine. Distance is counted over the name as
+   * written, with no case folding: a port reproduces one rule and not a host language's
+   * notion of lower case.
+   */
+  candidateNames(wanted: string, form: CallForm, arity: number): readonly string[] {
+    const matching: string[] = [];
+    for (const [name, entries] of this.byName) {
+      if (name === wanted) continue;
+      if (!isIdentifierSpelling(name) || isReservedWord(name)) continue;
+      const accepts = entries.some(
+        (entry) => entry.signature.form === form && entry.signature.parameters.length === arity,
+      );
+      if (accepts) matching.push(name);
+    }
+    return matching
+      .map((name) => ({ name, distance: editDistance(wanted, name) }))
+      .sort((left, right) => left.distance - right.distance || compareNames(left.name, right.name))
+      .slice(0, UNKNOWN_FUNCTION_CANDIDATES)
+      .map((candidate) => candidate.name);
+  }
+
   /**
    * The function a call resolves to. `receiver` is the type the call is written on,
    * absent for a global call.
@@ -114,11 +169,41 @@ export class FunctionRegistry {
     // unlisted variable from turning one mistake into two.
     const exact = this.match(viable, args, receiver, false);
     if (exact) return exact;
-    const loose = this.match(viable, args, receiver, true);
+    const loose = this.matchLoosely(viable, args, receiver);
     if (loose) return loose;
     return { reason: "no-overload", candidates: inForm };
   }
 
+  /**
+   * The loose pass: a `dyn` argument makes a candidate viable, and **where several become
+   * viable and they do not agree on a return type, the call answers `dyn`.**
+   *
+   * Taking the first one instead is a concrete type nothing established. `dyn('a') +
+   * dyn('b')` answered `int` — the first `+` overload — so a host that declares nothing
+   * about a name had `a + b` typed `int`, and a consumer comparing that against a declared
+   * `string` slot refused a manifest that runs correctly. The honest answer is the one the
+   * engine's own design already states: overloads are resolved per call site on the VALUES'
+   * own types, so a `dyn` operand is exactly the case where the static answer is unknown.
+   *
+   * The candidate is still carried for the caller that wants one (a listing, a flag), and a
+   * single viable overload still answers its own return type — `dyn` only where they differ.
+   */
+  private matchLoosely(
+    candidates: readonly RegisteredFunction[],
+    args: readonly CelType[],
+    receiver: CelType | undefined,
+  ): Resolution | undefined {
+    const viable: Resolution[] = [];
+    for (const candidate of candidates) {
+      const held = this.match([candidate], args, receiver, true);
+      if (held) viable.push(held);
+    }
+    const first = viable[0];
+    if (!first) return undefined;
+    const agree = viable.every((held) => typesEqual(held.returns, first.returns));
+    return agree ? first : { resolved: first.resolved, returns: DYN };
+  }
+
   private match(
     candidates: readonly RegisteredFunction[],
     args: readonly CelType[],
@@ -219,6 +304,33 @@ export function substitute(type: CelType, bindings: ReadonlyMap<string, CelType>
   }
 }
 
+/** Code-unit order, so a port orders two names without a locale. */
+function compareNames(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/**
+ * Levenshtein distance in UTF-16 code units — one insertion, deletion or substitution
+ * each costing one, which is the whole rule a port needs to reproduce.
+ *
+ * Code units rather than code points for the same reason every range in this package is
+ * in them: it is the one unit both ends of the engine already count in, and a name is
+ * compared against a name rather than cut.
+ */
+function editDistance(from: string, to: string): number {
+  let previous = Array.from({ length: to.length + 1 }, (ignored, at) => at);
+  for (let left = 1; left <= from.length; left += 1) {
+    const row = new Array<number>(to.length + 1);
+    row[0] = left;
+    for (let right = 1; right <= to.length; right += 1) {
+      const substitution = previous[right - 1]! + (from[left - 1] === to[right - 1] ? 0 : 1);
+      row[right] = Math.min(substitution, previous[right]! + 1, row[right - 1]! + 1);
+    }
+    previous = row;
+  }
+  return previous[to.length]!;
+}
+
 /** How a resolution failure names what it looked at, for a message a human reads. */
 export function describeCandidates(candidates: readonly RegisteredFunction[]): string {
   return candidates.map((candidate) => formatSignature(candidate.signature)).join(", ");