@telorun/cel 0.107.0 → 0.109.0

package/dist/runtime-library.js

@@ -24,7 +24,12 @@ import { googleTypeNames } from "./standard-library.js";
 import { celTimestamp, formatTimestamp, parseTimestamp, timestampField, timestampNanos, } from "./timestamp-value.js";
 import { celCompare, celEqual } from "./value-equality.js";
 import { bytesToText, doubleText, textToBytes } from "./value-text.js";
+/** The widest arity a registration declares, and so the number of direct parameters. */
+export const CALL_SITE_DIRECT_ARITY = 4;
 // --- reading arguments the dispatcher has already typed ---------------------
+// Each takes `CelValue | undefined` because a parameter list is as wide as the widest
+// overload; the dispatcher has already resolved on this argument's type, so the cast is
+// what reading it means.
 const text = (value) => value;
 const integer = (value) => value;
 const unsigned = (value) => value.value;
@@ -34,6 +39,8 @@ const list = (value) => value;
 const instant = (value) => value;
 const span = (value) => value;
 const optional = (value) => value;
+/** The argument itself, where what is read of it is that the dispatcher resolved on it. */
+const value = (held) => held;
 /** The code points of text — CEL counts and indexes a string by character. */
 const characters = (value) => [...value];
 // --- conversions -----------------------------------------------------------
