@telorun/templating 0.12.0 → 0.13.0

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).

package/src/cel/walk.ts

@@ -1,6 +1,22 @@
 import { isTaggedSentinel } from "../sentinel.js";
 import { TEMPLATE_REGEX } from "./compile.js";
 
+/** 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 };
+}
+
+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.
  *
@@ -15,15 +31,32 @@ import { TEMPLATE_REGEX } from "./compile.js";
 export function walkCelExpressions(
   value: unknown,
   path: string,
-  cb: (source: string, path: string, engineName: string) => void,
+  cb: (source: string, path: string, engineName: string, surface: CelSurface) => void,
 ): void {
   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;
   }

package/src/engine.ts

@@ -12,18 +12,95 @@ export interface CompileEnv {
  *  the path-specific effective context (kernel globals merged in, x-telo-context
  *  applied) and hands the engine a single closed schema. The engine validates
  *  member-access chains against it. `null` means "open context" — no chain
- *  validation possible. */
+ *  validation possible.
+ *
+ *  `celEnv` is the environment **typed for this path**, not the bare base one:
+ *  the engine type-checks against it, so the caller must not check the same
+ *  expression again against a different environment. One expression, one
+ *  verdict. */
 export interface AnalyzeEnv {
   readonly celEnv: Environment;
   readonly contextSchema: Record<string, unknown> | null;
 }
 
+/** A mechanically applicable repair for a diagnostic. `replacement` is the
+ *  **whole analyzed source**, corrected — never a fragment — so a consumer can
+ *  apply it by replacing the scalar node without knowing anything about the
+ *  language inside it.
+ *
+ *  There is deliberately no sub-range narrowing "what changed". Carrying one
+ *  beside a whole-value replacement offers two readings of the same field, and
+ *  the minimal-edit reading — splice `replacement` at `range` — produces
+ *  garbage, since the two measure different strings. No consumer needed it, so
+ *  the ambiguity bought nothing.
+ *
+ *  Producers emit a fix only when the repair is decidable. A fix that might not
+ *  compile is worse than none: the field exists so an IDE can apply it without
+ *  asking, and an agent can take it without re-deriving it from prose. */
+export interface DiagnosticFix {
+  readonly replacement: string;
+}
+
 /** A single static-analysis finding produced by an engine. Stable codes match
  *  the analyzer's existing diagnostic codes so downstream filtering keeps
  *  working unchanged across the engine boundary. */
 export interface EngineDiagnostic {
   readonly message: string;
   readonly code?: string;
+  readonly fix?: DiagnosticFix;
+}
+
+/** One function call an engine found in the source it analyzed. Reported
+ *  regardless of whether the call is valid: consumers apply policy the engine
+ *  cannot know (an `x-telo-eval: compile` field rejecting a non-deterministic
+ *  call), and policy that depends on manifest context does not belong in a
+ *  templating engine. */
+export interface CallSite {
+  readonly name: string;
+  /** How it was written — `f(x)` vs `x.f()`. */
+  readonly form: "global" | "receiver";
+  /** Argument count as written; excludes the receiver. */
+  readonly arity: number;
+  /** Offsets of the whole call within the analyzed source. */
+  readonly start: number;
+  readonly end: number;
+  /** Whether the resolved function re-evaluates per call. `undefined` when the
+   *  name resolves to nothing, or to a function carrying no determinism
+   *  metadata — absent is not "deterministic". */
+  readonly deterministic?: boolean;
+}
+
+/** What one `analyze` call establishes about one source. Everything derivable
+ *  from the expression alone is derived here, once; everything that needs
+ *  manifest context (the field's declared type, its eval mode, which verdict
+ *  outranks which) is left to the caller, which is the only side that has it. */
+export interface AnalyzeResult {
+  readonly diagnostics: readonly EngineDiagnostic[];
+  /** Type the engine's checker resolved, when it type-checks and succeeded. */
+  readonly type?: string;
+  /** Every function call in the source, in source order. */
+  readonly calls: readonly CallSite[];
+}
+
+/** One module-relative file a tagged node embeds, reported by the engine that
+ *  owns the tag.
+ *
+ *  `path` is relative to the module root — the directory holding `telo.yaml` —
+ *  never to the file the tag was written in. That is the rule every other file
+ *  reference in a manifest already follows (a controller's `path=` qualifier,
+ *  `files:` / `assets:` patterns), and it is what makes a claim survive publish:
+ *  publish deletes `include:` and inlines every partial as an extra document
+ *  into the single published `telo.yaml`, so the declaring file does not exist
+ *  in the artifact and a per-file-relative path would change meaning there.
+ *
+ *  The path is ALL an engine reports. Which artifact layer the file belongs in
+ *  is packaging's vocabulary, from a spec this package otherwise knows nothing
+ *  about, and the analyzer already owns that assignment for controller
+ *  candidates — so a new layer role stays a change to one package rather than
+ *  two. An object rather than a bare string so a future hint (eager/lazy, say)
+ *  costs no consumer a signature change. */
+export interface EngineFileClaim {
+  readonly path: string;
 }
 
 /** Per-property templating engine. Matches a YAML tag (`!<name>`); the kernel
@@ -48,6 +125,22 @@ export interface TemplatingEngine {
   compile(source: string, env: CompileEnv): CompiledValue | unknown;
 
   /** Static analysis hook. Engines that can't statically check (e.g. `literal`)
-   *  return []. The walker accumulates diagnostics across all values. */
-  analyze(source: string, env: AnalyzeEnv): readonly EngineDiagnostic[];
+   *  return an empty result. The walker accumulates diagnostics across all
+   *  values and applies its own policy to `calls` / `type`. */
+  analyze(source: string, env: AnalyzeEnv): AnalyzeResult;
+
+  /** Module-relative files this tagged node embeds, if any.
+   *
+   *  The single seam through which payload membership is discovered: publish
+   *  asks the registry what each tag claims rather than recognising tags by
+   *  name, so a future tag that embeds files is a one-file change and no
+   *  consumer downstream grows a second vocabulary for reading a manifest.
+   *  This is the `ref-slot.ts` / `zone-slot.ts` precedent applied to tags.
+   *
+   *  Optional, and absent on every engine that embeds nothing (`cel`, `ref`,
+   *  `literal`, `sql`). Pure string work over the source — it must never read
+   *  the filesystem, because the analyzer that calls it runs in the browser.
+   *  A source the engine considers malformed claims nothing; `analyze` is what
+   *  reports why. */
+  fileClaims?(source: string): readonly EngineFileClaim[];
 }

