@telorun/cel 0.107.0 → 0.109.0

package/src/index.ts

@@ -143,7 +143,7 @@ export type {
   VariableDefinition,
 } from "./environment.js";
 
-export { FunctionRegistry } from "./function-registry.js";
+export { FunctionRegistry, UNKNOWN_FUNCTION_CANDIDATES } from "./function-registry.js";
 export type { RegisteredFunction, Resolution, ResolutionFailure } from "./function-registry.js";
 
 export {
@@ -225,7 +225,11 @@ export {
 } from "./zoned-calendar.js";
 export type { CivilTime } from "./zoned-calendar.js";
 
-export { CelTypeExpressionError, parseTypeExpression } from "./type-expression.js";
+export {
+  CelTypeExpressionError,
+  CelUnknownTypeNameError,
+  parseTypeExpression,
+} from "./type-expression.js";
 export type { NominalResolver } from "./type-expression.js";
 
 // --- the value domain, the semantics and the closure backend ----------------
@@ -234,7 +238,10 @@ export type { CelActivation } from "./activation.js";
 
 export { BoundedCache } from "./bounded-cache.js";
 
-export { celMapFromEntries, celMapKeys, mapKeyIdentity } from "./cel-map-value.js";
+// `mapKeyIdentity` is deliberately NOT exported: what identifies an entry is the entries
+// map's own business, and publishing the rule is what let a consumer grow a second copy of
+// it. A host reads a map through the member-read seam and walks `entries` for the pairs.
+export { celMapFromEntries, celMapKeys } from "./cel-map-value.js";
 
 export { CelEvaluationError, programOfStep } from "./cel-program.js";
 export type { CelProgram, EvaluateOptions } from "./cel-program.js";
@@ -295,6 +302,7 @@ export type {
   CelEvaluationCode,
   CelHostValue,
   CelMap,
+  CelMapKey,
   CelMapValueEntry,
   CelOptional,
   CelRecord,
@@ -314,6 +322,7 @@ export type {
   CompileTarget,
   EvaluationFrame,
   NamespaceDispatch,
+  NamespaceImplementation,
 } from "./backend-runtime.js";
 
 export {
@@ -329,6 +338,7 @@ export {
   celDurationFromNanos,
   durationField,
   durationNanos,
+  durationNanosFromText,
   durationOutOfRange,
   formatDuration,
   MAX_DURATION_NANOS,
@@ -341,6 +351,7 @@ export {
   celIterable,
   celLookup,
   celRead,
+  lookupAbsence,
   lookupError,
   MISSING,
   OUT_OF_RANGE,
@@ -369,9 +380,12 @@ export {
   typeValueName,
 } from "./runtime-library.js";
 export type { CelCallContext, CelImplementation } from "./runtime-library.js";
+// The bound a host writing an implementation is held to, and what the refusal names.
+export { CALL_SITE_DIRECT_ARITY } from "./runtime-library.js";
 
 export {
   celTimestamp,
+  celTimestampFromMillis,
   formatTimestamp,
   MAX_TIMESTAMP_SECONDS,
   MIN_TIMESTAMP_SECONDS,
@@ -384,3 +398,10 @@ export {
 export { celCompare, celEqual } from "./value-equality.js";
 
 export { bytesToText, doubleText, textToBytes } from "./value-text.js";
+
+export {
+  BINDING_FORMS,
+  namespaceMacroBinding,
+  receiverMacroBinding,
+  type ComprehensionBinding,
+} from "./comprehension-bindings.js";

package/src/js-emitter.ts

@@ -36,6 +36,7 @@ import {
 import { namespaceMacroBinding, receiverMacroBinding } from "./comprehension-bindings.js";
 import { splitDeclaredChain } from "./declared-chain.js";
 import { isMacroCall } from "./macro-check.js";
+import { CALL_SITE_DIRECT_ARITY } from "./runtime-library.js";
 import type { CelLiteral, CelNode, CelSelectNode, SourceRange } from "./syntax-tree.js";
 
 /**
@@ -347,8 +348,8 @@ export class ModuleEmitter {
       const kept = entry.optional ? fn.next() : undefined;
       const written = kept
         ? `(${kept} = optionalEntry(${value}, ${at}), isCelError(${kept}) ? ${kept} : ` +
-          `(${kept}.present && ${out}.push([${key}, ${kept}.held]), ${body}))`
-        : `(${out}.push([${key}, ${value}]), ${body})`;
+          `(${kept}.present && ${out}.push(${key}, ${kept}.held), ${body}))`
+        : `(${out}.push(${key}, ${value}), ${body})`;
       body =
         `(${key} = ${entry.key}, isCelError(${key}) ? ${key} : ` +
         `(${value} = ${entry.value}, isCelError(${value}) ? ${value} : ${written}))`;
@@ -427,8 +428,9 @@ export class ModuleEmitter {
 
   /**
    * One dispatch: evaluate the arguments, carry the first error out, then hand the values to
-   * the site. The site is hoisted, so it is built once per loaded module and holds the
-   * overloads it resolved — exactly as a compiled closure's does.
+   * the site **positionally**. The site is hoisted, so it is built once per loaded module and
+   * holds the overloads it resolved — exactly as a compiled closure's does. The arity is the
+   * dispatch key's, so the entry point is chosen here and no argument array is built.
    */
   private call(
     name: string,
@@ -440,7 +442,13 @@ export class ModuleEmitter {
     const site = this.hoist(
       `callSite(${textSource(name)}, ${textSource(form)}, ${this.range(range)})`,
     );
-    return this.carrying(args, fn, (values) => `${site}.call([${values.join(", ")}])`);
+    // A call written wider than the bound takes the array form — the arity is the SOURCE's,
+    // so a width no signature can declare is still something an author may write.
+    return this.carrying(args, fn, (values) =>
+      values.length <= CALL_SITE_DIRECT_ARITY
+        ? `${site}.call${values.length}(${values.join(", ")})`
+        : `${site}.call([${values.join(", ")}])`,
+    );
   }
 
   private qualifiedCall(

package/src/macro-check.ts

@@ -25,6 +25,12 @@ export interface MacroHost {
   typeOf(node: CelNode): CelType;
   /** The type of a subexpression with extra names in scope. */
   typeOfBinding(node: CelNode, bindings: ReadonlyMap<string, CelType>): CelType;
+  /**
+   * The type of a select read as a question about PRESENCE — `has()`'s argument. It is
+   * the same reading `.?b` gets, which is what keeps the two forms of one question from
+   * answering differently about a union whose branches do not all hold the member.
+   */
+  typeOfPresence(node: Extract<CelNode, { kind: "select" }>): CelType;
   report(code: CelCheckCode, message: string, range: SourceRange): void;
 }
 
@@ -99,7 +105,7 @@ function checkOptionalBinding(node: Extract<CelNode, { kind: "receiverCall" }>,
 /** `has(a.b)` — a question about presence. Its shape is already validated. */
 function checkHas(node: Extract<CelNode, { kind: "call" }>, host: MacroHost): CelType {
   const argument = node.args[0]!;
-  if (argument.kind === "select") host.typeOf(argument);
+  if (argument.kind === "select") host.typeOfPresence(argument);
   return BOOL;
 }
 

package/src/member-read.ts

@@ -16,6 +16,10 @@
  *
  * A key the value does not hold is the `no_such_key` **error value**, which
  * participates in short-circuit. Never `undefined` passed along.
+ *
+ * **What each of the four verdicts answers is written once here**, in `lookupAbsence`,
+ * and read by both presence callers — so the closure backend, the emitter and the
+ * `has()` macro cannot differ by construction.
  */
 
 import { celMapKeys, mapKeyIdentity } from "./cel-map-value.js";
@@ -86,6 +90,38 @@ export function celRead(container: CelValue, key: CelValue, range?: SourceRange)
   return lookupError(found, key, range);
 }
 
+/**
+ * Whether a lookup that found nothing answers **absence** rather than an error. This is
+ * the seam's contract, in the one place both backends and the emitter read it: they all
+ * reach a member read through `backend-runtime.ts`, which reaches the four verdicts
+ * through here.
+ *
+ * - A **presence-shaped** read — `a.?b`, `a[?k]` and `has(a.b)` — answers absence for
+ *   *missing*, *out of range* and *holds no members* alike, and the error only for an
+ *   **unusable key**. It asks whether a member is THERE, and a value that cannot hold one
+ *   has none to find. The authority is the optional library's own: it enters this engine
+ *   from cel-go whole, and cel-go's attribute qualification answers "not found" for a
+ *   receiver that is neither a mapper, a lister nor an indexer **whenever the read is a
+ *   presence test**, erroring only otherwise — the error reading being an explicitly named
+ *   opt-in (`EnableErrorOnBadPresenceTest`), which Telo does not carry, because a
+ *   per-environment switch over what an expression MEANS would let the analyzer and a
+ *   kernel disagree about one manifest.
+ * - A read **through a present optional, written in the ordinary form** — the `.c` of
+ *   `a.?b.c` — is not a presence question about `c`. It answers absence for a key the held
+ *   value does not hold (`optional.of({'c': {}}).c.missing` is absent, cel-spec's
+ *   `optional_chaining_5`) and the error for a held value that holds no members at all
+ *   (`{true: dyn(0)}[?true].absent` is cel-spec's error).
+ * - A **plain** read never asks: each of the four is the error `lookupError` words.
+ *
+ * An unusable key is the one refusal no form forgives: `[?3.1]` names an entry no
+ * container of that shape could hold, so it is a mistake in the READ rather than a member
+ * that happens to be absent.
+ */
+export function lookupAbsence(found: symbol, presence: boolean): boolean {
+  if (found === MISSING || found === OUT_OF_RANGE) return true;
+  return presence && found === UNSUPPORTED_CONTAINER;
+}
+
 /** The error a refused lookup is. */
 export function lookupError(found: symbol, key: CelValue, range?: SourceRange): CelError {
   if (found === MISSING) return celError("no_such_key", `no such key: ${describe(key)}`, range);
@@ -99,20 +135,25 @@ export function lookupError(found: symbol, key: CelValue, range?: SourceRange):
 }
 
 /**
- * Whether a key is there — `has(a.b)`. It asks about presence, so a missing key is
- * `false` rather than the error a read would be; a container that holds no members at
- * all is still a mistake in the question.
+ * Whether a key is there — `has(a.b)`. The question is presence-shaped, so a value that
+ * holds no members answers `false` exactly as a missing key does: it has no member to
+ * find. Only an unusable key is a mistake in the question itself.
  */
 export function celHas(container: CelValue, key: CelValue, range?: SourceRange): boolean | CelError {
   const found = celLookup(container, key);
   if (typeof found !== "symbol") return true;
-  if (found === MISSING || found === OUT_OF_RANGE) return false;
+  if (lookupAbsence(found, true)) return false;
   return lookupError(found, key, range);
 }
 
-/** The elements a comprehension ranges over: a list's items, a map's keys. */
-export function celIterable(container: CelValue, range?: SourceRange): CelValue[] | CelError {
-  if (Array.isArray(container)) return [...container];
+/**
+ * The elements a comprehension ranges over: a list's items, a map's keys. A list is handed
+ * over as it is — nothing in CEL mutates a value, and every comprehension reads its range —
+ * so copying it would cost the length of the list per comprehension to defend against a
+ * write no expression can perform.
+ */
+export function celIterable(container: CelValue, range?: SourceRange): readonly CelValue[] | CelError {
+  if (Array.isArray(container)) return container as readonly CelValue[];
   if (isCelMap(container)) return celMapKeys(container);
   if (isCelRecord(container)) return Object.keys(container);
   return celError("unsupported_container", "a comprehension reads a list or a map", range);

package/src/resolved-call.ts

@@ -31,4 +31,17 @@ export interface ResolvedCall {
   readonly deterministic?: boolean;
   readonly hostBacked?: boolean;
   readonly throws?: readonly string[];
+  /**
+   * Each argument's own type, for a NAMESPACED call only.
+   *
+   * The host judges such a call against its own, richer signature grammar — a JSON Schema
+   * per parameter, an optional trailing parameter — so it needs what was actually passed.
+   * It cannot re-derive it: checking an argument's subtree on its own loses whatever the
+   * expression bound around it, so an argument inside a comprehension (`xs.map(i,
+   * Billing.total(i))`) would type as `dyn` and the host's argument check would silently
+   * stop asking. Here the types come from the same pass that typed the call.
+   *
+   * Absent for a call the registry resolved: its parameter types are the signature's.
+   */
+  readonly argumentTypes?: readonly string[];
 }