@telorun/templating 0.18.0 → 0.20.0

package/dist/cel/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/cel/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AA0DD;;+DAE+D;AAC/D,eAAO,MAAM,aAAa,QAAQ,CAAC;AAqBnC,UAAU,aAAa;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAoFD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,aAAa,EAAE,CAIjB;AA2FD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CAsBf"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/cel/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AAsFD;;+DAE+D;AAC/D,eAAO,MAAM,aAAa,QAAQ,CAAC;AAqBnC,UAAU,aAAa;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAoFD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,aAAa,EAAE,CAIjB;AAoGD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CAsBf"}

package/dist/cel/analyze.js

@@ -11,12 +11,44 @@ export function extractAccessChains(node) {
     return chains;
 }
 const COMPREHENSION_METHODS = new Set(["filter", "map", "exists", "all", "exists_one"]);
+/** `cel.bind(name, init, body)` — CEL's only binding form, and the one the
+ *  parser expands rather than dispatching, so it appears as a receiver call on a
+ *  bare `cel` identifier that is in no scope and never will be. Both walks below
+ *  need the same three facts out of it, so the shape is read once here.
+ *
+ *  The receiver is deliberately not returned: it contributes no chain, and
+ *  descending into it is what produced a `CEL_UNKNOWN_FIELD` for `cel` itself. */
+function bindCall(node) {
+    if (node.op !== "rcall" || !Array.isArray(node.args))
+        return null;
+    const [method, receiver, callArgs] = node.args;
+    if (method !== "bind")
+        return null;
+    if (!isASTNode(receiver) || receiver.op !== "id" || receiver.args !== "cel")
+        return null;
+    if (!Array.isArray(callArgs) || callArgs.length !== 3)
+        return null;
+    const [nameNode, init, body] = callArgs;
+    if (!isASTNode(nameNode) || nameNode.op !== "id")
+        return null;
+    if (!isASTNode(init) || !isASTNode(body))
+        return null;
+    return { name: nameNode.args, init, body };
+}
 function visitNode(node, chains, boundVars) {
     const chain = extractChain(node, boundVars);
     if (chain !== null) {
         chains.push(chain);
         return;
     }
+    // The bound name is in scope for the body ONLY; `init` is evaluated in the
+    // enclosing scope, so a name used there still has to resolve there.
+    const bind = bindCall(node);
+    if (bind) {
+        visitNode(bind.init, chains, boundVars);
+        visitNode(bind.body, chains, new Set(boundVars).add(bind.name));
+        return;
+    }
     if (node.op === "rcall" &&
         Array.isArray(node.args) &&
         typeof node.args[0] === "string" &&
@@ -210,6 +242,14 @@ function walkNullable(node, nonNull, boundVars, issues, schema) {
         walkNullable(b, union(nonNull, carried), boundVars, issues, schema);
         return;
     }
+    // `cel.bind` binds a name for its body; mirror extractAccessChains so a bound
+    // name is never read as a nullable context field.
+    const bind = bindCall(node);
+    if (bind) {
+        walkNullable(bind.init, nonNull, boundVars, issues, schema);
+        walkNullable(bind.body, nonNull, new Set(boundVars).add(bind.name), issues, schema);
+        return;
+    }
     // Comprehension macros bind a loop variable; mirror extractAccessChains so a
     // bound var is never mistaken for a nullable context field.
     if (node.op === "rcall" &&

package/dist/cel/catalog.d.ts

@@ -12,7 +12,7 @@ export interface CelHandlers {
     base64Decode: (s: string) => string;
     json: (value: unknown) => string;
 }
-export type CelFunctionCategory = "conversion" | "time" | "uuid" | "string" | "math" | "collection" | "json" | "encoding" | "hashing" | "null";
+export type CelFunctionCategory = "conversion" | "time" | "uuid" | "string" | "math" | "collection" | "json" | "encoding" | "hashing" | "formatting" | "null";
 /** One entry in the CEL standard library — the single source of truth that both
  *  registers the function (`build`) and documents it (everything else). `telo
  *  cel functions` and `celFunctionCatalog()` read the metadata; `buildCelEnvironment`
@@ -38,6 +38,24 @@ export interface CelFunctionDoc {
      *  analyzer's stub throws if such a function is actually evaluated. */
     readonly hostBacked: boolean;
     readonly build: (h: CelHandlers) => (...args: any[]) => unknown;
+    /**
+     * Check the arguments that were written as LITERALS, at analysis time.
+     *
+     * A type is all a signature can constrain, so a guard over a value —
+     * an unparseable format specifier, a decimal count out of range, a day length
+     * of zero, an unknown IANA zone — fires only when the expression is evaluated.
+     * That puts a defect the manifest states in plain sight behind a run, which is
+     * the opposite of what static analysis is for.
+     *
+     * `literals[i]` is the value of argument `i` when it was written as a literal,
+     * and `undefined` when it is an expression whose value is not statically
+     * known — so a checker MUST skip an `undefined` rather than judge it.
+     * Returns a message, or `undefined` when there is nothing to report.
+     *
+     * Implementations call the SAME guard the runtime calls, so the static and
+     * dynamic answers cannot drift into disagreement.
+     */
+    readonly checkArgs?: (literals: readonly unknown[]) => string | undefined;
 }
 /** Public, build-free view of a catalog entry (for `--json` / docs). */
 export type CelFunctionInfo = Omit<CelFunctionDoc, "build">;

package/dist/cel/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/cel/catalog.ts"],"names":[],"mappings":"AAGA;;;0DAG0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AA2CD,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX;;;qBAGqB;AACrB,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;yDAIqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;wBACoB;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACjE;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAwH5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EA8lBlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/cel/catalog.ts"],"names":[],"mappings":"AAIA;;;0DAG0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AA2CD,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,SAAS,GACT,YAAY,GACZ,MAAM,CAAC;AAEX;;;qBAGqB;AACrB,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;yDAIqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;wBACoB;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;IAChE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3E;AAYD,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AA8Z5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAyxBlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}

package/dist/cel/catalog.js

@@ -1,3 +1,4 @@
+import { formatLocale } from "d3-format";
 import { RE2JS } from "re2js";
 import { v1, v3, v4, v5, v6, v7, validate as uuidValidate, version as uuidVersion } from "uuid";
 /** RE2 regex engine for the CEL `regex*` functions — `re2js`, a pure-JS port of
@@ -40,6 +41,16 @@ const compileRe2 = (fn, pattern, flags) => {
         throw new Error(`${fn}: invalid RE2 pattern ${JSON.stringify(pattern)}: ${e instanceof Error ? e.message : String(e)}`);
     }
 };
+/** Run a runtime guard for its refusal, so a `checkArgs` never restates one. */
+const literalGuard = (run) => {
+    try {
+        run();
+        return undefined;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+};
 const num = (x) => Number(x);
 const minMax = (list, isMin) => {
     if (!Array.isArray(list) || list.length === 0)
@@ -62,6 +73,147 @@ const sortList = (list) => [...list].sort((a, b) => {
     }
     return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
 });
+/** The number-formatting locale, pinned rather than defaulted.
+ *
+ *  d3-format's default locale renders a negative with U+2212 MINUS SIGN, so
+ *  `format(-1.5, '.2f')` is `"−1.50"` and not `"-1.50"` — a string that no
+ *  downstream parser, comparison or diff treats as the number it looks like.
+ *  Every field here is fixed to its ASCII form for the same reason the layer is
+ *  locale-free at all: the same manifest must render the same bytes on every
+ *  runtime, and a second engine implementing the specifier grammar has to be
+ *  able to reproduce these exactly. */
+const FORMAT_LOCALE = formatLocale({
+    decimal: ".",
+    thousands: ",",
+    grouping: [3],
+    currency: ["$", ""],
+    minus: "-",
+    percent: "%",
+    nan: "NaN",
+});
+/** Largest integer a double represents exactly. */
+const MAX_EXACT_INT = 9007199254740991n;
+/** A CEL `int` is a BigInt in this runtime and `d3-format` throws on one
+ *  outright, so a formattable argument is converted here. Past 2^53 a double
+ *  stops representing every integer, and silently emitting a number that is not
+ *  the one the author computed is the defect class this family exists to close —
+ *  so that case raises instead. */
+const formattable = (fn, x) => {
+    if (typeof x === "bigint") {
+        if (x > MAX_EXACT_INT || x < -MAX_EXACT_INT) {
+            throw new Error(`${fn}: integer ${x} exceeds 2^53-1 and cannot be formatted exactly as a double`);
+        }
+        return Number(x);
+    }
+    const n = Number(x);
+    // The runtime backstop behind the typed registrations. A value that is not a
+    // number formats as the string "NaN", which is the failure this family exists
+    // to remove: it looks like an answer and prints into a document. Named here
+    // rather than coerced, the way an instant argument is.
+    if (!Number.isFinite(n)) {
+        throw new Error(`${fn}: expected a finite number, got ${JSON.stringify(x)}`);
+    }
+    return n;
+};
+/** Specifier type characters d3 implements. An unknown one PARSES — `.2q`
+ *  yields `"1"` rather than throwing — so a typo would silently format against
+ *  the default type. The set is checked here so a bad specifier is refused
+ *  rather than quietly answered. */
+const FORMAT_TYPES = new Set([..."efgrs%pbodxXcn"]);
+/** A specifier is a CEL value, so it can be request-derived — an `Http.Server`
+ *  evaluating `format(x, request.query.spec)` would otherwise grow this map for
+ *  the life of the process, and it is module-global, so every in-process kernel
+ *  shares it. Cleared wholesale at the cap rather than evicted one at a time: a
+ *  manifest's real specifier set is a handful of constants that repopulate
+ *  immediately, and an LRU is machinery for a hit rate nothing here needs. */
+const FORMATTER_CACHE_MAX = 256;
+const formatterCache = new Map();
+const formatter = (fn, spec) => {
+    const text = String(spec);
+    const cached = formatterCache.get(text);
+    if (cached)
+        return cached;
+    const type = text.slice(-1);
+    if (text !== "" && /[a-zA-Z%]/.test(type) && !FORMAT_TYPES.has(type)) {
+        throw new Error(`${fn}: unknown format type '${type}' (one of ${[...FORMAT_TYPES].join("")})`);
+    }
+    // The `.precision` group — width is the digits BEFORE the dot, so this is the
+    // only `.`-digits sequence the grammar admits.
+    const precision = /\.(\d+)/.exec(text);
+    if (precision)
+        digitCount(fn, precision[1]);
+    let built;
+    try {
+        built = FORMAT_LOCALE.format(text);
+    }
+    catch {
+        throw new Error(`${fn}: invalid format specifier ${JSON.stringify(text)}`);
+    }
+    if (formatterCache.size >= FORMATTER_CACHE_MAX)
+        formatterCache.clear();
+    formatterCache.set(text, built);
+    return built;
+};
+/** Decimal places, bounded. The ceiling is well below what `toFixed` accepts
+ *  because past it the digits are an artefact of the binary representation
+ *  rather than of the value.
+ *
+ *  ONE rule, enforced wherever a precision is written: `formatter` applies it to
+ *  a specifier's `.precision` group too. Bounding only this spelling let an
+ *  author route around the guard by writing `format(x, '.11f')` instead of
+ *  `fixed(x, 11)` — the family giving two answers to one question. It is not the
+ *  grammar subsetting the "full d3 surface" decision refuses: every specifier
+ *  type and flag stays available, and only the digit count is capped. */
+const MAX_DECIMALS = 10;
+const digitCount = (fn, digits) => {
+    const n = Number(digits);
+    if (!Number.isInteger(n) || n < 0 || n > MAX_DECIMALS) {
+        throw new Error(`${fn}: decimal places must be an integer 0-${MAX_DECIMALS}, got ${String(digits)}`);
+    }
+    return n;
+};
+/** Render a minute count against a declared day length. The day is a policy
+ *  argument, never an assumption — see the catalog entry's summary. */
+const durationText = (minutes, minutesPerDay) => {
+    const perDay = Math.round(formattable("formatDuration", minutesPerDay));
+    if (!Number.isFinite(perDay) || perDay <= 0) {
+        throw new Error(`formatDuration: minutesPerDay must be a positive number, got ${perDay}`);
+    }
+    const total = Math.round(formattable("formatDuration", minutes));
+    if (!Number.isFinite(total)) {
+        throw new Error(`formatDuration: minutes must be a finite number`);
+    }
+    const magnitude = Math.abs(total);
+    const days = Math.floor(magnitude / perDay);
+    const withinDay = magnitude % perDay;
+    const hours = Math.floor(withinDay / 60);
+    const mins = withinDay % 60;
+    const parts = [];
+    if (days)
+        parts.push(`${days}d`);
+    if (hours)
+        parts.push(`${hours}h`);
+    if (mins)
+        parts.push(`${mins}m`);
+    if (parts.length === 0)
+        parts.push("0m");
+    return `${total < 0 ? "-" : ""}${parts.join(" ")}`;
+};
+/** Refuse an unknown zone in this family's own voice. Left to `Intl`, the
+ *  failure is a raw `RangeError` naming neither the function nor what was
+ *  wrong with the argument — the only refusal here that did not read
+ *  `<fn>: <what is wrong>`, and whose wording belongs to the JS engine rather
+ *  than to Telo. Also the guard `checkArgs` runs at analysis time, so a literal
+ *  zone is checked once and answered identically in both places. */
+const assertZone = (fn, tz) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    }
+    catch {
+        throw new Error(`${fn}: unknown IANA time zone ${JSON.stringify(tz)}`);
+    }
+    return tz;
+};
 /** `Intl.DateTimeFormat` is an ECMA-402 global in Node (full ICU) and browsers,
  *  so timezone handling needs no Node-only API and stays browser-safe. */
 const zoneParts = (date, tz, opts) => {
@@ -75,8 +227,7 @@ const zoneParts = (date, tz, opts) => {
  *  offset (e.g. `2026-06-06T18:30:00.000-05:00`). Uses only standard Intl
  *  fields and derives the offset arithmetically, so it needs no newer Intl
  *  type-lib features and stays portable. */
-const isoInZone = (tz) => {
-    const now = new Date();
+const isoInZone = (now, tz) => {
     if (tz === "UTC" || tz === "Z")
         return now.toISOString();
     const p = zoneParts(now, tz, {
@@ -98,14 +249,148 @@ const isoInZone = (tz) => {
         : `${offsetMin > 0 ? "+" : "-"}${String(Math.floor(Math.abs(offsetMin) / 60)).padStart(2, "0")}:${String(Math.abs(offsetMin) % 60).padStart(2, "0")}`;
     return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}.${ms}${offset}`;
 };
-/** Current calendar date (`YYYY-MM-DD`) in `tz`. */
-const dateInZone = (tz) => {
-    const now = new Date();
+/** Calendar date (`YYYY-MM-DD`) of an instant in `tz`. */
+const dateInZone = (now, tz) => {
     if (tz === "UTC" || tz === "Z")
         return now.toISOString().slice(0, 10);
     const p = zoneParts(now, tz, { year: "numeric", month: "2-digit", day: "2-digit" });
     return `${p.year}-${p.month}-${p.day}`;
 };
+const zonedFields = (date, tz) => {
+    const p = zoneParts(date, tz, {
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    return {
+        year: +p.year,
+        month: +p.month,
+        day: +p.day,
+        hour: +p.hour,
+        minute: +p.minute,
+        second: +p.second,
+    };
+};
+/** The zone's offset at `date`, in milliseconds — its wall clock read as UTC,
+ *  minus the real instant. The same arithmetic `isoInZone` does. */
+const zoneOffsetMs = (date, tz) => {
+    const f = zonedFields(date, tz);
+    return Date.UTC(f.year, f.month - 1, f.day, f.hour, f.minute, f.second) - date.getTime();
+};
+const sameWallClock = (a, b) => a.year === b.year &&
+    a.month === b.month &&
+    a.day === b.day &&
+    a.hour === b.hour &&
+    a.minute === b.minute &&
+    a.second === b.second;
+/** The instant whose wall clock in `tz` is the given fields.
+ *
+ *  The offset depends on the instant being solved for, so this takes the offset
+ *  at the UTC reading, corrects, and then CHECKS by reading the result back.
+ *  That check is the whole point: a plain fixpoint settles on an instant whose
+ *  wall clock is not the one asked for whenever the requested time does not
+ *  exist, and it settles BACKWARDS — which silently moves the calendar day, the
+ *  one thing `addMonths` and `startOfMonth` exist to control. Chile jumps
+ *  00:00 → 01:00 on 2026-09-06 and Cuba on 2026-03-08, so "the 6th at midnight"
+ *  there is not a time; a fixpoint answered "the 5th at 23:00".
+ *
+ *  Resolution follows Java's `ZonedDateTime` and Temporal's `compatible`:
+ *  a wall clock that exists twice (a fall-back) takes the EARLIER instant, and
+ *  one that does not exist (a spring-forward gap) shifts FORWARD out of the gap,
+ *  which keeps the requested day. */
+const instantOfZoned = (f, tz) => {
+    const asUtc = Date.UTC(f.year, f.month - 1, f.day, f.hour, f.minute, f.second);
+    const offsetA = zoneOffsetMs(new Date(asUtc), tz);
+    const candidateA = asUtc - offsetA;
+    const offsetB = zoneOffsetMs(new Date(candidateA), tz);
+    if (offsetA === offsetB)
+        return new Date(candidateA);
+    const candidateB = asUtc - offsetB;
+    const aHolds = sameWallClock(zonedFields(new Date(candidateA), tz), f);
+    const bHolds = sameWallClock(zonedFields(new Date(candidateB), tz), f);
+    if (aHolds && bHolds)
+        return new Date(Math.min(candidateA, candidateB));
+    if (aHolds)
+        return new Date(candidateA);
+    if (bHolds)
+        return new Date(candidateB);
+    return new Date(Math.max(candidateA, candidateB));
+};
+/** `Date.UTC` maps years 0-99 to 1900-1999, so the year is set explicitly. */
+const daysInMonth = (year, month) => {
+    const d = new Date(Date.UTC(2000, month, 0));
+    d.setUTCFullYear(year, month, 0);
+    return d.getUTCDate();
+};
+/** An instant argument arrives as a `Date`; anything else is a caller error the
+ *  type-checker did not catch (a `dyn` slot), so it is named rather than
+ *  coerced into an Invalid Date that formats as `NaN`. */
+const instantArg = (fn, v) => {
+    if (v instanceof Date && Number.isFinite(v.getTime()))
+        return v;
+    throw new Error(`${fn}: expected a timestamp`);
+};
+/** Drop entries whose value is null or the empty string. Nothing else: an empty
+ *  list or map is a value someone deliberately built. CEL hands a map over as a
+ *  plain object or a `Map` depending on how it was produced, so both are read. */
+const compactValue = (v) => {
+    const keep = (x) => x !== null && x !== undefined && x !== "";
+    if (Array.isArray(v))
+        return v.filter(keep);
+    if (v instanceof Map) {
+        return new Map([...v.entries()].filter(([, value]) => keep(value)));
+    }
+    // A PLAIN object only. Rebuilding an arbitrary object from its entries is how
+    // a byte buffer becomes `{"0":137,…}` and an instant becomes `{}` — silently,
+    // and looking like a value. The same rule the compile walker follows, and the
+    // same "name it rather than coerce it" the instant argument follows.
+    if (v !== null && typeof v === "object") {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Error(`compact: expected a map or a list, got ${v.constructor?.name ?? "an object"}`);
+        }
+        return Object.fromEntries(Object.entries(v).filter(([, value]) => keep(value)));
+    }
+    throw new Error(`compact: expected a map or a list, got ${JSON.stringify(v)}`);
+};
+/** A CEL map as entries. Read the way `compact` reads one — a map arrives as a
+ *  plain object or a `Map` depending on how it was produced — and refusing
+ *  anything that is not one, since rebuilding an arbitrary object from its
+ *  entries is how a byte buffer becomes `{"0":137,…}` silently. A LIST is named
+ *  rather than coerced: CEL's `+` already concatenates lists, so a list here is
+ *  a mistake with a spelling that works, not a case to support. */
+const mapEntries = (fn, v) => {
+    if (v instanceof Map)
+        return [...v.entries()];
+    if (Array.isArray(v))
+        throw new Error(`${fn}: expected a map, got a list — use '+' to join lists`);
+    if (v !== null && typeof v === "object") {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Error(`${fn}: expected a map, got ${v.constructor?.name ?? "an object"}`);
+        }
+        return Object.entries(v);
+    }
+    throw new Error(`${fn}: expected a map, got ${JSON.stringify(v)}`);
+};
+/** Right-hand precedence, so `merge(defaults, overrides)` reads as it looks.
+ *
+ *  The map case is the one with no spelling at all — `+` joins lists and
+ *  strings and refuses maps — so a child kind inheriting a map-valued field
+ *  could only REPLACE it. That turns a default the parent set for a reason into
+ *  something every consumer must restate, and a consumer who restates it
+ *  incompletely gets a system that works until the omitted entry matters.
+ *
+ *  Follows the LEFT argument's shape: this extends that map, so what comes back
+ *  is what was extended. */
+const mergeMaps = (a, b) => {
+    const entries = [...mapEntries("merge", a), ...mapEntries("merge", b)];
+    return a instanceof Map ? new Map(entries) : Object.fromEntries(entries);
+};
 const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 /** Base64 → bytes, written out rather than delegated: `Buffer` is not browser-
  *  safe and `atob` round-trips through a string, which is the corruption this
@@ -417,12 +702,30 @@ export const CEL_FUNCTIONS = [
     },
     {
         name: "round",
-        signature: "round(dyn): double",
+        signature: "round(dyn, int?): double",
+        register: [
+            "round(double): double",
+            "round(int): double",
+            "round(double, int): double",
+            "round(int, int): double",
+        ],
         category: "math",
-        summary: "Round to the nearest integer.",
+        summary: "Round to the nearest integer, or to the given number of decimal places (0–10). The two-argument form shares the formatter's rounding rule, so a rounded value and the cell rendered beside it agree at the boundary. An integer past 2^53 is refused rather than rounded to a neighbour.",
         deterministic: true,
         hostBacked: false,
-        build: () => (x) => Math.round(num(x)),
+        // Both arities go through `formattable`, so the 2^53 refusal does not depend
+        // on which one the author wrote. Guarding only the two-argument form left
+        // `round(x)` silently answering with a neighbouring integer — the defect
+        // this family exists to close, reachable by writing one fewer argument.
+        build: () => (x, digits) => digits === undefined
+            ? Math.round(formattable("round", x))
+            : Number(formattable("round", x).toFixed(digitCount("round", digits))),
+        checkArgs: (lit) => literalGuard(() => {
+            if (lit[1] !== undefined)
+                digitCount("round", lit[1]);
+            if (typeof lit[0] === "bigint")
+                formattable("round", lit[0]);
+        }),
     },
     {
         name: "min",
@@ -619,7 +922,7 @@ export const CEL_FUNCTIONS = [
         summary: "Current time as ISO-8601; UTC by default, or in the given IANA timezone.",
         deterministic: false,
         hostBacked: false,
-        build: () => (tz) => isoInZone(tz ?? "UTC"),
+        build: () => (tz) => isoInZone(new Date(), tz ?? "UTC"),
     },
     {
         name: "today",
@@ -628,7 +931,7 @@ export const CEL_FUNCTIONS = [
         summary: "Current calendar date (YYYY-MM-DD); UTC by default, or in the given IANA timezone.",
         deterministic: false,
         hostBacked: false,
-        build: () => (tz) => dateInZone(tz ?? "UTC"),
+        build: () => (tz) => dateInZone(new Date(), tz ?? "UTC"),
     },
     {
         name: "nowMillis",
@@ -675,6 +978,169 @@ export const CEL_FUNCTIONS = [
         hostBacked: false,
         build: () => (t) => BigInt(Math.floor(t.getTime() / 1000)),
     },
+    // Formatting. The number surface is the d3-format specifier grammar in full,
+    // `[[fill]align][sign][symbol][0][width][,][.precision][~][type]`, so a chart
+    // axis label and the table cell beside it cannot round the same value two
+    // ways. Rounding is therefore d3's: `f` rounds the double at the decimal
+    // place, so `.2f` of 1.005 is "1.00" — 1.005 is not representable and the
+    // nearest double sits below the half.
+    {
+        name: "format",
+        signature: "format(dyn, string): string",
+        // Registered per numeric type rather than as `dyn`. A `dyn` first parameter
+        // accepted a string and answered "NaN" — a value that looks like an answer
+        // and prints into a document. A genuinely dynamic expression still passes,
+        // because cel-js matches `dyn` against any declared parameter type; what
+        // this rejects is a STATICALLY known wrong type, at `telo check`.
+        register: ["format(double, string): string", "format(int, string): string"],
+        category: "formatting",
+        summary: "Format a number with a d3-format specifier (`.2f`, `,.2f`, `.1%`, `.2s`).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x, spec) => formatter("format", spec)(formattable("format", x)),
+        checkArgs: (lit) => literalGuard(() => {
+            if (lit[1] !== undefined)
+                formatter("format", lit[1]);
+            if (typeof lit[0] === "bigint")
+                formattable("format", lit[0]);
+        }),
+    },
+    {
+        name: "fixed",
+        signature: "fixed(dyn, int): string",
+        register: ["fixed(double, int): string", "fixed(int, int): string"],
+        category: "formatting",
+        summary: "Fixed-decimal string with the given number of places (0–10).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x, digits) => formatter("fixed", `.${digitCount("fixed", digits)}f`)(formattable("fixed", x)),
+        checkArgs: (lit) => literalGuard(() => {
+            if (lit[1] !== undefined)
+                digitCount("fixed", lit[1]);
+            if (typeof lit[0] === "bigint")
+                formattable("fixed", lit[0]);
+        }),
+    },
+    {
+        name: "formatDuration",
+        signature: "formatDuration(dyn, int): string",
+        register: [
+            "formatDuration(double, int): string",
+            "formatDuration(int, int): string",
+        ],
+        category: "formatting",
+        summary: "Render a minute count against a declared day length: `formatDuration(510, 480)` is `1d 30m`. The day length is an argument because it is a policy, not arithmetic. The result is a rendering for a reader, not a duration literal — its `d` is the declared day, so it must not be fed back into a field that parses a duration.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (minutes, minutesPerDay) => durationText(minutes, minutesPerDay),
+        checkArgs: (lit) => literalGuard(() => {
+            if (lit[1] !== undefined)
+                durationText(lit[0] ?? 0, lit[1]);
+        }),
+    },
+    {
+        name: "dateIn",
+        signature: "dateIn(timestamp, string?): string",
+        register: [
+            "dateIn(google.protobuf.Timestamp): string",
+            "dateIn(google.protobuf.Timestamp, string): string",
+        ],
+        category: "time",
+        summary: "Calendar date (`YYYY-MM-DD`) of an instant, in an IANA zone (UTC by default).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (t, tz) => dateInZone(instantArg("dateIn", t), assertZone("dateIn", tz ?? "UTC")),
+        checkArgs: (lit) => literalGuard(() => {
+            if (typeof lit[1] === "string")
+                assertZone("dateIn", lit[1]);
+        }),
+    },
+    {
+        name: "isoIn",
+        signature: "isoIn(timestamp, string?): string",
+        register: [
+            "isoIn(google.protobuf.Timestamp): string",
+            "isoIn(google.protobuf.Timestamp, string): string",
+        ],
+        category: "time",
+        summary: "ISO-8601 rendering of an instant, in an IANA zone (UTC by default).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (t, tz) => isoInZone(instantArg("isoIn", t), assertZone("isoIn", tz ?? "UTC")),
+        checkArgs: (lit) => literalGuard(() => {
+            if (typeof lit[1] === "string")
+                assertZone("isoIn", lit[1]);
+        }),
+    },
+    {
+        name: "startOfMonth",
+        signature: "startOfMonth(timestamp, string?): timestamp",
+        register: [
+            "startOfMonth(google.protobuf.Timestamp): google.protobuf.Timestamp",
+            "startOfMonth(google.protobuf.Timestamp, string): google.protobuf.Timestamp",
+        ],
+        category: "time",
+        summary: "Midnight on the 1st of the instant's month, in an IANA zone (UTC by default).",
+        deterministic: true,
+        hostBacked: false,
+        checkArgs: (lit) => literalGuard(() => {
+            if (typeof lit[1] === "string")
+                assertZone("startOfMonth", lit[1]);
+        }),
+        build: () => (t, tz) => {
+            const zone = assertZone("startOfMonth", tz ?? "UTC");
+            const f = zonedFields(instantArg("startOfMonth", t), zone);
+            return instantOfZoned({ year: f.year, month: f.month, day: 1, hour: 0, minute: 0, second: 0 }, zone);
+        },
+    },
+    {
+        name: "addMonths",
+        signature: "addMonths(timestamp, int, string?): timestamp",
+        register: [
+            "addMonths(google.protobuf.Timestamp, int): google.protobuf.Timestamp",
+            "addMonths(google.protobuf.Timestamp, int, string): google.protobuf.Timestamp",
+        ],
+        category: "time",
+        summary: "Shift an instant by whole months in an IANA zone, clamping the day of month (Jan 31 + 1 month is Feb 28).",
+        deterministic: true,
+        hostBacked: false,
+        checkArgs: (lit) => literalGuard(() => {
+            if (typeof lit[2] === "string")
+                assertZone("addMonths", lit[2]);
+        }),
+        build: () => (t, months, tz) => {
+            const zone = assertZone("addMonths", tz ?? "UTC");
+            const f = zonedFields(instantArg("addMonths", t), zone);
+            const shifted = f.year * 12 + (f.month - 1) + Number(months);
+            // `%` takes the dividend's sign in JS, so a negative total would yield
+            // month 0. Unreachable for realistic dates and wrong for free otherwise.
+            const year = Math.floor(shifted / 12);
+            const month = (((shifted % 12) + 12) % 12) + 1;
+            return instantOfZoned({ ...f, year, month, day: Math.min(f.day, daysInMonth(year, month)) }, zone);
+        },
+    },
+    {
+        name: "compact",
+        signature: "compact(dyn): dyn",
+        // A `dyn` parameter accepted an instant (yielding `{}`) and a byte buffer
+        // (yielding `{"0":137,…}`), both silently and both passing `telo check`.
+        register: ["compact(list): list", "compact(map): map"],
+        category: "collection",
+        summary: "Drop entries whose value is null or the empty string, from a map or a list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (v) => compactValue(v),
+    },
+    {
+        name: "merge",
+        signature: "merge(map, map): map",
+        register: ["merge(map, map): map"],
+        category: "collection",
+        summary: "Combine two maps, with the right-hand map winning on a shared key. Use it to add to a map rather than replace it — `merge(defaults, overrides)`.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (a, b) => mergeMaps(a, b),
+    },
     // UUID
     {
         name: "uuidv1",

package/dist/cel/diagnose.d.ts

@@ -32,6 +32,11 @@ export declare function functionIndex(env: Environment): FunctionIndex;
 export interface CallAudit {
     readonly diagnostics: readonly EngineDiagnostic[];
     readonly calls: readonly CallSite[];
+    /** Refusals decided from arguments written as literals. Reported whatever the
+     *  type-checker said, unlike {@link CallAudit.diagnostics}: a call whose types
+     *  are all correct and whose specifier is `.2q` type-checks perfectly, and is
+     *  exactly the defect this catches. */
+    readonly argumentIssues: readonly EngineDiagnostic[];
     /** Names that resolve, but that no registered signature accepts as written.
      *  The caller appends their signatures to a type-check failure it could not
      *  otherwise explain. */