package/src/engines/cel.ts

@@ -4,54 +4,114 @@ import {
   validateChainAgainstSchema,
 } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
-import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import { auditCalls, explainUnresolved } from "../cel/diagnose.js";
+import type { AnalyzeEnv, AnalyzeResult, EngineDiagnostic, TemplatingEngine } from "../engine.js";
 
 /** Statically analyze one CEL expression against the effective context schema:
- *  parse → extract member-access chains → validate each chain → flag nullable
- *  access. Single source of truth shared by the `!cel` engine (one expression)
- *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
- *  can't drift between them. */
-export function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[] {
+ *  parse → classify every call → type-check → validate member-access chains →
+ *  flag nullable access. Single source of truth shared by the `!cel` engine
+ *  (one expression) and the `!sql` engine (one per `${{ }}` interpolation), so
+ *  diagnostic wording can't drift between them.
+ *
+ *  The type-check lives here, not in the analyzer, so one expression produces
+ *  one verdict against one environment. Splitting them let an opaque
+ *  "no matching overload" survive next to the diagnostic that actually
+ *  explained it, and left `${{ }}` interpolations chain-validated but never
+ *  type-checked at all. */
+export function analyzeCelExpression(source: string, env: AnalyzeEnv): AnalyzeResult {
   const out: EngineDiagnostic[] = [];
 
   let parsed: ReturnType<typeof env.celEnv.parse>;
   try {
     parsed = env.celEnv.parse(source);
   } catch (e) {
-    out.push({
-      code: "CEL_SYNTAX_ERROR",
-      message: e instanceof Error ? e.message : String(e),
-    });
-    return out;
+    return {
+      diagnostics: [{ code: "CEL_SYNTAX_ERROR", message: e instanceof Error ? e.message : String(e) }],
+      calls: [],
+    };
   }
 
-  if (!env.contextSchema) return out;
+  const audit = auditCalls(source, parsed.ast, env.celEnv);
 
-  const chains = extractAccessChains(parsed.ast);
-  for (const chain of chains) {
-    const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
-    if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+  let type: string | undefined;
+  let checkError: string | undefined;
+  try {
+    const result = env.celEnv.check(source);
+    if (result.valid) type = result.type;
+    else if (result.error) {
+      checkError = String((result.error as { message?: string }).message ?? result.error)
+        .split("\n")[0]!
+        .trim();
+    }
+  } catch (e) {
+    // The checker is now the ONLY type verdict for every CEL expression, so a
+    // crash here silently retires static typing for that expression. Report it
+    // instead: degrading is acceptable, degrading invisibly is not.
+    return {
+      diagnostics: [
+        {
+          code: "CEL_TYPE_ERROR",
+          message: `the CEL type-checker failed on this expression: ${
+            e instanceof Error ? e.message : String(e)
+          }`,
+        },
+      ],
+      calls: audit.calls,
+    };
   }
 
-  for (const issue of findNullableAccessIssues(
-    parsed.ast,
-    env.contextSchema as Record<string, any>,
-  )) {
-    // Index access (member "[index]") attaches without a dot; a named field
-    // attaches with one — so the suggested CEL stays valid either way.
-    const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
-    out.push({
-      code: "CEL_NULLABLE_ACCESS",
-      message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
-    });
+  // The audit only ever EXPLAINS a rejection — it never overrules acceptance.
+  // Its classification is decided from the registry, so a call cel-js accepts
+  // but the registry cannot account for (a macro the parser expands and the
+  // registry never sees, which a cel-js upgrade can introduce at any time) must
+  // not become a hard error on valid CEL. Reporting nothing where cel-js is
+  // happy makes an unknown future macro a silent no-op rather than a manifest
+  // this analyzer refuses and the kernel would run fine.
+  if (checkError !== undefined) {
+    // `check()` stops at its first problem; the audit enumerates every bad call,
+    // which is the whole reason it exists as more than a message rewriter.
+    out.push(...audit.diagnostics);
+    if (audit.diagnostics.length === 0) {
+      out.push({
+        code: "CEL_TYPE_ERROR",
+        message: checkError + explainUnresolved(audit.unresolved, env.celEnv) + DYN_HINT(checkError),
+      });
+    }
   }
-  return out;
+
+  if (env.contextSchema) {
+    const contextSchema = env.contextSchema as Record<string, any>;
+    for (const chain of extractAccessChains(parsed.ast)) {
+      const err = validateChainAgainstSchema(chain, contextSchema);
+      if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+    }
+
+    for (const issue of findNullableAccessIssues(parsed.ast, contextSchema)) {
+      // Index access (member "[index]") attaches without a dot; a named field
+      // attaches with one — so the suggested CEL stays valid either way.
+      const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+      out.push({
+        code: "CEL_NULLABLE_ACCESS",
+        message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+      });
+    }
+  }
+
+  return { diagnostics: out, calls: audit.calls, ...(type === undefined ? {} : { type }) };
 }
 
+/** `dyn` in a checker message means an operand whose type is unknown here —
+ *  almost always a step result whose invoked resource declares no
+ *  `outputType:`. Without this, the reader takes `dyn` for a cast problem. */
+const DYN_HINT = (message: string): string =>
+  // Word-bounded: "dynamic" appears in unrelated checker messages, and the
+  // hint is wrong for those.
+  /\bdyn\b/.test(message)
+    ? " (`dyn` is a value with no static type here — declare `outputType:` on the resource producing it, or convert at the call site.)"
+    : "";
+
 /** The `!cel` engine. Treats the entire tagged scalar as a single CEL
- *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
- *  as the untagged path: parse → extract member-access chains → validate each
- *  chain against the effective context schema. */
+ *  expression — no `${{ }}` wrapping. */
 export const celEngine: TemplatingEngine = {
   name: "cel",
   language: "cel",