@@ -185,119 +192,121 @@ function splitText(value, separator, limit) {
 }
 // --- the table -------------------------------------------------------------
 function timestampGetter(field) {
-    return (args, ctx) => timestampField(instant(args[0]), field, args.length > 1 ? text(args[1]) : undefined, ctx.range);
+    // One implementation under both arities: the zone is absent where the call omits it, and
+    // no CEL value is `undefined`, so the absence is the argument's own answer.
+    return (ctx, a, b) => timestampField(instant(a), field, b === undefined ? undefined : text(b), ctx.range);
 }
 function durationGetter(field) {
-    return (args) => durationField(span(args[0]), field);
+    return (ctx, a) => durationField(span(a), field);
 }
 const IMPLEMENTATIONS = new Map([
     // conversions
-    ["bool(bool)", (args) => args[0]],
+    ["bool(bool)", (ctx, a) => value(a)],
     [
         "bool(string)",
-        (args, ctx) => {
-            const held = BOOL_WORDS[text(args[0])];
-            return held === undefined ? conversionError("bool()", JSON.stringify(args[0]), ctx.range) : held;
+        (ctx, a) => {
+            const held = BOOL_WORDS[text(a)];
+            return held === undefined ? conversionError("bool()", JSON.stringify(a), ctx.range) : held;
         },
     ],
-    ["bytes(bytes)", (args) => args[0]],
-    ["bytes(string)", (args) => textToBytes(text(args[0]))],
-    ["double(double)", (args) => args[0]],
-    ["double(int)", (args) => Number(integer(args[0]))],
-    ["double(uint)", (args) => Number(unsigned(args[0]))],
-    ["double(string)", (args, ctx) => doubleFromText(text(args[0]), ctx.range)],
-    ["duration(string)", (args, ctx) => parseDuration(text(args[0]), ctx.range)],
-    ["duration(google.protobuf.Duration)", (args) => args[0]],
-    ["dyn(A)", (args) => args[0]],
-    ["int(int)", (args) => args[0]],
-    ["int(uint)", (args, ctx) => intResult(unsigned(args[0]), ctx.range)],
-    ["int(double)", (args, ctx) => intFromDouble(double(args[0]), ctx.range)],
+    ["bytes(bytes)", (ctx, a) => value(a)],
+    ["bytes(string)", (ctx, a) => textToBytes(text(a))],
+    ["double(double)", (ctx, a) => value(a)],
+    ["double(int)", (ctx, a) => Number(integer(a))],
+    ["double(uint)", (ctx, a) => Number(unsigned(a))],
+    ["double(string)", (ctx, a) => doubleFromText(text(a), ctx.range)],
+    ["duration(string)", (ctx, a) => parseDuration(text(a), ctx.range)],
+    ["duration(google.protobuf.Duration)", (ctx, a) => value(a)],
+    ["dyn(A)", (ctx, a) => value(a)],
+    ["int(int)", (ctx, a) => value(a)],
+    ["int(uint)", (ctx, a) => intResult(unsigned(a), ctx.range)],
+    ["int(double)", (ctx, a) => intFromDouble(double(a), ctx.range)],
     [
         "int(string)",
-        (args, ctx) => {
-            const written = text(args[0]);
+        (ctx, a) => {
+            const written = text(a);
             if (!DECIMAL_INT.test(written))
                 return conversionError("int()", JSON.stringify(written), ctx.range);
             return intResult(BigInt(written), ctx.range);
         },
     ],
-    ["int(google.protobuf.Timestamp)", (args) => instant(args[0]).seconds],
+    ["int(google.protobuf.Timestamp)", (ctx, a) => instant(a).seconds],
     // A duration's whole seconds, truncated toward zero — no row pins it, cel-spec does.
-    ["int(google.protobuf.Duration)", (args) => durationField(span(args[0]), "getSeconds")],
-    ["matches(string, string)", (args, ctx) => celMatches(text(args[0]), text(args[1]), ctx.range)],
-    ["size(string)", (args) => BigInt(characters(text(args[0])).length)],
-    ["size(bytes)", (args) => BigInt(bytes(args[0]).length)],
-    ["size(list<A>)", (args) => BigInt(list(args[0]).length)],
-    ["size(map<K, V>)", (args) => BigInt(sizeOfMap(args[0]))],
-    ["string(string)", (args) => args[0]],
-    ["string(bool)", (args) => String(args[0])],
-    ["string(int)", (args) => String(integer(args[0]))],
-    ["string(uint)", (args) => String(unsigned(args[0]))],
-    ["string(double)", (args) => doubleText(double(args[0]))],
-    ["string(bytes)", (args, ctx) => bytesToText(bytes(args[0]), ctx.range)],
-    ["string(google.protobuf.Timestamp)", (args) => formatTimestamp(instant(args[0]))],
-    ["string(google.protobuf.Duration)", (args) => formatDuration(span(args[0]))],
-    ["timestamp(string)", (args, ctx) => parseTimestamp(text(args[0]), ctx.range)],
-    ["timestamp(int)", (args, ctx) => celTimestamp(integer(args[0]), 0, ctx.range)],
-    ["timestamp(google.protobuf.Timestamp)", (args) => args[0]],
-    ["uint(uint)", (args) => args[0]],
-    ["uint(int)", (args, ctx) => uintResult(integer(args[0]), ctx.range)],
-    ["uint(double)", (args, ctx) => uintFromDouble(double(args[0]), ctx.range)],
+    ["int(google.protobuf.Duration)", (ctx, a) => durationField(span(a), "getSeconds")],
+    ["matches(string, string)", (ctx, a, b) => celMatches(text(a), text(b), ctx.range)],
+    ["size(string)", (ctx, a) => BigInt(characters(text(a)).length)],
+    ["size(bytes)", (ctx, a) => BigInt(bytes(a).length)],
+    ["size(list<A>)", (ctx, a) => BigInt(list(a).length)],
+    ["size(map<K, V>)", (ctx, a) => BigInt(sizeOfMap(a))],
+    ["string(string)", (ctx, a) => value(a)],
+    ["string(bool)", (ctx, a) => String(a)],
+    ["string(int)", (ctx, a) => String(integer(a))],
+    ["string(uint)", (ctx, a) => String(unsigned(a))],
+    ["string(double)", (ctx, a) => doubleText(double(a))],
+    ["string(bytes)", (ctx, a) => bytesToText(bytes(a), ctx.range)],
+    ["string(google.protobuf.Timestamp)", (ctx, a) => formatTimestamp(instant(a))],
+    ["string(google.protobuf.Duration)", (ctx, a) => formatDuration(span(a))],
+    ["timestamp(string)", (ctx, a) => parseTimestamp(text(a), ctx.range)],
+    ["timestamp(int)", (ctx, a) => celTimestamp(integer(a), 0, ctx.range)],
+    ["timestamp(google.protobuf.Timestamp)", (ctx, a) => value(a)],
+    ["uint(uint)", (ctx, a) => value(a)],
+    ["uint(int)", (ctx, a) => uintResult(integer(a), ctx.range)],
+    ["uint(double)", (ctx, a) => uintFromDouble(double(a), ctx.range)],
     [
         "uint(string)",
-        (args, ctx) => {
-            const written = text(args[0]);
+        (ctx, a) => {
+            const written = text(a);
             if (!DECIMAL_UINT.test(written))
                 return conversionError("uint()", JSON.stringify(written), ctx.range);
             return uintResult(BigInt(written), ctx.range);
         },
     ],
     // string members
-    ["string.size()", (args) => BigInt(characters(text(args[0])).length)],
-    ["bytes.size()", (args) => BigInt(bytes(args[0]).length)],
-    ["list<A>.size()", (args) => BigInt(list(args[0]).length)],
-    ["map<K, V>.size()", (args) => BigInt(sizeOfMap(args[0]))],
-    ["string.startsWith(string)", (args) => text(args[0]).startsWith(text(args[1]))],
-    ["string.endsWith(string)", (args) => text(args[0]).endsWith(text(args[1]))],
-    ["string.contains(string)", (args) => text(args[0]).includes(text(args[1]))],
-    ["string.matches(string)", (args, ctx) => celMatches(text(args[0]), text(args[1]), ctx.range)],
+    ["string.size()", (ctx, a) => BigInt(characters(text(a)).length)],
+    ["bytes.size()", (ctx, a) => BigInt(bytes(a).length)],
+    ["list<A>.size()", (ctx, a) => BigInt(list(a).length)],
+    ["map<K, V>.size()", (ctx, a) => BigInt(sizeOfMap(a))],
+    ["string.startsWith(string)", (ctx, a, b) => text(a).startsWith(text(b))],
+    ["string.endsWith(string)", (ctx, a, b) => text(a).endsWith(text(b))],
+    ["string.contains(string)", (ctx, a, b) => text(a).includes(text(b))],
+    ["string.matches(string)", (ctx, a, b) => celMatches(text(a), text(b), ctx.range)],
     // Named for ASCII and not limited to it — see the declaration's own `spec: false` reason.
-    ["string.lowerAscii()", (args) => text(args[0]).toLowerCase()],
-    ["string.upperAscii()", (args) => text(args[0]).toUpperCase()],
-    ["string.trim()", (args) => text(args[0]).trim()],
-    ["string.indexOf(string)", (args) => BigInt(text(args[0]).indexOf(text(args[1])))],
+    ["string.lowerAscii()", (ctx, a) => text(a).toLowerCase()],
+    ["string.upperAscii()", (ctx, a) => text(a).toUpperCase()],
+    ["string.trim()", (ctx, a) => text(a).trim()],
+    ["string.indexOf(string)", (ctx, a, b) => BigInt(text(a).indexOf(text(b)))],
     [
         "string.indexOf(string, int)",
-        (args, ctx) => {
-            const from = boundedIndex(integer(args[2]), text(args[0]).length, ctx.range);
-            return typeof from === "number" ? BigInt(text(args[0]).indexOf(text(args[1]), from)) : from;
+        (ctx, a, b, c) => {
+            const from = boundedIndex(integer(c), text(a).length, ctx.range);
+            return typeof from === "number" ? BigInt(text(a).indexOf(text(b), from)) : from;
         },
     ],
-    ["string.lastIndexOf(string)", (args) => BigInt(text(args[0]).lastIndexOf(text(args[1])))],
+    ["string.lastIndexOf(string)", (ctx, a, b) => BigInt(text(a).lastIndexOf(text(b)))],
     [
         "string.lastIndexOf(string, int)",
-        (args, ctx) => {
-            const from = boundedIndex(integer(args[2]), text(args[0]).length, ctx.range);
-            return typeof from === "number" ? BigInt(text(args[0]).lastIndexOf(text(args[1]), from)) : from;
+        (ctx, a, b, c) => {
+            const from = boundedIndex(integer(c), text(a).length, ctx.range);
+            return typeof from === "number" ? BigInt(text(a).lastIndexOf(text(b), from)) : from;
         },
     ],
-    ["string.substring(int)", (args, ctx) => substring(text(args[0]), integer(args[1]), undefined, ctx.range)],
+    ["string.substring(int)", (ctx, a, b) => substring(text(a), integer(b), undefined, ctx.range)],
     [
         "string.substring(int, int)",
-        (args, ctx) => substring(text(args[0]), integer(args[1]), integer(args[2]), ctx.range),
+        (ctx, a, b, c) => substring(text(a), integer(b), integer(c), ctx.range),
     ],
-    ["string.split(string)", (args) => splitText(text(args[0]), text(args[1]))],
-    ["string.split(string, int)", (args) => splitText(text(args[0]), text(args[1]), integer(args[2]))],
-    ["list<string>.join()", (args) => list(args[0]).join("")],
-    ["list<string>.join(string)", (args) => list(args[0]).join(text(args[1]))],
+    ["string.split(string)", (ctx, a, b) => splitText(text(a), text(b))],
+    ["string.split(string, int)", (ctx, a, b, c) => splitText(text(a), text(b), integer(c))],
+    ["list<string>.join()", (ctx, a) => list(a).join("")],
+    ["list<string>.join(string)", (ctx, a, b) => list(a).join(text(b))],
     // bytes members, each a compatibility member rather than CEL's
-    ["bytes.string()", (args, ctx) => bytesToText(bytes(args[0]), ctx.range)],
-    ["bytes.hex()", (args) => hexText(bytes(args[0]))],
-    ["bytes.base64()", (args) => base64Text(bytes(args[0]))],
+    ["bytes.string()", (ctx, a) => bytesToText(bytes(a), ctx.range)],
+    ["bytes.hex()", (ctx, a) => hexText(bytes(a))],
+    ["bytes.base64()", (ctx, a) => base64Text(bytes(a))],
     [
         "bytes.json()",
-        (args, ctx) => {
-            const decoded = bytesToText(bytes(args[0]), ctx.range);
+        (ctx, a) => {
+            const decoded = bytesToText(bytes(a), ctx.range);
             if (typeof decoded !== "string")
                 return decoded;
             try {
@@ -310,9 +319,9 @@ const IMPLEMENTATIONS = new Map([
     ],
     [
         "bytes.at(int)",
-        (args, ctx) => {
-            const held = bytes(args[0]);
-            const at = integer(args[1]);
+        (ctx, a, b) => {
+            const held = bytes(a);
+            const at = integer(b);
             if (at < 0n || at >= BigInt(held.length)) {
                 return celError("index_out_of_range", `index out of range: ${at}`, ctx.range);
             }
@@ -320,96 +329,96 @@ const IMPLEMENTATIONS = new Map([
         },
     ],
     // arithmetic
-    ["!(bool)", (args) => !args[0]],
-    ["-(int)", (args, ctx) => intResult(-integer(args[0]), ctx.range)],
-    ["-(double)", (args) => -double(args[0])],
-    ["+(int, int)", (args, ctx) => intResult(integer(args[0]) + integer(args[1]), ctx.range)],
-    ["+(uint, uint)", (args, ctx) => uintResult(unsigned(args[0]) + unsigned(args[1]), ctx.range)],
-    ["+(double, double)", (args) => double(args[0]) + double(args[1])],
-    ["+(string, string)", (args) => text(args[0]) + text(args[1])],
+    ["!(bool)", (ctx, a) => !a],
+    ["-(int)", (ctx, a) => intResult(-integer(a), ctx.range)],
+    ["-(double)", (ctx, a) => -double(a)],
+    ["+(int, int)", (ctx, a, b) => intResult(integer(a) + integer(b), ctx.range)],
+    ["+(uint, uint)", (ctx, a, b) => uintResult(unsigned(a) + unsigned(b), ctx.range)],
+    ["+(double, double)", (ctx, a, b) => double(a) + double(b)],
+    ["+(string, string)", (ctx, a, b) => text(a) + text(b)],
     [
         "+(bytes, bytes)",
-        (args) => {
-            const left = bytes(args[0]);
-            const right = bytes(args[1]);
+        (ctx, a, b) => {
+            const left = bytes(a);
+            const right = bytes(b);
             const out = new Uint8Array(left.length + right.length);
             out.set(left);
             out.set(right, left.length);
             return out;
         },
     ],
-    ["+(list<A>, list<A>)", (args) => [...list(args[0]), ...list(args[1])]],
+    ["+(list<A>, list<A>)", (ctx, a, b) => [...list(a), ...list(b)]],
     [
         "+(google.protobuf.Timestamp, google.protobuf.Duration)",
-        (args, ctx) => durationOutOfRange(span(args[1]), ctx.range) ??
-            celTimestamp(0n, timestampNanos(instant(args[0])) + durationNanos(span(args[1])), ctx.range),
+        (ctx, a, b) => durationOutOfRange(span(b), ctx.range) ??
+            celTimestamp(0n, timestampNanos(instant(a)) + durationNanos(span(b)), ctx.range),
     ],
     [
         "+(google.protobuf.Duration, google.protobuf.Timestamp)",
-        (args, ctx) => durationOutOfRange(span(args[0]), ctx.range) ??
-            celTimestamp(0n, durationNanos(span(args[0])) + timestampNanos(instant(args[1])), ctx.range),
+        (ctx, a, b) => durationOutOfRange(span(a), ctx.range) ??
+            celTimestamp(0n, durationNanos(span(a)) + timestampNanos(instant(b)), ctx.range),
     ],
     [
         "+(google.protobuf.Duration, google.protobuf.Duration)",
-        (args, ctx) => celDurationFromNanos(durationNanos(span(args[0])) + durationNanos(span(args[1])), ctx.range),
+        (ctx, a, b) => celDurationFromNanos(durationNanos(span(a)) + durationNanos(span(b)), ctx.range),
     ],
-    ["-(int, int)", (args, ctx) => intResult(integer(args[0]) - integer(args[1]), ctx.range)],
-    ["-(uint, uint)", (args, ctx) => uintResult(unsigned(args[0]) - unsigned(args[1]), ctx.range)],
-    ["-(double, double)", (args) => double(args[0]) - double(args[1])],
+    ["-(int, int)", (ctx, a, b) => intResult(integer(a) - integer(b), ctx.range)],
+    ["-(uint, uint)", (ctx, a, b) => uintResult(unsigned(a) - unsigned(b), ctx.range)],
+    ["-(double, double)", (ctx, a, b) => double(a) - double(b)],
     [
         "-(google.protobuf.Timestamp, google.protobuf.Timestamp)",
-        (args, ctx) => celDurationFromNanos(timestampNanos(instant(args[0])) - timestampNanos(instant(args[1])), ctx.range),
+        (ctx, a, b) => celDurationFromNanos(timestampNanos(instant(a)) - timestampNanos(instant(b)), ctx.range),
     ],
     [
         "-(google.protobuf.Timestamp, google.protobuf.Duration)",
-        (args, ctx) => durationOutOfRange(span(args[1]), ctx.range) ??
-            celTimestamp(0n, timestampNanos(instant(args[0])) - durationNanos(span(args[1])), ctx.range),
+        (ctx, a, b) => durationOutOfRange(span(b), ctx.range) ??
+            celTimestamp(0n, timestampNanos(instant(a)) - durationNanos(span(b)), ctx.range),
     ],
     [
         "-(google.protobuf.Duration, google.protobuf.Duration)",
-        (args, ctx) => celDurationFromNanos(durationNanos(span(args[0])) - durationNanos(span(args[1])), ctx.range),
+        (ctx, a, b) => celDurationFromNanos(durationNanos(span(a)) - durationNanos(span(b)), ctx.range),
     ],
-    ["*(int, int)", (args, ctx) => intResult(integer(args[0]) * integer(args[1]), ctx.range)],
-    ["*(uint, uint)", (args, ctx) => uintResult(unsigned(args[0]) * unsigned(args[1]), ctx.range)],
-    ["*(double, double)", (args) => double(args[0]) * double(args[1])],
-    ["/(int, int)", (args, ctx) => intDivide(integer(args[0]), integer(args[1]), ctx.range)],
-    ["/(uint, uint)", (args, ctx) => uintDivide(unsigned(args[0]), unsigned(args[1]), ctx.range)],
+    ["*(int, int)", (ctx, a, b) => intResult(integer(a) * integer(b), ctx.range)],
+    ["*(uint, uint)", (ctx, a, b) => uintResult(unsigned(a) * unsigned(b), ctx.range)],
+    ["*(double, double)", (ctx, a, b) => double(a) * double(b)],
+    ["/(int, int)", (ctx, a, b) => intDivide(integer(a), integer(b), ctx.range)],
+    ["/(uint, uint)", (ctx, a, b) => uintDivide(unsigned(a), unsigned(b), ctx.range)],
     // A double divided by zero is an infinity, as IEEE 754 says; only the integers refuse.
-    ["/(double, double)", (args) => double(args[0]) / double(args[1])],
-    ["%(int, int)", (args, ctx) => intModulo(integer(args[0]), integer(args[1]), ctx.range)],
-    ["%(uint, uint)", (args, ctx) => uintModulo(unsigned(args[0]), unsigned(args[1]), ctx.range)],
+    ["/(double, double)", (ctx, a, b) => double(a) / double(b)],
+    ["%(int, int)", (ctx, a, b) => intModulo(integer(a), integer(b), ctx.range)],
+    ["%(uint, uint)", (ctx, a, b) => uintModulo(unsigned(a), unsigned(b), ctx.range)],
     [
         "in(A, list<A>)",
-        (args) => {
+        (ctx, a, b) => {
             // Membership reads every element, so an element that must be awaited is a door too, and
             // the refusal is TERMINAL as it is in a comprehension: answering `true` off the one
             // element that is readable decides the question against a list this engine cannot read.
-            for (const held of list(args[1])) {
+            for (const held of list(b)) {
                 const refused = asyncValueRefused(held);
                 if (refused)
                     return refused;
-                if (celEqual(held, args[0]))
+                if (celEqual(held, value(a)))
                     return true;
             }
             return false;
         },
     ],
-    ["in(K, map<K, V>)", (args) => typeof celLookup(args[1], args[0]) !== "symbol"],
+    ["in(K, map<K, V>)", (ctx, a, b) => typeof celLookup(value(b), value(a)) !== "symbol"],
     // the optional library
-    ["optional<A>.hasValue()", (args) => optional(args[0]).present],
+    ["optional<A>.hasValue()", (ctx, a) => optional(a).present],
     [
         "optional<A>.value()",
-        (args, ctx) => {
-            const held = optional(args[0]);
+        (ctx, a) => {
+            const held = optional(a);
             return held.present
                 ? held.held
                 : celError("optional_value_missing", "the optional holds no value", ctx.range);
         },
     ],
-    ["optional<A>.or(optional<A>)", (args) => (optional(args[0]).present ? args[0] : args[1])],
+    ["optional<A>.or(optional<A>)", (ctx, a, b) => (optional(a).present ? value(a) : value(b))],
     [
         "optional<A>.orValue(A)",
-        (args) => (optional(args[0]).present ? optional(args[0]).held : args[1]),
+        (ctx, a, b) => (optional(a).present ? optional(a).held : value(b)),
     ],
     // timestamp and duration fields
     ["google.protobuf.Timestamp.getDate()", timestampGetter("getDate")],
@@ -451,23 +460,23 @@ function sizeOfMap(value) {
  * would then have no implementation.
  */
 const BY_NAME = new Map([
-    ["==", (args) => celEqual(args[0], args[1])],
-    ["!=", (args) => !celEqual(args[0], args[1])],
+    ["==", (ctx, a, b) => celEqual(value(a), value(b))],
+    ["!=", (ctx, a, b) => !celEqual(value(a), value(b))],
     ["<", ordering((compared) => compared < 0)],
     ["<=", ordering((compared) => compared <= 0)],
     [">", ordering((compared) => compared > 0)],
     [">=", ordering((compared) => compared >= 0)],
-    ["type", (args, ctx) => celTypeValueOf(args[0], ctx.range)],
+    ["type", (ctx, a) => celTypeValueOf(value(a), ctx.range)],
 ]);
 function ordering(holds) {
-    return (args, ctx) => {
-        const compared = celCompare(args[0], args[1]);
+    return (ctx, a, b) => {
+        const compared = celCompare(value(a), value(b));
         // Values that do not order at all — unrelated types, or a NaN. NaN orders with
         // nothing, including itself, so every comparison against it is false.
         if (compared === undefined) {
-            if (isNotANumber(args[0]) || isNotANumber(args[1]))
+            if (isNotANumber(a) || isNotANumber(b))
                 return false;
-            return celError("no_matching_overload", `${celTypeNameOf(args[0]) ?? "this value"} and ${celTypeNameOf(args[1]) ?? "this value"} do not order`, ctx.range);
+            return celError("no_matching_overload", `${celTypeNameOf(a) ?? "this value"} and ${celTypeNameOf(b) ?? "this value"} do not order`, ctx.range);
         }
         return holds(compared);
     };
@@ -512,8 +521,8 @@ export function standardConstantValues(optionalTypes) {
  * `optional.ofNonZeroValue(v)`: present unless the value is its type's zero — which is
  * what makes it different from `optional.of`, and what three of the vectors' rows read.
  */
-export function optionalOfNonZero(value) {
-    return isZeroValue(value) ? celNone() : celSome(value);
+export function optionalOfNonZero(held) {
+    return isZeroValue(held) ? celNone() : celSome(held);
 }
 /**
  * Whether a value is its type's zero. Every type that HAS one is listed; the types left out

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAc,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE5D,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAuND,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAc,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE5D,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAuOD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/serializer.js

@@ -121,14 +121,30 @@ function writeDouble(value) {
     const text = String(Math.abs(value));
     return `${sign}${/[.e]/.test(text) ? text : `${text}.0`}`;
 }
+/**
+ * A string literal, always in double quotes.
+ *
+ * **One spelling, chosen rather than remembered.** The tree records a string's VALUE and not
+ * the quote the author typed — the source's own formatting is not structure, which is the
+ * same rule that makes the serializer drop redundant parentheses — so a round trip
+ * normalizes `'x'` to `"x"`. Both are CEL and the parser reads either.
+ *
+ * The cost lands on a quick fix, which is written by rewriting the tree and serializing it
+ * back **into a YAML scalar**: a double-quoted CEL literal inside a double-quoted scalar has
+ * to be escaped, so a repair reads `!cel "a.startsWith(\"x\")"` where the author wrote
+ * `'x'`. Choosing the quote here cannot fix that — a single-quoted YAML scalar wants the
+ * opposite choice, and this engine does not know which scalar the text will land in. Picking
+ * the YAML quoting that needs no escaping is the EDITOR's, which has both halves in hand.
+ */
 function writeString(value) {
-    let text = '"';
+    const quote = '"';
+    let text = quote;
     for (const unit of value) {
         const code = unit.codePointAt(0);
         if (unit === "\\")
             text += "\\\\";
-        else if (unit === '"')
-            text += '\\"';
+        else if (unit === quote)
+            text += `\\${quote}`;
         else if (unit === "\n")
             text += "\\n";
         else if (unit === "\r")
@@ -140,7 +156,7 @@ function writeString(value) {
         else
             text += unit;
     }
-    return `${text}"`;
+    return `${text}${quote}`;
 }
 function writeBytes(value) {
     let text = 'b"';

package/dist/timestamp-value.d.ts

@@ -19,6 +19,15 @@ export declare const MIN_TIMESTAMP_SECONDS = -62135596800n;
 export declare const MAX_TIMESTAMP_SECONDS = 253402300799n;
 /** An instant from seconds and nanoseconds of any sign, normalized, or the range error. */
 export declare function celTimestamp(seconds: bigint, nanos?: bigint | number, range?: SourceRange): CelTimestamp | CelError;
+/**
+ * An instant from epoch MILLISECONDS — the mirror of `celDurationFromNanos` for a host
+ * clock reading (`Date.now()`, a driver's epoch-millis column), or the range error.
+ *
+ * It exists so that a host never has to reach for its own date type to say "now": the
+ * instance type is seconds plus nanos, and a millisecond reading is the one other shape
+ * a host actually holds. A fractional reading keeps its sub-millisecond part.
+ */
+export declare function celTimestampFromMillis(millis: number, range?: SourceRange): CelTimestamp | CelError;
 /** The instant's nanoseconds since the epoch — what arithmetic and ordering compare. */
 export declare function timestampNanos(value: CelTimestamp): bigint;
 /** An instant from RFC 3339 text, with any offset and any fractional precision. */

package/dist/timestamp-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timestamp-value.d.ts","sourceRoot":"","sources":["../src/timestamp-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAInD,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAM,GAAG,MAAU,EAC1B,KAAK,CAAC,EAAE,WAAW,GAClB,YAAY,GAAG,QAAQ,CAYzB;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE1D;AAKD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAgCzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAK3D;AAaD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAgED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,CAAC,EAAE,WAAW,GAClB,WAAW,GAAG,QAAQ,CAYxB;AAsCD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,cAAc,GACd,eAAe,GACf,SAAS,GACT,cAAc,GACd,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,WAAW,GAClB,MAAM,GAAG,QAAQ,CA0BnB"}
+{"version":3,"file":"timestamp-value.d.ts","sourceRoot":"","sources":["../src/timestamp-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAInD,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAM,GAAG,MAAU,EAC1B,KAAK,CAAC,EAAE,WAAW,GAClB,YAAY,GAAG,QAAQ,CAYzB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAMnG;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAE1D;AAKD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAgCzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAK3D;AAaD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAgED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,CAAC,EAAE,WAAW,GAClB,WAAW,GAAG,QAAQ,CAYxB;AAsCD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,cAAc,GACd,eAAe,GACf,SAAS,GACT,cAAc,GACd,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,WAAW,GAClB,MAAM,GAAG,QAAQ,CA0BnB"}

package/dist/timestamp-value.js

@@ -31,6 +31,21 @@ export function celTimestamp(seconds, nanos = 0, range) {
     }
     return { [CEL_VALUE_TYPE]: "google.protobuf.Timestamp", seconds: whole, nanos: Number(rest) };
 }
+/**
+ * An instant from epoch MILLISECONDS — the mirror of `celDurationFromNanos` for a host
+ * clock reading (`Date.now()`, a driver's epoch-millis column), or the range error.
+ *
+ * It exists so that a host never has to reach for its own date type to say "now": the
+ * instance type is seconds plus nanos, and a millisecond reading is the one other shape
+ * a host actually holds. A fractional reading keeps its sub-millisecond part.
+ */
+export function celTimestampFromMillis(millis, range) {
+    if (!Number.isFinite(millis)) {
+        return celError("invalid_conversion", "timestamp out of range", range);
+    }
+    const whole = Math.floor(millis / 1000);
+    return celTimestamp(BigInt(whole), Math.round((millis - whole * 1000) * 1_000_000), range);
+}
 /** The instant's nanoseconds since the epoch — what arithmetic and ordering compare. */
 export function timestampNanos(value) {
     return value.seconds * NANOS_PER_SECOND + BigInt(value.nanos);

package/dist/type-expression.d.ts

@@ -9,13 +9,29 @@
  *
  * A bare capital letter is a type **parameter**, which is how a signature says "the
  * same type here and there". A name the host registered as a nominal type resolves
- * to it; any other name is refused rather than guessed, because a misspelled type in
- * a signature would otherwise register a function nothing can call.
+ * to it; any other name is refused rather than guessed — as a
+ * {@link CelUnknownTypeNameError}, which a caller holding the name's source may turn
+ * into a verdict — because a misspelled type in a signature would otherwise register a
+ * function nothing can call.
  */
 import type { CelType } from "./cel-type.js";
 export declare class CelTypeExpressionError extends Error {
     constructor(message: string);
 }
+/**
+ * A well-formed type expression naming a type nothing is registered under.
+ *
+ * It is **not** a `CelTypeExpressionError`, and the split is the whole point: that error
+ * is about text this grammar cannot read, while this one is about a name the HOST and its
+ * own registry disagree about. A caller that holds where the name was written can turn it
+ * into a ranged verdict instead of a crash — which is what a namespace declaration built
+ * out of a host's data does — and a caller that cannot still lets it fly.
+ */
+export declare class CelUnknownTypeNameError extends Error {
+    /** The name nothing is registered under. */
+    readonly typeName: string;
+    constructor(typeName: string);
+}
 /** What a name that is neither a primitive nor a parameter resolves to. */
 export type NominalResolver = (name: string, args: readonly CelType[]) => CelType | undefined;
 /**

package/dist/type-expression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-expression.d.ts","sourceRoot":"","sources":["../src/type-expression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AAoB5D,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAmBD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,SAAS,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,eAAe,GAAG,OAAO,CAK3F"}
+{"version":3,"file":"type-expression.d.ts","sourceRoot":"","sources":["../src/type-expression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AAoB5D,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAmBD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,SAAS,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,eAAe,GAAG,OAAO,CAK3F"}

package/dist/type-expression.js

@@ -9,8 +9,10 @@
  *
  * A bare capital letter is a type **parameter**, which is how a signature says "the
  * same type here and there". A name the host registered as a nominal type resolves
- * to it; any other name is refused rather than guessed, because a misspelled type in
- * a signature would otherwise register a function nothing can call.
+ * to it; any other name is refused rather than guessed — as a
+ * {@link CelUnknownTypeNameError}, which a caller holding the name's source may turn
+ * into a verdict — because a misspelled type in a signature would otherwise register a
+ * function nothing can call.
  */
 import { BOOL, BYTES, DOUBLE, DYN, DURATION, INT, listOf, mapOf, NULL, optionalOf, parameterOf, STRING, TIMESTAMP, TYPE, UINT, WELL_KNOWN_TYPE_NAMES, } from "./cel-type.js";
 export class CelTypeExpressionError extends Error {
@@ -19,6 +21,24 @@ export class CelTypeExpressionError extends Error {
         this.name = "CelTypeExpressionError";
     }
 }
+/**
+ * A well-formed type expression naming a type nothing is registered under.
+ *
+ * It is **not** a `CelTypeExpressionError`, and the split is the whole point: that error
+ * is about text this grammar cannot read, while this one is about a name the HOST and its
+ * own registry disagree about. A caller that holds where the name was written can turn it
+ * into a ranged verdict instead of a crash — which is what a namespace declaration built
+ * out of a host's data does — and a caller that cannot still lets it fly.
+ */
+export class CelUnknownTypeNameError extends Error {
+    /** The name nothing is registered under. */
+    typeName;
+    constructor(typeName) {
+        super(`no type is registered under the name ${JSON.stringify(typeName)}`);
+        this.name = "CelUnknownTypeNameError";
+        this.typeName = typeName;
+    }
+}
 const PRIMITIVES = {
     dyn: DYN,
     int: INT,
@@ -124,7 +144,7 @@ class TypeReader {
         const nominal = this.resolveNominal?.(name, args);
         if (nominal)
             return nominal;
-        throw new CelTypeExpressionError(`no type is registered under the name ${JSON.stringify(name)}`);
+        throw new CelUnknownTypeNameError(name);
     }
     noArguments(name, args, type) {
         if (args.length > 0)

package/dist/value-equality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-equality.d.ts","sourceRoot":"","sources":["../src/value-equality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA8E/C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAgB9E;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAgCjE"}
+{"version":3,"file":"value-equality.d.ts","sourceRoot":"","sources":["../src/value-equality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA8E1D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAgB9E;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAgCjE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/cel",
-  "version": "0.107.0",
+  "version": "0.109.0",
   "description": "The Common Expression Language for Telo: read, type-check and evaluate an expression, hold it as a tree, write it back.",
   "keywords": [
     "telo",