@telorun/templating 0.12.0 → 0.14.0

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,42 @@ 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[];
+
+  /** The type this tag ALWAYS produces, as a JSON Schema fragment.
+   *
+   *  Declared by the engine, never recognised by a consumer — the `fileClaims`
+   *  precedent applied to the one fact it left behind. Before this, the analyzer
+   *  hardcoded two tag names to hand an `!include-bytes` a byte placeholder and
+   *  an `!include-text` a string one; the only place a tag's produced type was
+   *  written down was in its consumer, so a future tag producing bytes had to be
+   *  added to a set rather than declaring it.
+   *
+   *  Absent for an engine whose produced type is a function of the SLOT rather
+   *  than of the tag — `!cel`, whose type is only derivable from the expression,
+   *  and `!ref`, which is an identity marker. Their values keep taking a
+   *  slot-shaped placeholder.
+   *
+   *  What falls out is the property this preserves exactly: because an embed's
+   *  type is a constant of the tag, a byte embed at a string slot and text at a
+   *  byte slot both fail statically, through the ordinary schema check and with
+   *  no diagnostic code of their own. */
+  producedType?(): Record<string, unknown>;
 }

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",

package/src/engines/include.ts

@@ -0,0 +1,164 @@
+import type { EngineFileClaim, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import { INCLUDE_BYTES_ENGINE, INCLUDE_TEXT_ENGINE, makeTaggedSentinel } from "../sentinel.js";
+
+/** Characters that would make a path a pattern rather than a name. Globs are
+ *  excluded deliberately: a claim has to name one file for publish to place it
+ *  in a layer, and a pattern that matches nothing on the publishing machine
+ *  would ship an artifact missing a file the manifest reads. */
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/** `scheme:` prefix — a URL, or a Windows drive letter. Either way not a
+ *  module-relative path. */
+const URI_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+
+export interface NormalizedIncludePath {
+  /** Module-root-relative path with `./` and `.` segments folded out, `/`
+   *  separated. Absent when the source is not a usable path. */
+  readonly path?: string;
+  readonly diagnostic?: EngineDiagnostic;
+}
+
+/**
+ * Normalize an `!include-*` source to a module-root-relative path, or explain
+ * why it is not one.
+ *
+ * Pure string work, deliberately: this runs in the analyzer, which must load in
+ * a browser, so confinement is decided from the written path alone and never by
+ * asking a filesystem where it lands. That is possible because the path is
+ * root-relative by definition — the module root is the one directory every path
+ * is measured from, so `..` below depth zero is an escape regardless of where
+ * the module happens to sit on disk.
+ */
+export function normalizeIncludePath(source: string): NormalizedIncludePath {
+  const raw = source.trim();
+  if (raw === "") {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message: "the path is empty — name a file relative to the module root.",
+      },
+    };
+  }
+  if (URI_SCHEME.test(raw)) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message:
+          `'${raw}' names a location outside the module. An include path is a file that ships ` +
+          `inside the module artifact, written relative to the module root. To read a file at ` +
+          `runtime from somewhere else, use Fs.File.`,
+      },
+    };
+  }
+  if (GLOB_CHARS.test(raw)) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message:
+          `'${raw}' looks like a pattern. An include path names exactly one file, because ` +
+          `publish places each claimed file into a layer by name.`,
+      },
+    };
+  }
+  if (raw.startsWith("/") || raw.startsWith("\\")) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_ESCAPES_MODULE",
+        message:
+          `'${raw}' is an absolute path. An include path is written relative to the module ` +
+          `root, so the same manifest resolves identically from a checkout and from a ` +
+          `published artifact.`,
+      },
+    };
+  }
+
+  const out: string[] = [];
+  for (const segment of raw.split(/[/\\]+/)) {
+    if (segment === "" || segment === ".") continue;
+    if (segment !== "..") {
+      out.push(segment);
+      continue;
+    }
+    // Depth zero is the module root. Popping past it would read a file the
+    // artifact cannot contain, so it is an escape rather than a path to
+    // normalize — and catching it here is what keeps the check static.
+    if (out.length === 0) {
+      return {
+        diagnostic: {
+          code: "INCLUDE_PATH_ESCAPES_MODULE",
+          message:
+            `'${raw}' points above the module root. An include path may only name a file ` +
+            `inside the module, since that is the only thing its artifact can carry.`,
+        },
+      };
+    }
+    out.pop();
+  }
+  if (out.length === 0) {
+    return {
+      diagnostic: {
+        code: "INCLUDE_PATH_INVALID",
+        message: `'${raw}' resolves to the module root, not to a file.`,
+      },
+    };
+  }
+  return { path: out.join("/") };
+}
+
+/**
+ * The `!include-text` / `!include-bytes` engines — a file that ships inside the
+ * module artifact, embedded as a manifest value.
+ *
+ * `compile` returns the sentinel unchanged rather than a value. Two things
+ * follow, and both are the point. The read is deferred to resource creation, so
+ * loading a manifest does not pull payload layers — the artifact spec makes
+ * `telo.yaml` its own layer precisely so that reading a manifest cannot drag the
+ * whole artifact in, and an app loads every imported library's manifest. And
+ * because the marker survives precompile the way a `!ref` does, the analyzer can
+ * type the slot without opening the file, which is what keeps it browser-safe.
+ * Unlike `!ref`, no special case is needed in `precompileDoc`: an engine whose
+ * `compile` is identity on its own marker passes through the generic path.
+ *
+ * `analyze` reports why a path is unusable; `fileClaims` reports the path itself
+ * so publish can place the file in a layer without recognising the tag by name.
+ */
+function includeEngine(name: string, produced: Record<string, unknown>): TemplatingEngine {
+  return {
+    name,
+
+    compile(source) {
+      return makeTaggedSentinel(name, source);
+    },
+
+    producedType() {
+      return produced;
+    },
+
+    analyze(source) {
+      const { diagnostic } = normalizeIncludePath(source);
+      return { diagnostics: diagnostic ? [diagnostic] : [], calls: [] };
+    },
+
+    fileClaims(source): readonly EngineFileClaim[] {
+      const { path } = normalizeIncludePath(source);
+      // A malformed path claims nothing. `analyze` is what says why, so
+      // claiming a half-understood path here would produce a second, worse
+      // report from publish about the same mistake.
+      return path ? [{ path }] : [];
+    },
+  };
+}
+
+/** Embeds a file's contents as a UTF-8 string. */
+export const includeTextEngine: TemplatingEngine = includeEngine(INCLUDE_TEXT_ENGINE, {
+  type: "string",
+});
+
+/** Embeds a file's contents as raw bytes — the shape every `Telo.Bytes` slot
+ *  accepts. The name is written as a literal rather than imported from the SDK:
+ *  templating is the lower package, and a produced type is a schema fragment,
+ *  which is data. What checks it is the registry the analyzer and the kernel both
+ *  read. */
+export const includeBytesEngine: TemplatingEngine = includeEngine(INCLUDE_BYTES_ENGINE, {
+  "x-telo-type": "Telo.Bytes",
+});

