@telorun/templating 0.12.0 → 0.14.0

package/README.md

@@ -23,9 +23,9 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api
+$ telo ./examples/todo-app
 
-{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8077"}
 ```
 
 ## Why use Telo?

package/dist/builtins.d.ts

@@ -8,6 +8,17 @@ import type { TemplatingEngine } from "./engine.js";
  *  another (e.g. `cel + literal`); always ship the same set. */
 export declare const builtinEngines: readonly TemplatingEngine[];
 export declare function createDefaultRegistry(): TemplatingEngineRegistry;
+/**
+ * The type a tag always produces, or undefined when its produced type is a
+ * function of the slot rather than of the tag (`!cel`, `!ref`).
+ *
+ * The single reader of `TemplatingEngine.producedType`, so a consumer asks the
+ * registry what a tag produces instead of recognising tag names — the same seam
+ * `fileClaims` opened for payload membership. Reads the default registry
+ * because a produced type is a property of the engine, not of a host's
+ * configuration, and every host ships the same built-in set.
+ */
+export declare function producedTypeOf(engineName: string): Record<string, unknown> | undefined;
 /** Memoized singleton: returns the default registry. Hosts that don't need
  *  per-instance isolation (precompile, the analyzer's tagged-value walker)
  *  should use this so they share the same registry instance the YAML tag

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAKrD,CAAC;AAEF,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAOrD,CAAC;AAEF,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEtF;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}

package/dist/builtins.js

@@ -1,4 +1,5 @@
 import { celEngine } from "./engines/cel.js";
+import { includeBytesEngine, includeTextEngine } from "./engines/include.js";
 import { literalEngine } from "./engines/literal.js";
 import { refEngine } from "./engines/ref.js";
 import { sqlEngine } from "./engines/sql.js";
@@ -11,6 +12,8 @@ import { TemplatingEngineRegistry } from "./registry.js";
  *  another (e.g. `cel + literal`); always ship the same set. */
 export const builtinEngines = [
     celEngine,
+    includeBytesEngine,
+    includeTextEngine,
     literalEngine,
     refEngine,
     sqlEngine,
@@ -22,6 +25,19 @@ export function createDefaultRegistry() {
     }
     return registry;
 }
+/**
+ * The type a tag always produces, or undefined when its produced type is a
+ * function of the slot rather than of the tag (`!cel`, `!ref`).
+ *
+ * The single reader of `TemplatingEngine.producedType`, so a consumer asks the
+ * registry what a tag produces instead of recognising tag names — the same seam
+ * `fileClaims` opened for payload membership. Reads the default registry
+ * because a produced type is a property of the engine, not of a host's
+ * configuration, and every host ships the same built-in set.
+ */
+export function producedTypeOf(engineName) {
+    return defaultRegistry().get(engineName)?.producedType?.();
+}
 let defaultRegistryCache;
 /** Memoized singleton: returns the default registry. Hosts that don't need
  *  per-instance isolation (precompile, the analyzer's tagged-value walker)

package/dist/cel/analyze.d.ts

@@ -29,7 +29,8 @@ export declare function findNullableAccessIssues(node: ASTNode, contextSchema: R
  * Check whether a member-access chain accesses only fields declared in a JSON Schema.
  * Returns an error string if a field is unknown in a schema that declares explicit
  * properties without `additionalProperties: true`, or if the chain attempts to
- * reach inside an `x-telo-stream: true` property.
+ * reach inside a `live` value type — one whose consumption has effects, so its
+ * contents exist only for a consumer that drains it.
  * Returns null when the chain is valid or the schema is too open to judge.
  */
 export declare function validateChainAgainstSchema(chain: string[], schema: Record<string, any>): string | null;

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;AAEpD;;;;;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;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CA2Bf"}
+{"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"}

package/dist/cel/analyze.js

@@ -1,3 +1,4 @@
+import { isLiveSlot } from "@telorun/sdk";
 /**
  * Extract all member-access chains from a CEL AST.
  * Returns arrays like ["request", "query", "name"] for `request.query.name`.
@@ -254,7 +255,8 @@ function walkNullable(node, nonNull, boundVars, issues, schema) {
  * Check whether a member-access chain accesses only fields declared in a JSON Schema.
  * Returns an error string if a field is unknown in a schema that declares explicit
  * properties without `additionalProperties: true`, or if the chain attempts to
- * reach inside an `x-telo-stream: true` property.
+ * reach inside a `live` value type — one whose consumption has effects, so its
+ * contents exist only for a consumer that drains it.
  * Returns null when the chain is valid or the schema is too open to judge.
  */
 export function validateChainAgainstSchema(chain, schema) {
@@ -268,10 +270,7 @@ export function validateChainAgainstSchema(chain, schema) {
             return null;
         if (key in props) {
             const propSchema = props[key];
-            if (propSchema &&
-                typeof propSchema === "object" &&
-                propSchema["x-telo-stream"] === true &&
-                i < chain.length - 1) {
+            if (isLiveSlot(propSchema) && i < chain.length - 1) {
                 const path = chain.slice(0, i + 1).join(".");
                 return `'${path}' yields a stream — pipe it through an Encoder or iterate in a JS.Script step (no member access on stream-typed values)`;
             }

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;AAyE5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAogBlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}
+{"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;AAyE5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EA+hBlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}

package/dist/cel/catalog.js

@@ -540,6 +540,33 @@ export const CEL_FUNCTIONS = [
         hostBacked: false,
         build: () => () => BigInt(Math.floor(Date.now() / 1000)),
     },
+    // Timestamp conversions. cel-go's standard library defines both and cel-js
+    // ships neither, which is what made an instant a one-way door: timestamp
+    // arithmetic and the `getFullYear` / `getHours` family already work, but
+    // nothing converted the result back into a value a manifest field accepts,
+    // so an expiry could be computed and not stored. Semantics follow cel-go
+    // exactly — RFC 3339 and epoch SECONDS — so `int(timestamp)` and
+    // `timestamp(int)` round-trip in one unit.
+    {
+        name: "string",
+        signature: "string(timestamp): string",
+        register: ["string(google.protobuf.Timestamp): string"],
+        category: "conversion",
+        summary: "Format an instant as RFC 3339 (ISO-8601, UTC).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (t) => t.toISOString(),
+    },
+    {
+        name: "int",
+        signature: "int(timestamp): int",
+        register: ["int(google.protobuf.Timestamp): int"],
+        category: "conversion",
+        summary: "Epoch seconds of an instant (the unit `timestamp(int)` reads back).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (t) => BigInt(Math.floor(t.getTime() / 1000)),
+    },
     // UUID
     {
         name: "uuidv1",

package/dist/cel/diagnose.d.ts

@@ -0,0 +1,50 @@
+import type { ASTNode, Environment } from "@marcbachmann/cel-js";
+import type { CallSite, EngineDiagnostic } from "../engine.js";
+/** Classifies every function call in a CEL expression against the environment's
+ *  own function registry.
+ *
+ *  This exists because cel-js reports one sentence for three unrelated mistakes
+ *  — a name that does not exist, a name called in the wrong form, and a genuine
+ *  type mismatch all surface as `found no matching overload for 'f(...)'`. Two
+ *  of those readings actively mislead: the message names argument types, so the
+ *  repair for `startsWith(key, 'x')` looks like a cast, when the real fix is
+ *  `key.startsWith('x')` and no cast helps.
+ *
+ *  Nothing here reads cel-js's message text. `Environment.getDefinitions()`
+ *  reports every registered signature — cel-js builtins and Telo's catalog
+ *  alike — with its call form and parameters, and the AST distinguishes `f(x)`
+ *  from `x.f()` structurally. Name existence, call form and arity are therefore
+ *  decidable by lookup, which is what keeps a cel-js version bump from silently
+ *  degrading this back into the passthrough it replaced. */
+/** One registered signature, reduced to what classification needs. */
+interface FnEntry {
+    readonly signature: string;
+    readonly form: "global" | "receiver";
+    /** Parameter count, excluding the receiver for a receiver form. */
+    readonly arity: number;
+}
+export interface FunctionIndex {
+    readonly byName: ReadonlyMap<string, readonly FnEntry[]>;
+}
+/** Registry view of an environment, memoized: environments are rebuilt per
+ *  analysis path, but each is immutable once built. */
+export declare function functionIndex(env: Environment): FunctionIndex;
+export interface CallAudit {
+    readonly diagnostics: readonly EngineDiagnostic[];
+    readonly calls: readonly CallSite[];
+    /** 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. */
+    readonly unresolved: readonly string[];
+}
+/** Classify every call in `ast`. Runs unconditionally rather than only after a
+ *  failed type-check, because a type-check reports its first error and stops:
+ *  an expression with two bad calls would otherwise fix one, re-run, and
+ *  discover the next. */
+export declare function auditCalls(source: string, ast: ASTNode, env: Environment): CallAudit;
+/** Registered signatures for names a type-check failure mentions, so the
+ *  residual says what the function actually accepts rather than only echoing
+ *  what the author wrote. */
+export declare function explainUnresolved(names: readonly string[], env: Environment): string;
+export {};
+//# sourceMappingURL=diagnose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/cel/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,QAAQ,EAAiB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE9E;;;;;;;;;;;;;;;4DAe4D;AAE5D,sEAAsE;AACtE,UAAU,OAAO;IACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC;CAC1D;AAWD;uDACuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAiB7D;AAuJD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC;;6BAEyB;IACzB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;yBAGyB;AACzB,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,CA0DpF;AAED;;6BAE6B;AAC7B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAIpF"}

package/dist/cel/diagnose.js

@@ -0,0 +1,223 @@
+import { CEL_FUNCTIONS } from "./catalog.js";
+/** Determinism is Telo catalog metadata; cel-js builtins carry none. Absent
+ *  means "no signal", never "deterministic" — consumers of
+ *  `CallSite.deterministic` must not read undefined as a guarantee. */
+const DETERMINISM = new Map(CEL_FUNCTIONS.map((f) => [f.name, f.deterministic]));
+const INDEX_CACHE = new WeakMap();
+/** Registry view of an environment, memoized: environments are rebuilt per
+ *  analysis path, but each is immutable once built. */
+export function functionIndex(env) {
+    const cached = INDEX_CACHE.get(env);
+    if (cached)
+        return cached;
+    const byName = new Map();
+    for (const fn of env.getDefinitions().functions) {
+        const form = fn.receiverType === null ? "global" : "receiver";
+        const entry = { signature: fn.signature, form, arity: fn.params?.length ?? 0 };
+        const entries = byName.get(fn.name);
+        if (entries)
+            entries.push(entry);
+        else
+            byName.set(fn.name, [entry]);
+    }
+    const index = { byName };
+    INDEX_CACHE.set(env, index);
+    return index;
+}
+/** Macros the parser expands rather than dispatching through the registry, so
+ *  they never appear in `getDefinitions()` and would otherwise classify as
+ *  unknown names.
+ *
+ *  Deliberately short: most macros ARE registered, and the caller only reports
+ *  this audit when the type-checker already rejected the expression, so a macro
+ *  missing from here degrades to "no extra explanation" rather than to a false
+ *  error on valid CEL. That is what keeps a cel-js upgrade from turning a new
+ *  macro into a manifest this analyzer refuses. */
+const MACROS = new Set(["optMap", "optFlatMap"]);
+function isNode(v) {
+    return typeof v === "object" && v !== null && "op" in v;
+}
+/** Every non-macro call in the expression, in source order. */
+function collectCalls(root, index) {
+    const out = [];
+    visit(root);
+    return out.sort((a, b) => a.start - b.start);
+    function visit(node) {
+        const args = node.args;
+        if (node.op === "call" || node.op === "rcall") {
+            const tuple = args;
+            const name = tuple[0];
+            if (typeof name === "string" && !MACROS.has(name)) {
+                const receiver = node.op === "rcall" ? tuple[1] : undefined;
+                const rawArgs = node.op === "rcall" ? tuple[2] : tuple[1];
+                const callArgs = (Array.isArray(rawArgs) ? rawArgs : []).filter(isNode);
+                out.push({
+                    name,
+                    form: node.op === "rcall" ? "receiver" : "global",
+                    arity: callArgs.length,
+                    start: node.start,
+                    end: node.end,
+                    ...(index.byName.has(name) ? { deterministic: DETERMINISM.get(name) } : {}),
+                    ...(isNode(receiver) ? { receiver } : {}),
+                    args: callArgs,
+                });
+            }
+        }
+        for (const arg of Array.isArray(args) ? args : [args]) {
+            if (isNode(arg))
+                visit(arg);
+            else if (Array.isArray(arg))
+                for (const item of arg)
+                    if (isNode(item))
+                        visit(item);
+        }
+    }
+}
+/** Node shapes that can carry a `.` on their right without reparsing
+ *  differently. Everything else — an operator expression, a literal that would
+ *  sit against the dot — is parenthesized when moved into receiver position. */
+const SELF_DELIMITING = new Set(["id", ".", ".?", "call", "rcall", "[]", "[?]"]);
+/** Source text of a node. When it is about to become a receiver it may need
+ *  parentheses: an identifier, member chain, index or call is self-delimiting,
+ *  but an operator expression or a bare literal against a `.` is not. */
+function nodeText(source, node, asReceiver = false) {
+    const text = source.slice(node.start, node.end);
+    if (!asReceiver)
+        return text;
+    return SELF_DELIMITING.has(node.op) ? text : `(${text})`;
+}
+/** The same call written in the other form, or undefined when the shape does
+ *  not allow it (a global call with no arguments has no receiver to move). */
+function transpose(source, call) {
+    if (call.form === "global") {
+        const [first, ...rest] = call.args;
+        if (!first)
+            return undefined;
+        const argText = rest.map((a) => nodeText(source, a));
+        return `${nodeText(source, first, true)}.${call.name}(${argText.join(", ")})`;
+    }
+    if (!call.receiver)
+        return undefined;
+    const argText = [nodeText(source, call.receiver), ...call.args.map((a) => nodeText(source, a))];
+    return `${call.name}(${argText.join(", ")})`;
+}
+/** Splice a rewritten call back into the full source. The fix always carries
+ *  the whole corrected source, so a consumer applies it by replacing the
+ *  scalar. */
+function spliceFix(source, call, rewritten) {
+    return { replacement: source.slice(0, call.start) + rewritten + source.slice(call.end) };
+}
+/** Replace only the called name, leaving arguments untouched. The offset is
+ *  derived rather than searched: a receiver whose own text contains the name
+ *  (`slice.slice(1)`) would defeat a first-occurrence replace. */
+function renameFix(source, call, to) {
+    const searchFrom = call.receiver ? call.receiver.end : call.start;
+    const at = source.indexOf(call.name, searchFrom);
+    if (at === -1 || at >= call.end)
+        return undefined;
+    return { replacement: source.slice(0, at) + to + source.slice(at + call.name.length) };
+}
+/** Arity the call would need in the other form: moving a receiver in adds an
+ *  argument, moving it out removes one. */
+function transposedArity(call) {
+    return call.form === "global" ? call.arity - 1 : call.arity + 1;
+}
+function accepts(entries, form, arity) {
+    return entries.some((e) => e.form === form && e.arity === arity);
+}
+const listOf = (names) => [...new Set(names)].sort().join(", ");
+/** Names registered in exactly the form and arity the author wrote — the only
+ *  ones that could replace this call with no further edits. Ranked by shared
+ *  prefix, which is what reaches `nowIso` from `now`; edit distance never
+ *  would (3 characters against a 3-character name). Returns [] when nothing
+ *  shares a prefix, so the caller lists what is legal here instead of
+ *  guessing. */
+function candidates(call, index) {
+    const written = call.name.toLowerCase();
+    return callableHere(call, index)
+        .filter((name) => {
+        const lower = name.toLowerCase();
+        return lower.startsWith(written) || written.startsWith(lower);
+    })
+        .sort((a, b) => a.length - b.length || a.localeCompare(b));
+}
+/** Every name callable in exactly the position written — same form, same
+ *  argument count. Arity is what makes the list usable: a receiver's type is
+ *  `dyn` at analysis time so every method is nominally reachable, and printing
+ *  all forty says nothing. */
+function callableHere(call, index) {
+    const names = [];
+    for (const [name, entries] of index.byName) {
+        if (name !== call.name && accepts(entries, call.form, call.arity))
+            names.push(name);
+    }
+    return names;
+}
+function signaturesOf(name, index) {
+    return (index.byName.get(name) ?? []).map((e) => e.signature);
+}
+/** Spread-friendly optional `fix`, so an undecidable rewrite simply omits the
+ *  field rather than carrying `undefined` into the diagnostic. */
+const withFix = (fix) => (fix ? { fix } : {});
+/** Classify every call in `ast`. Runs unconditionally rather than only after a
+ *  failed type-check, because a type-check reports its first error and stops:
+ *  an expression with two bad calls would otherwise fix one, re-run, and
+ *  discover the next. */
+export function auditCalls(source, ast, env) {
+    const index = functionIndex(env);
+    const diagnostics = [];
+    const unresolved = [];
+    const calls = collectCalls(ast, index);
+    for (const call of calls) {
+        const entries = index.byName.get(call.name);
+        const noun = call.form === "receiver" ? "method" : "function";
+        if (!entries) {
+            const near = candidates(call, index);
+            const hint = near.length > 0
+                ? `Closest taking ${call.arity} argument${call.arity === 1 ? "" : "s"}: ${near
+                    .slice(0, 5)
+                    .map((n) => `\`${n}\``)
+                    .join(", ")}.`
+                : `Every ${noun} taking ${call.arity} argument${call.arity === 1 ? "" : "s"}: ${listOf(callableHere(call, index))}.`;
+            diagnostics.push({
+                code: "CEL_UNKNOWN_FUNCTION",
+                message: `there is no ${noun} \`${call.name}\`. ${hint} Full list: \`telo cel functions\`.`,
+                // A single candidate is an unambiguous rename; several are a menu, and
+                // applying an arbitrary one would be a guess wearing a fix's clothes.
+                ...(near.length === 1 ? withFix(renameFix(source, call, near[0])) : {}),
+            });
+            continue;
+        }
+        if (accepts(entries, call.form, call.arity))
+            continue;
+        const otherForm = call.form === "global" ? "receiver" : "global";
+        if (accepts(entries, otherForm, transposedArity(call))) {
+            const rewritten = transpose(source, call);
+            const written = source.slice(call.start, call.end);
+            diagnostics.push({
+                code: "CEL_WRONG_CALL_FORM",
+                message: `\`${call.name}\` is ${call.form === "global"
+                    ? "a method, not a global function — call it on the value"
+                    : "a global function, not a method — pass the value to it"}:` +
+                    (rewritten ? `\n  write:  ${rewritten}\n  not:    ${written}` : "") +
+                    `\nRegistered: ${listOf(signaturesOf(call.name, index))}.`,
+                ...withFix(rewritten ? spliceFix(source, call, rewritten) : undefined),
+            });
+            continue;
+        }
+        unresolved.push(call.name);
+    }
+    return {
+        diagnostics,
+        calls: calls.map(({ receiver: _receiver, args: _args, ...site }) => site),
+        unresolved,
+    };
+}
+/** Registered signatures for names a type-check failure mentions, so the
+ *  residual says what the function actually accepts rather than only echoing
+ *  what the author wrote. */
+export function explainUnresolved(names, env) {
+    const index = functionIndex(env);
+    const signatures = [...new Set(names)].flatMap((n) => signaturesOf(n, index));
+    return signatures.length > 0 ? ` Registered: ${listOf(signatures)}.` : "";
+}

