@telorun/templating 0.12.0 → 0.14.0

package/dist/manifest-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;kBAMkB;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEA+ByE;AACzE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoB7B,CAAC;AAqCF;;;;;;;;;;;;;;uDAcuD;AACvD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CA+C1D;AAED;;;;;+BAK+B;AAC/B,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;8BAG8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK9B,CAAC"}
+{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;kBAMkB;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEA+ByE;AACzE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoB7B,CAAC;AAGF;;;;;+BAK+B;AAC/B,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;8BAG8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK9B,CAAC"}

package/dist/manifest-schemas.js

@@ -58,101 +58,6 @@ export const ResourceRefSchema = {
         },
     ],
 };
-const REF_ANNOTATION = "x-telo-ref";
-// The legacy base types a reference slot used to pin when references were
-// written as plain strings. Post-migration a reference resolves to an object
-// (the `{kind, name, alias?}` shape, or an unresolved `!ref` sentinel), so a
-// scalar `type` on a ref slot is a stale constraint that would reject the
-// resolved value. Object / array `type`s are left alone — they already admit
-// the reference object (and any inline value a slot like `inputType` accepts).
-const LEGACY_REF_SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
-// JSON Schema keywords whose values are themselves subschemas. Split by shape so
-// the ref-slot normalizer recurses only into schema positions — never into
-// data-bearing keywords (`default`, `const`, `enum`, `examples`), where a stray
-// `x-telo-ref` key would be data, not an annotation.
-const SUBSCHEMA_SINGLE = [
-    "additionalProperties",
-    "additionalItems",
-    "contains",
-    "not",
-    "if",
-    "then",
-    "else",
-    "propertyNames",
-    "unevaluatedItems",
-    "unevaluatedProperties",
-];
-const SUBSCHEMA_LIST = ["allOf", "anyOf", "oneOf", "prefixItems"];
-const SUBSCHEMA_MAP = [
-    "properties",
-    "patternProperties",
-    "$defs",
-    "definitions",
-    "dependentSchemas",
-];
-/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
- *  reference-slot node — one carrying an `x-telo-ref` string annotation.
- *
- *  A reference slot's value is always a `!ref` sentinel or its resolved
- *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
- *  published modules still pin `type: "string"` on these slots — the encoding
- *  references took when they were written as plain strings — which now rejects
- *  the resolved object. Removing only the scalar `type` lets the analyzer and
- *  kernel accept references uniformly across module versions during the
- *  migration away from `{kind, name}` / string references, without disturbing
- *  slots that legitimately accept an inline object (e.g. `inputType` /
- *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
- *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
- *  checked separately by the analyzer's reference walker, which reads the
- *  original schema — not this validation-only copy. */
-export function normalizeRefSlots(schema) {
-    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
-        return schema;
-    }
-    const node = schema;
-    const out = { ...node };
-    // Reference slot with a stale scalar `type` (legacy string-ref encoding):
-    // drop the constraint so the resolved reference object / sentinel validates.
-    //
-    // A presence test, not a shape test — deliberately, since `templating` sits
-    // BELOW the analyzer in the dependency order and cannot reach the shared
-    // `readRefSlot` accessor. Presence is the only thing this rule needs, and it
-    // is stable across every annotation shape.
-    if (node[REF_ANNOTATION] !== undefined &&
-        typeof node.type === "string" &&
-        LEGACY_REF_SCALAR_TYPES.has(node.type)) {
-        delete out.type;
-    }
-    for (const key of SUBSCHEMA_SINGLE) {
-        const value = node[key];
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-            out[key] = normalizeRefSlots(value);
-        }
-    }
-    for (const key of SUBSCHEMA_LIST) {
-        const value = node[key];
-        if (Array.isArray(value))
-            out[key] = value.map(normalizeRefSlots);
-    }
-    // `items` is either a single subschema or a tuple of subschemas.
-    if (Array.isArray(node.items)) {
-        out.items = node.items.map(normalizeRefSlots);
-    }
-    else if (node.items && typeof node.items === "object") {
-        out.items = normalizeRefSlots(node.items);
-    }
-    for (const key of SUBSCHEMA_MAP) {
-        const value = node[key];
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-            const mapped = {};
-            for (const [name, sub] of Object.entries(value)) {
-                mapped[name] = normalizeRefSlots(sub);
-            }
-            out[key] = mapped;
-        }
-    }
-    return out;
-}
 /** Stable URI under which the shared manifest root schema is registered
  *  with module-side AJV instances. Module YAMLs reach the fragments via
  *  `$ref: "telo://manifest#/$defs/<Name>"`. The URI is the contract;

package/dist/sentinel.d.ts

@@ -19,4 +19,41 @@ export declare function makeTaggedSentinel(engine: string, source: string): Tagg
 export declare function isRefSentinel(v: unknown): v is TaggedSentinel & {
     engine: "ref";
 };
+/** The CEL engine's name. Beside the other sentinel predicates for the same
+ *  reason they are: a consumer that spells an engine name inline is a second
+ *  place the registry's key is written down. */
+export declare const CEL_ENGINE = "cel";
+/** Engine names of the two file-embedding tags. Named here beside the other
+ *  sentinel predicates so the kernel's resolution pass and the engines
+ *  themselves agree on one spelling. */
+export declare const INCLUDE_TEXT_ENGINE = "include-text";
+export declare const INCLUDE_BYTES_ENGINE = "include-bytes";
+/**
+ * The dotted chain a value names, or undefined.
+ *
+ * Only a PLAIN CHAIN — `steps.encode.result.output` — in either spelling a
+ * manifest may carry it: a `!cel` sentinel or the `${{ }}` string form. An
+ * expression that COMPUTES rather than names has no schema to read off a context,
+ * so a caller that navigates one gets nothing and reports nothing: silence where
+ * the analyzer knows least is the conservative direction.
+ *
+ * Here rather than in each caller because "is this expression a plain chain" is
+ * one question, and two copies of the answer would eventually disagree about a
+ * shape like `a.b[0]`.
+ */
+export declare function plainChainOf(value: unknown): string | undefined;
+/** Both file-embedding tag names, for a consumer holding an engine NAME rather
+ *  than a value (the analyzer's expression walk reports names). */
+export declare const INCLUDE_ENGINE_NAMES: ReadonlySet<string>;
+/** True when `v` is an `!include-text` / `!include-bytes` sentinel — a file
+ *  embed marked at parse time and still unresolved.
+ *
+ *  The kernel's creation-time resolution keys off this the way Phase-5
+ *  injection keys off {@link isRefSentinel}. Both tags survive precompile as
+ *  markers rather than collapsing to a value, because the read is deferred: a
+ *  manifest load must not pull payload layers, and the analyzer that types the
+ *  slot cannot open files at all. */
+export declare function isIncludeSentinel(v: unknown): v is TaggedSentinel & {
+    engine: typeof INCLUDE_TEXT_ENGINE | typeof INCLUDE_BYTES_ENGINE;
+};
 //# sourceMappingURL=sentinel.d.ts.map