package/src/engines/literal.ts

@@ -11,6 +11,6 @@ export const literalEngine: TemplatingEngine = {
   },
 
   analyze() {
-    return [];
+    return { diagnostics: [], calls: [] };
   },
 };

package/src/engines/ref.ts

@@ -17,6 +17,6 @@ export const refEngine: TemplatingEngine = {
   },
 
   analyze() {
-    return [];
+    return { diagnostics: [], calls: [] };
   },
 };

package/src/engines/sql.ts

@@ -1,7 +1,12 @@
 import { isParameterizedSql, type CompiledValue, type ParameterizedSql } from "@telorun/sdk";
 import { analyzeCelExpression } from "./cel.js";
 import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
-import type { TemplatingEngine } from "../engine.js";
+import type {
+  CallSite,
+  DiagnosticFix,
+  EngineDiagnostic,
+  TemplatingEngine,
+} from "../engine.js";
 
 export { isParameterizedSql, type ParameterizedSql };
 
@@ -30,15 +35,44 @@ export const sqlEngine: TemplatingEngine = {
   analyze(source, env) {
     // Each `${{ }}` interpolation is its own CEL expression; reuse the shared
     // per-expression analyzer so diagnostics match the `!cel` engine exactly.
-    return expressionsOf(source).flatMap((expr) => analyzeCelExpression(expr, env));
+    // Each interpolation's offset is kept so a fix computed against the bare
+    // expression is re-anchored to the whole SQL scalar — the only thing that
+    // ever made `!sql` fix-less was dropping it here.
+    const diagnostics: EngineDiagnostic[] = [];
+    const calls: CallSite[] = [];
+    for (const { expr, start } of expressionsOf(source)) {
+      const result = analyzeCelExpression(expr, env);
+      for (const d of result.diagnostics) {
+        diagnostics.push(d.fix ? { ...d, fix: reanchor(source, expr, start, d.fix) } : d);
+      }
+      for (const c of result.calls) {
+        calls.push({ ...c, start: start + c.start, end: start + c.end });
+      }
+    }
+    // No `type`: a SQL template is a string built from many expressions, so
+    // there is no single checked type to report.
+    return { diagnostics, calls };
   },
 };
 