package/dist/cel/environment.d.ts

@@ -24,5 +24,12 @@ export type { CelHandlers } from "./catalog.js";
  *  Returns `[signature]` unchanged when no `?` is present or the signature
  *  cannot be parsed. */
 export declare function deriveSignatures(signature: string): string[];
+/** The environment before any Telo function is registered — i.e. exactly
+ *  cel-js's own built-ins. Documentation needs to tell the two apart, and
+ *  subtracting by signature TEXT does not work: cel-js normalizes a declared
+ *  `list` to `list<dyn>`, so the catalog's documented spelling and the
+ *  registered one differ for a third of the entries. Asking for the base set
+ *  directly needs no matching at all. */
+export declare function celBuiltinFunctions(): ReturnType<Environment["getDefinitions"]>["functions"];
 export declare function buildCelEnvironment(handlers?: Partial<CelHandlers>): Environment;
 //# sourceMappingURL=environment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoBhD;;;;;;;;;;;;;;;yDAeyD;AACzD;;;;;wBAKwB;AACxB,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB5D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAkBpF"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoBhD;;;;;;;;;;;;;;;yDAeyD;AACzD;;;;;wBAKwB;AACxB,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB5D;AAYD;;;;;yCAKyC;AACzC,wBAAgB,mBAAmB,IAAI,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAE5F;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAcpF"}