package/dist/sentinel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;YAKY;AACZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEjF;AAED;;;;4CAI4C;AAC5C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,CAEjF"}
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;YAKY;AACZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEjF;AAED;;;;4CAI4C;AAC5C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,CAEjF;AAED;;gDAEgD;AAChD,eAAO,MAAM,UAAU,QAAQ,CAAC;AAEhC;;wCAEwC;AACxC,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAa/D;AAED;mEACmE;AACnE,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAGnD,CAAC;AAEH;;;;;;;qCAOqC;AACrC,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,OAAO,GACT,CAAC,IAAI,cAAc,GAAG;IAAE,MAAM,EAAE,OAAO,mBAAmB,GAAG,OAAO,oBAAoB,CAAA;CAAE,CAI5F"}

package/dist/sentinel.js

@@ -16,3 +16,57 @@ export function makeTaggedSentinel(engine, source) {
 export function isRefSentinel(v) {
     return isTaggedSentinel(v) && v.engine === "ref";
 }
+/** The CEL engine's name. Beside the other sentinel predicates for the same
+ *  reason they are: a consumer that spells an engine name inline is a second
+ *  place the registry's key is written down. */
+export const CEL_ENGINE = "cel";
+/** Engine names of the two file-embedding tags. Named here beside the other
+ *  sentinel predicates so the kernel's resolution pass and the engines
+ *  themselves agree on one spelling. */
+export const INCLUDE_TEXT_ENGINE = "include-text";
+export const INCLUDE_BYTES_ENGINE = "include-bytes";
+/**
+ * The dotted chain a value names, or undefined.
+ *
+ * Only a PLAIN CHAIN — `steps.encode.result.output` — in either spelling a
+ * manifest may carry it: a `!cel` sentinel or the `${{ }}` string form. An
+ * expression that COMPUTES rather than names has no schema to read off a context,
+ * so a caller that navigates one gets nothing and reports nothing: silence where
+ * the analyzer knows least is the conservative direction.
+ *
+ * Here rather than in each caller because "is this expression a plain chain" is
+ * one question, and two copies of the answer would eventually disagree about a
+ * shape like `a.b[0]`.
+ */
+export function plainChainOf(value) {
+    const source = isTaggedSentinel(value)
+        ? value.engine === CEL_ENGINE
+            ? value.source
+            : undefined
+        : typeof value === "string"
+            ? /^\s*\$\{\{(.+)\}\}\s*$/.exec(value)?.[1]
+            : undefined;
+    if (typeof source !== "string")
+        return undefined;
+    const trimmed = source.trim();
+    return /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(trimmed)
+        ? trimmed
+        : undefined;
+}
+/** Both file-embedding tag names, for a consumer holding an engine NAME rather
+ *  than a value (the analyzer's expression walk reports names). */
+export const INCLUDE_ENGINE_NAMES = new Set([
+    INCLUDE_TEXT_ENGINE,
+    INCLUDE_BYTES_ENGINE,
+]);
+/** True when `v` is an `!include-text` / `!include-bytes` sentinel — a file
+ *  embed marked at parse time and still unresolved.
+ *
+ *  The kernel's creation-time resolution keys off this the way Phase-5
+ *  injection keys off {@link isRefSentinel}. Both tags survive precompile as
+ *  markers rather than collapsing to a value, because the read is deferred: a
+ *  manifest load must not pull payload layers, and the analyzer that types the
+ *  slot cannot open files at all. */
+export function isIncludeSentinel(v) {
+    return (isTaggedSentinel(v) && (v.engine === INCLUDE_TEXT_ENGINE || v.engine === INCLUDE_BYTES_ENGINE));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/templating",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
   "keywords": [
     "telo",
@@ -44,7 +44,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.67.0"
+    "@telorun/sdk": "0.73.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/builtins.ts

@@ -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";
@@ -13,6 +14,8 @@ import type { TemplatingEngine } from "./engine.js";
  *  another (e.g. `cel + literal`); always ship the same set. */
 export const builtinEngines: readonly TemplatingEngine[] = [
   celEngine,
+  includeBytesEngine,
+  includeTextEngine,
   literalEngine,
   refEngine,
   sqlEngine,
@@ -26,6 +29,20 @@ export function createDefaultRegistry(): TemplatingEngineRegistry {
   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: string): Record<string, unknown> | undefined {
+  return defaultRegistry().get(engineName)?.producedType?.();
+}
+
 let defaultRegistryCache: TemplatingEngineRegistry | undefined;
 
 /** Memoized singleton: returns the default registry. Hosts that don't need

package/src/cel/analyze.ts

@@ -1,4 +1,5 @@
 import type { ASTNode } from "@marcbachmann/cel-js";
+import { isLiveSlot } from "@telorun/sdk";
 
 /**
  * Extract all member-access chains from a CEL AST.
@@ -291,7 +292,8 @@ function walkNullable(
  * 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(
@@ -306,12 +308,7 @@ export function validateChainAgainstSchema(
     if (!props) 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/src/cel/catalog.ts

@@ -613,6 +613,33 @@ export const CEL_FUNCTIONS: readonly CelFunctionDoc[] = [
     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: Date) => 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: Date) => BigInt(Math.floor(t.getTime() / 1000)),
+  },
   // UUID
   {
     name: "uuidv1",

package/src/cel/diagnose.ts

@@ -0,0 +1,293 @@
+import type { ASTNode, Environment } from "@marcbachmann/cel-js";
+import { CEL_FUNCTIONS } from "./catalog.js";
+import type { CallSite, DiagnosticFix, 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[]>;
+}
+
+/** 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: ReadonlyMap<string, boolean> = new Map(
+  CEL_FUNCTIONS.map((f) => [f.name, f.deterministic]),
+);
+
+const INDEX_CACHE = new WeakMap<Environment, FunctionIndex>();
+
+/** Registry view of an environment, memoized: environments are rebuilt per
+ *  analysis path, but each is immutable once built. */
+export function functionIndex(env: Environment): FunctionIndex {
+  const cached = INDEX_CACHE.get(env);
+  if (cached) return cached;
+
+  const byName = new Map<string, FnEntry[]>();
+
+  for (const fn of env.getDefinitions().functions) {
+    const form = fn.receiverType === null ? "global" : "receiver";
+    const entry: FnEntry = { 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: FunctionIndex = { byName };
+  INDEX_CACHE.set(env, index);
+  return index;
+}
+
+/** A call plus the nodes needed to rewrite it. Internal — `CallSite` is the
+ *  shape that crosses the engine seam. */
+interface RawCall extends CallSite {
+  readonly receiver?: ASTNode;
+  readonly args: readonly ASTNode[];
+}
+
+/** 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: unknown): v is ASTNode {
+  return typeof v === "object" && v !== null && "op" in (v as Record<string, unknown>);
+}
+
+/** Every non-macro call in the expression, in source order. */
+function collectCalls(root: ASTNode, index: FunctionIndex): RawCall[] {
+  const out: RawCall[] = [];
+  visit(root);
+  return out.sort((a, b) => a.start - b.start);
+
+  function visit(node: ASTNode): void {
+    const args = node.args as unknown;
+    if (node.op === "call" || node.op === "rcall") {
+      const tuple = args as unknown[];
+      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<string>(["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: string, node: ASTNode, asReceiver = false): string {
+  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: string, call: RawCall): string | undefined {
+  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: string, call: RawCall, rewritten: string): DiagnosticFix {
+  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: string, call: RawCall, to: string): DiagnosticFix | undefined {
+  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: RawCall): number {
+  return call.form === "global" ? call.arity - 1 : call.arity + 1;
+}
+
+function accepts(entries: readonly FnEntry[], form: CallSite["form"], arity: number): boolean {
+  return entries.some((e) => e.form === form && e.arity === arity);
+}
+
+const listOf = (names: readonly string[]): string => [...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: RawCall, index: FunctionIndex): string[] {
+  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: RawCall, index: FunctionIndex): string[] {
+  const names: string[] = [];
+  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: string, index: FunctionIndex): string[] {
+  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: DiagnosticFix | undefined): { fix?: DiagnosticFix } => (fix ? { fix } : {});
+
+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 function auditCalls(source: string, ast: ASTNode, env: Environment): CallAudit {
+  const index = functionIndex(env);
+  const diagnostics: EngineDiagnostic[] = [];
+  const unresolved: string[] = [];
+  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: readonly string[], env: Environment): string {
+  const index = functionIndex(env);
+  const signatures = [...new Set(names)].flatMap((n) => signaturesOf(n, index));
+  return signatures.length > 0 ? ` Registered: ${listOf(signatures)}.` : "";
+}

package/src/cel/environment.ts

@@ -71,13 +71,29 @@ export function deriveSignatures(signature: string): string[] {
   });
 }
 
+/** 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,
+} as const;
+
+/** 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(): ReturnType<Environment["getDefinitions"]>["functions"] {
+  return new Environment(ENVIRONMENT_OPTIONS).getDefinitions().functions;
+}
+
 export function buildCelEnvironment(handlers: Partial<CelHandlers> = {}): Environment {
   const h: CelHandlers = { ...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).