-/** Extract each `${{ expr }}` body from a `!sql` template source. */
-function expressionsOf(source: string): string[] {
-  const exprs: string[] = [];
+/** Re-anchor a fix computed against one interpolation onto the full source. */
+function reanchor(source: string, expr: string, start: number, fix: DiagnosticFix): DiagnosticFix {
+  return {
+    replacement: source.slice(0, start) + fix.replacement + source.slice(start + expr.length),
+  };
+}
+
+/** Each `${{ expr }}` body in a `!sql` template, with the body's offset in the
+ *  source. The offset is derived from the opening delimiter and the leading
+ *  whitespace the capture group already trims, never by searching for the
+ *  body text — which a body appearing twice would defeat. */
+function expressionsOf(source: string): { expr: string; start: number }[] {
+  const out: { expr: string; start: number }[] = [];
   for (const m of source.matchAll(TEMPLATE_REGEX)) {
-    exprs.push(m[1]!.trim());
+    const lead = /^\s*/.exec(m[0]!.slice(OPEN.length))![0]!.length;
+    out.push({ expr: m[1]!, start: m.index! + OPEN.length + lead });
   }
-  return exprs;
+  return out;
 }
+
+const OPEN = "${{";

package/src/index.ts

@@ -1,4 +1,9 @@
-export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export {
+  buildCelEnvironment,
+  celBuiltinFunctions,
+  deriveSignatures,
+  type CelHandlers,
+} from "./cel/environment.js";
 export {
   celFunctionCatalog,
   CEL_FUNCTIONS,
@@ -19,27 +24,53 @@ export {
   INDEX_SEGMENT,
   validateChainAgainstSchema,
 } from "./cel/analyze.js";
-export { walkCelExpressions } from "./cel/walk.js";
+export { auditCalls, explainUnresolved, functionIndex, type CallAudit } from "./cel/diagnose.js";
+export { walkCelExpressions, type CelSurface } from "./cel/walk.js";
 
 export { celEngine } from "./engines/cel.js";
+export {
+  includeBytesEngine,
+  includeTextEngine,
+  normalizeIncludePath,
+  type NormalizedIncludePath,
+} from "./engines/include.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
 export { sqlEngine, isParameterizedSql, type ParameterizedSql } from "./engines/sql.js";
 
 export { TemplatingEngineRegistry } from "./registry.js";
-export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
+export {
+  builtinEngines,
+  createDefaultRegistry,
+  defaultRegistry,
+  producedTypeOf,
+} from "./builtins.js";
 export type {
   AnalyzeEnv,
+  AnalyzeResult,
+  CallSite,
   CompileEnv,
+  DiagnosticFix,
   EngineDiagnostic,
+  EngineFileClaim,
   TemplatingEngine,
 } from "./engine.js";
 
-export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export {
+  CEL_ENGINE,
+  INCLUDE_BYTES_ENGINE,
+  INCLUDE_ENGINE_NAMES,
+  INCLUDE_TEXT_ENGINE,
+  isIncludeSentinel,
+  isRefSentinel,
+  isTaggedSentinel,
+  makeTaggedSentinel,
+  plainChainOf,
+  type TaggedSentinel,
+} from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
 export {
   MANIFEST_SCHEMA_URI,
   ManifestRootSchema,
   ResourceRefSchema,
-  normalizeRefSlots,
 } from "./manifest-schemas.js";