package/dist/cel/environment.js

@@ -66,13 +66,27 @@ export function deriveSignatures(signature) {
         return `${name}(${allParams.join(", ")}): ${returnType}`;
     });
 }
+/** cel-go defaults HomogeneousAggregateLiterals OFF: heterogeneous list/map
+ *  literals unify to `dyn` rather than erroring. cel-js flips that default to
+ *  strict; we align with cel-go so manifests (dyn-heavy: request, rows, …)
+ *  don't hit false positives the runtime evaluates fine. */
+const ENVIRONMENT_OPTIONS = {
+    unlistedVariablesAreDyn: true,
+    enableOptionalTypes: true,
+    homogeneousAggregateLiterals: false,
+};
+/** The environment before any Telo function is registered — i.e. exactly
+ *  cel-js's own built-ins. Documentation needs to tell the two apart, and
+ *  subtracting by signature TEXT does not work: cel-js normalizes a declared
+ *  `list` to `list<dyn>`, so the catalog's documented spelling and the
+ *  registered one differ for a third of the entries. Asking for the base set
+ *  directly needs no matching at all. */
+export function celBuiltinFunctions() {
+    return new Environment(ENVIRONMENT_OPTIONS).getDefinitions().functions;
+}
 export function buildCelEnvironment(handlers = {}) {
     const h = { ...STUB_HANDLERS, ...handlers };
-    // cel-go defaults HomogeneousAggregateLiterals OFF: heterogeneous list/map
-    // literals unify to `dyn` rather than erroring. cel-js flips that default to
-    // strict; we align with cel-go so manifests (dyn-heavy: request, rows, …)
-    // don't hit false positives the runtime evaluates fine.
-    let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true, homogeneousAggregateLiterals: false });
+    let env = new Environment(ENVIRONMENT_OPTIONS);
     for (const fn of CEL_FUNCTIONS) {
         const impl = fn.build(h);
         // `register` lists one cel-js signature per arity (overloaded functions).

package/dist/cel/walk.d.ts

@@ -1,3 +1,19 @@
+/** How an emitted expression sits in the scalar it came from. A repair can be
+ *  applied by replacing the scalar only when the expression covers all of it;
+ *  otherwise the literal text around it would be lost.
+ *
+ *  `wrapper` is the delimiter text to restore around a corrected expression —
+ *  empty for a tagged sentinel (whose scalar *is* the expression), `${{` / `}}`
+ *  for the legacy interpolation form. Carrying it as data rather than letting
+ *  each consumer re-derive it is what keeps `${{ … }}` a first-class fix site
+ *  instead of an exclusion: the two surfaces differ only by these delimiters. */
+export interface CelSurface {
+    readonly whole: boolean;
+    readonly wrapper?: {
+        readonly prefix: string;
+        readonly suffix: string;
+    };
+}
 /** Walks `value` and emits each templated source segment with its dotted
  *  path (e.g. `routes[0].handler.body`) and the engine that owns it.
  *
@@ -9,5 +25,5 @@
  *    routing through the registry stays generic so adding a third engine
  *    that wants real analysis doesn't require touching the walker.
  *  - Compiled values are skipped so a precompiled tree won't be re-walked. */
-export declare function walkCelExpressions(value: unknown, path: string, cb: (source: string, path: string, engineName: string) => void): void;
+export declare function walkCelExpressions(value: unknown, path: string, cb: (source: string, path: string, engineName: string, surface: CelSurface) => void): void;
 //# sourceMappingURL=walk.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../src/cel/walk.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;8EAU8E;AAC9E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GAC7D,IAAI,CAwBN"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../src/cel/walk.ts"],"names":[],"mappings":"AAGA;;;;;;;;iFAQiF;AACjF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAID;;;;;;;;;;8EAU8E;AAC9E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GAClF,IAAI,CAyCN"}

package/dist/cel/walk.js

@@ -1,5 +1,6 @@
 import { isTaggedSentinel } from "../sentinel.js";
 import { TEMPLATE_REGEX } from "./compile.js";
+const OPEN = "${{";
 /** Walks `value` and emits each templated source segment with its dotted
  *  path (e.g. `routes[0].handler.body`) and the engine that owns it.
  *
@@ -13,12 +14,29 @@ import { TEMPLATE_REGEX } from "./compile.js";
  *  - Compiled values are skipped so a precompiled tree won't be re-walked. */
 export function walkCelExpressions(value, path, cb) {
     if (isTaggedSentinel(value)) {
-        cb(value.source, path, value.engine);
+        cb(value.source, path, value.engine, { whole: true });
         return;
     }
     if (typeof value === "string") {
-        for (const m of value.matchAll(TEMPLATE_REGEX)) {
-            cb(m[1].trim(), path, "cel");
+        const matches = [...value.matchAll(TEMPLATE_REGEX)];
+        for (const m of matches) {
+            const expr = m[1].trim();
+            // A string that is nothing but one interpolation is as whole as a
+            // tagged scalar — the delimiters are the only difference, and they are
+            // handed back as the wrapper.
+            const only = matches.length === 1 && m.index === 0 && m[0].length === value.length;
+            const lead = /^\s*/.exec(m[0].slice(OPEN.length))[0].length;
+            cb(expr, path, "cel", {
+                whole: only,
+                ...(only
+                    ? {
+                        wrapper: {
+                            prefix: value.slice(0, OPEN.length + lead),
+                            suffix: value.slice(OPEN.length + lead + expr.length),
+                        },
+                    }
+                    : {}),
+            });
         }
         return;
     }