@telorun/analyzer 0.7.0 → 0.8.0

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAoY/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA2TvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAKxF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAiB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8W/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAmUvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAKxF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAiB5F"}

package/dist/analyzer.js

@@ -1,3 +1,4 @@
+import { defaultRegistry, walkCelExpressions } from "@telorun/templating";
 import { AliasResolver } from "./alias-resolver.js";
 import { buildCelEnvironment, buildTypedCelEnvironment, } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
@@ -8,11 +9,10 @@ import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
-import { extractAccessChains, getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, validateChainAgainstSchema, } from "./validate-cel-context.js";
+import { getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
-const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 const SELF_PREFIX = "Self.";
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
@@ -36,21 +36,6 @@ function lookupDefinitionTypeField(invokedKind, fieldName, defs, aliases, allMan
     const value = def[fieldName];
     return resolveTypeFieldToSchema(value, allManifests);
 }
-function walkCelExpressions(value, path, cb) {
-    if (typeof value === "string") {
-        for (const m of value.matchAll(TEMPLATE_REGEX)) {
-            cb(m[1].trim(), path);
-        }
-    }
-    else if (Array.isArray(value)) {
-        value.forEach((v, i) => walkCelExpressions(v, `${path}[${i}]`, cb));
-    }
-    else if (value !== null && typeof value === "object") {
-        for (const [k, v] of Object.entries(value)) {
-            walkCelExpressions(v, path ? `${path}.${k}` : k, cb);
-        }
-    }
-}
 const SOURCE = "telo-analyzer";
 /**
  * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
@@ -512,27 +497,14 @@ export class StaticAnalyzer {
             const stepContextSchema = mDefinition?.schema
                 ? buildStepContextSchema(m, mDefinition.schema, allManifests, defs, aliases)
                 : undefined;
-            walkCelExpressions(m, "", (expr, path) => {
-                let parsed;
-                try {
-                    parsed = this.celEnv.parse(expr);
-                }
-                catch (e) {
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "CEL_SYNTAX_ERROR",
-                        source: SOURCE,
-                        message: `CEL syntax error at ${path}: ${e instanceof Error ? e.message : String(e)}`,
-                        data: { resource, filePath, path },
-                    });
-                    return;
-                }
-                const accessChains = extractAccessChains(parsed.ast);
+            walkCelExpressions(m, "", (expr, path, engineName) => {
+                // Resolve the effective context for this expression's path. The
+                // engine receives a single closed schema and validates member-access
+                // chains against it; per-path resolution (step context, x-telo-context,
+                // kernel-globals merge) stays on the analyzer side because it depends
+                // on analyzer-internal state (definitions, aliases).
                 const contexts = mDefinition?.schema ? extractContextsFromSchema(mDefinition.schema) : [];
                 const invocationContext = m.metadata?.xTeloInvocationContext;
-                // If no static context but we have step context, inject it
-                if (contexts.length === 0 && !invocationContext && !stepContextSchema)
-                    return;
                 let matchedContext;
                 let matchedScope;
                 for (const ctx of contexts) {
@@ -544,7 +516,6 @@ export class StaticAnalyzer {
                 }
                 if (!matchedContext)
                     matchedContext = invocationContext;
-                // Merge step context into the effective context
                 if (stepContextSchema) {
                     const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
                     matchedContext = {
@@ -555,24 +526,49 @@ export class StaticAnalyzer {
                         },
                     };
                 }
-                if (!matchedContext)
+                let effectiveContext = null;
+                if (matchedContext) {
+                    const manifestItem = matchedScope
+                        ? getManifestItem(path, matchedScope, m)
+                        : m;
+                    const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, allManifests);
+                    effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+                }
+                const engine = defaultRegistry().get(engineName);
+                if (!engine)
                     return;
-                const manifestItem = matchedScope
-                    ? getManifestItem(path, matchedScope, m)
-                    : m;
-                const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, allManifests);
-                const effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
-                for (const chain of accessChains) {
-                    const err = validateChainAgainstSchema(chain, effectiveContext);
-                    if (!err)
-                        continue;
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "CEL_UNKNOWN_FIELD",
-                        source: SOURCE,
-                        message: `${m.kind}/${resource.name}: CEL at '${path}': ${err}`,
-                        data: { resource, filePath, path },
-                    });
+                const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
+                for (const f of findings) {
+                    if (f.code === "CEL_SYNTAX_ERROR") {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "CEL_SYNTAX_ERROR",
+                            source: SOURCE,
+                            message: `CEL syntax error at ${path}: ${f.message}`,
+                            data: { resource, filePath, path },
+                        });
+                    }
+                    else if (f.code === "CEL_UNKNOWN_FIELD") {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "CEL_UNKNOWN_FIELD",
+                            source: SOURCE,
+                            message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+                            data: { resource, filePath, path },
+                        });
+                    }
+                    else {
+                        // Unknown code from a future engine — pass the message through,
+                        // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
+                        // filters can still bucket it.
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: f.code ?? "ENGINE_DIAGNOSTIC",
+                            source: SOURCE,
+                            message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+                            data: { resource, filePath, path },
+                        });
+                    }
                 }
             });
         }

package/dist/cel-environment.d.ts

@@ -1,23 +1,7 @@
 import { Environment } from "@marcbachmann/cel-js";
-import { type ResourceManifest } from "@telorun/sdk";
-export interface CelHandlers {
-    sha256: (s: string) => string;
-    json: (value: unknown) => string;
-}
-/** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
- *  same function signatures (so `env.check()` succeeds for type-inference) — the
- *  handlers govern what the function does when called at runtime. Analyzer-only
- *  callers can omit handlers; runtime callers (kernel) must supply real ones.
- *
- *  Also registers the `Stream` object type, backed by the `Stream` class from
- *  `@telorun/sdk`. CEL's type-checker rejects values whose constructor isn't
- *  Object/Map/Array/Set/registered; producers that need to expose an
- *  `AsyncIterable` through a stream-typed property must wrap the iterable in
- *  `new Stream(...)` so its constructor is the registered class. The type has
- *  no fields, so terminal access (passing the value through CEL) succeeds but
- *  member access raises a CEL error at runtime — matching the analyzer's
- *  static check on `x-telo-stream`-marked properties. */
-export declare function buildCelEnvironment(handlers?: CelHandlers): Environment;
+import type { ResourceManifest } from "@telorun/sdk";
+export { buildCelEnvironment } from "@telorun/templating";
+export type { CelHandlers } from "@telorun/templating";
 /** Clone `baseEnv` and register typed variable declarations so that
  *  `env.check(expr)` can infer return types for expressions referencing known variables.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAU,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAcD;;;;;;;;;;;;yDAYyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,WAA2B,GAAG,WAAW,CAgBtF;AAED;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAC9C,WAAW,CAyCb"}
+{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAC9C,WAAW,CAyCb"}

package/dist/cel-environment.js

@@ -1,44 +1,5 @@
-import { Environment } from "@marcbachmann/cel-js";
-import { Stream } from "@telorun/sdk";
 import { jsonSchemaToCelType } from "./schema-compat.js";
-const stub = (name) => () => {
-    throw new Error(`${name}() is not available in this environment. ` +
-        `Construct StaticAnalyzer or Loader with celHandlers to enable it.`);
-};
-const STUB_HANDLERS = {
-    sha256: stub("sha256"),
-    json: stub("json"),
-};
-/** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
- *  same function signatures (so `env.check()` succeeds for type-inference) — the
- *  handlers govern what the function does when called at runtime. Analyzer-only
- *  callers can omit handlers; runtime callers (kernel) must supply real ones.
- *
- *  Also registers the `Stream` object type, backed by the `Stream` class from
- *  `@telorun/sdk`. CEL's type-checker rejects values whose constructor isn't
- *  Object/Map/Array/Set/registered; producers that need to expose an
- *  `AsyncIterable` through a stream-typed property must wrap the iterable in
- *  `new Stream(...)` so its constructor is the registered class. The type has
- *  no fields, so terminal access (passing the value through CEL) succeeds but
- *  member access raises a CEL error at runtime — matching the analyzer's
- *  static check on `x-telo-stream`-marked properties. */
-export function buildCelEnvironment(handlers = STUB_HANDLERS) {
-    return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
-        .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
-        .registerFunction("keys(map): list", (map) => {
-        if (map instanceof Map)
-            return [...map.keys()];
-        return Object.keys(map);
-    })
-        .registerFunction("values(map): list", (map) => {
-        if (map instanceof Map)
-            return [...map.values()];
-        return Object.values(map);
-    })
-        .registerFunction("sha256(string): string", (s) => handlers.sha256(s))
-        .registerFunction("json(dyn): string", (value) => handlers.json(value))
-        .registerType("Stream", Stream);
-}
+export { buildCelEnvironment } from "@telorun/templating";
 /** Clone `baseEnv` and register typed variable declarations so that
  *  `env.check(expr)` can infer return types for expressions referencing known variables.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IAEJ,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA+HnE"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IAEJ,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA+HnE"}

package/dist/manifest-loader.js

@@ -1,4 +1,5 @@
 import { isCompiledValue } from "@telorun/sdk";
+import { defaultCustomTags } from "@telorun/templating";
 import { isMap, isPair, isScalar, isSeq, parseAllDocuments } from "yaml";
 import { HttpSource } from "./sources/http-source.js";
 import { RegistrySource } from "./sources/registry-source.js";
@@ -53,7 +54,7 @@ export class Loader {
         if (cached && cached.text === text) {
             return cloneManifestArray(cached.manifests);
         }
-        const parsedDocuments = parseAllDocuments(text);
+        const parsedDocuments = parseAllDocuments(text, { customTags: defaultCustomTags() });
         const rawDocs = parsedDocuments.map((d) => d.toJSON());
         const offsets = documentLineOffsets(text);
         const lineOffsets = buildLineOffsets(text);
@@ -154,7 +155,7 @@ export class Loader {
     }
     async loadPartialFile(url, ownerModuleName, options) {
         const { text, source } = await this.pick(url).read(url);
-        const parsedDocuments = parseAllDocuments(text);
+        const parsedDocuments = parseAllDocuments(text, { customTags: defaultCustomTags() });
         const rawDocs = parsedDocuments.map((d) => d.toJSON());
         const offsets = documentLineOffsets(text);
         const lineOffsets = buildLineOffsets(text);

package/dist/precompile.d.ts

@@ -1,10 +1,16 @@
 import type { Environment } from "@marcbachmann/cel-js";
 /**
- * Walks a raw YAML document and replaces all "${{ expr }}" strings with
- * CompiledValue wrappers. Throws on CEL syntax errors.
- * Intended to be called once per document at load time.
- * Telo.Definition documents are returned unchanged — their schema fields
- * are static metadata and must not be treated as CEL templates.
+ * Walks a raw YAML document and replaces all `${{ expr }}` strings (and
+ * `!cel`-tagged sentinels) with CompiledValue wrappers. Throws on CEL syntax
+ * errors. Intended to be called once per document at load time.
+ *
+ * Note on Telo.Definition / Telo.Abstract: the walker traverses these too.
+ * Their `schema` fields are JSON Schema metadata and don't typically contain
+ * `${{ }}` text, so compile is a no-op there. Their `template` fields, on
+ * the other hand, *do* carry CEL — Definition-driven templates are expanded
+ * by the kernel and rely on the precompiled tree. If a description or
+ * example string inside a schema happens to contain `${{ }}`, it will be
+ * interpreted as CEL; tag it `!literal` to opt out.
  */
 export declare function precompileDoc(doc: unknown, env: Environment): unknown;
 //# sourceMappingURL=precompile.d.ts.map

package/dist/precompile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAarE"}
+{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAmCrE"}

package/dist/precompile.js

@@ -1,13 +1,41 @@
-const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
-const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+import { isCompiledValue } from "@telorun/sdk";
+import { compileString, defaultRegistry, isTaggedSentinel } from "@telorun/templating";
 /**
- * Walks a raw YAML document and replaces all "${{ expr }}" strings with
- * CompiledValue wrappers. Throws on CEL syntax errors.
- * Intended to be called once per document at load time.
- * Telo.Definition documents are returned unchanged — their schema fields
- * are static metadata and must not be treated as CEL templates.
+ * Walks a raw YAML document and replaces all `${{ expr }}` strings (and
+ * `!cel`-tagged sentinels) with CompiledValue wrappers. Throws on CEL syntax
+ * errors. Intended to be called once per document at load time.
+ *
+ * Note on Telo.Definition / Telo.Abstract: the walker traverses these too.
+ * Their `schema` fields are JSON Schema metadata and don't typically contain
+ * `${{ }}` text, so compile is a no-op there. Their `template` fields, on
+ * the other hand, *do* carry CEL — Definition-driven templates are expanded
+ * by the kernel and rely on the precompiled tree. If a description or
+ * example string inside a schema happens to contain `${{ }}`, it will be
+ * interpreted as CEL; tag it `!literal` to opt out.
  */
 export function precompileDoc(doc, env) {
+    // Tagged sentinel: dispatch to the engine. The result is decorated with
+    // `__tagged` + `engine` + `source` when it's a CompiledValue so the
+    // analyzer's diagnostic walk can identify it on compiled trees too;
+    // engines returning plain values (e.g. `literal` → a string) pass through
+    // verbatim — the runtime contract is "any scalar value is fine."
+    if (isTaggedSentinel(doc)) {
+        const engine = defaultRegistry().get(doc.engine);
+        if (!engine) {
+            throw new Error(`Unknown templating engine: !${doc.engine}`);
+        }
+        const compiled = engine.compile(doc.source, { celEnv: env });
+        if (isCompiledValue(compiled)) {
+            return {
+                __tagged: true,
+                __compiled: true,
+                engine: doc.engine,
+                source: doc.source,
+                call: compiled.call.bind(compiled),
+            };
+        }
+        return compiled;
+    }
     if (typeof doc === "string")
         return compileString(doc, env);
     if (Array.isArray(doc))
@@ -23,31 +51,3 @@ export function precompileDoc(doc, env) {
     }
     return doc;
 }
-function compileString(s, env) {
-    if (!s.includes("${{"))
-        return s;
-    const exact = s.match(EXACT_TEMPLATE_REGEX);
-    if (exact) {
-        const expr = exact[1].trim();
-        const fn = env.parse(expr);
-        return { __compiled: true, source: expr, call: (ctx) => fn(ctx) };
-    }
-    // Interpolated template — collect literal parts + compiled sub-expressions
-    const parts = [];
-    let last = 0;
-    for (const m of s.matchAll(TEMPLATE_REGEX)) {
-        if (m.index > last)
-            parts.push(s.slice(last, m.index));
-        const expr = m[1].trim();
-        const fn = env.parse(expr);
-        parts.push({ __compiled: true, source: expr, call: (ctx) => fn(ctx) });
-        last = m.index + m[0].length;
-    }
-    if (last < s.length)
-        parts.push(s.slice(last));
-    return {
-        __compiled: true,
-        source: s,
-        call: (ctx) => parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
-    };
-}

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;0FAC0F;AAC1F,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAMpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAwBT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;0FAC0F;AAC1F,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAMpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CA2BT"}

package/dist/schema-compat.js

@@ -1,5 +1,6 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
+import { isTaggedSentinel } from "@telorun/templating";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
  *  Called once for the module-level instance and once per DefinitionRegistry instance. */
@@ -269,6 +270,9 @@ export function substituteCelFields(data, schema, rootSchema) {
     if (typeof data === "string" && CEL_PURE_RE.test(data)) {
         return celPlaceholderForSchema(resolved);
     }
+    if (isTaggedSentinel(data)) {
+        return celPlaceholderForSchema(resolved);
+    }
     if (Array.isArray(data)) {
         const itemSchema = resolveRef((resolved.items ?? {}), root);
         return data.map((item) => substituteCelFields(item, itemSchema, root));

package/dist/validate-cel-context.d.ts

@@ -1,4 +1,4 @@
-import type { ASTNode } from "@marcbachmann/cel-js";
+export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
 /**
  * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
  * - String: look up the named type in allManifests (Type.JsonSchema resources)
@@ -6,21 +6,6 @@ import type { ASTNode } from "@marcbachmann/cel-js";
  * - Object with `type` or `properties`: raw JSON Schema, return as-is
  */
 export declare function resolveTypeFieldToSchema(value: unknown, allManifests: Record<string, any>[]): Record<string, any> | undefined;
-/**
- * Extract all member-access chains from a CEL AST.
- * Returns arrays like ["request", "query", "name"] for `request.query.name`.
- * Chains that start with a call or non-identifier root are ignored.
- * Bound variables in comprehension macros (filter, map, exists, all, exists_one) are excluded.
- */
-export declare function extractAccessChains(node: ASTNode): string[][];
-/**
- * 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.
- * 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;
 /**
  * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
  * falls within the scope of a context (e.g. "$.routes[*].inputs").

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AAsFD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CAiCf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqDrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqDrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}

package/dist/validate-cel-context.js

@@ -1,3 +1,4 @@
+export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
 /**
  * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
  * - String: look up the named type in allManifests (Type.JsonSchema resources)
@@ -29,139 +30,6 @@ export function resolveTypeFieldToSchema(value, allManifests) {
     }
     return undefined;
 }
-/**
- * Extract all member-access chains from a CEL AST.
- * Returns arrays like ["request", "query", "name"] for `request.query.name`.
- * Chains that start with a call or non-identifier root are ignored.
- * Bound variables in comprehension macros (filter, map, exists, all, exists_one) are excluded.
- */
-export function extractAccessChains(node) {
-    const chains = [];
-    visitNode(node, chains, new Set());
-    return chains;
-}
-// CEL comprehension macros that bind a variable: list.filter(x, ...), list.map(x, ...), etc.
-const COMPREHENSION_METHODS = new Set(["filter", "map", "exists", "all", "exists_one"]);
-function visitNode(node, chains, boundVars) {
-    const chain = extractChain(node, boundVars);
-    if (chain !== null) {
-        chains.push(chain);
-        return; // don't recurse into parts of an already-collected chain
-    }
-    // Comprehension macros bind a variable in their body — handle them specially
-    // AST shape: { op: "rcall", args: [methodName, receiver, [boundVarId, body, ...]] }
-    if (node.op === "rcall" &&
-        Array.isArray(node.args) &&
-        typeof node.args[0] === "string" &&
-        COMPREHENSION_METHODS.has(node.args[0])) {
-        const receiver = node.args[1];
-        const comprehensionArgs = node.args[2];
-        if (isASTNode(receiver))
-            visitNode(receiver, chains, boundVars);
-        if (Array.isArray(comprehensionArgs) &&
-            comprehensionArgs.length >= 2 &&
-            isASTNode(comprehensionArgs[0]) &&
-            comprehensionArgs[0].op === "id") {
-            const newBoundVars = new Set(boundVars);
-            newBoundVars.add(comprehensionArgs[0].args);
-            for (let i = 1; i < comprehensionArgs.length; i++) {
-                const arg = comprehensionArgs[i];
-                if (isASTNode(arg))
-                    visitNode(arg, chains, newBoundVars);
-            }
-        }
-        return;
-    }
-    const args = node.args;
-    if (Array.isArray(args)) {
-        for (const arg of args) {
-            if (isASTNode(arg)) {
-                visitNode(arg, chains, boundVars);
-            }
-            else if (Array.isArray(arg)) {
-                for (const item of arg) {
-                    if (isASTNode(item))
-                        visitNode(item, chains, boundVars);
-                }
-            }
-        }
-    }
-}
-function isASTNode(v) {
-    return v !== null && typeof v === "object" && "op" in v;
-}
-// Sentinel used in extracted chains to represent an `[index]` access. The
-// validator treats it like any other deeper segment, so a chain that reaches
-// past an `x-telo-stream`-marked property via `[N]` is rejected the same way
-// `.field` access is. The actual index expression is opaque to the chain
-// validator (it only checks property names against the schema).
-const INDEX_SEGMENT = "[*]";
-/** Returns the member-access chain for a node if it is purely an id, ".", or
- *  "[]" chain; else null. Bracket index access is captured as `INDEX_SEGMENT`
- *  so it counts as a chain extension for the stream-property opacity rule. */
-function extractChain(node, boundVars) {
-    if (node.op === "id") {
-        const name = node.args;
-        if (boundVars.has(name))
-            return null; // bound by a comprehension macro, not a free access
-        return [name];
-    }
-    if (node.op === ".") {
-        const [obj, field] = node.args;
-        const parent = extractChain(obj, boundVars);
-        if (parent !== null)
-            return [...parent, field];
-    }
-    if (node.op === "[]") {
-        const [obj] = node.args;
-        const parent = extractChain(obj, boundVars);
-        if (parent !== null)
-            return [...parent, INDEX_SEGMENT];
-    }
-    return null;
-}
-/**
- * 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.
- * Returns null when the chain is valid or the schema is too open to judge.
- */
-export function validateChainAgainstSchema(chain, schema) {
-    let current = schema;
-    for (let i = 0; i < chain.length; i++) {
-        const key = chain[i];
-        if (!current || typeof current !== "object")
-            return null;
-        const props = current.properties;
-        if (!props)
-            return null;
-        if (key in props) {
-            const propSchema = props[key];
-            // Stream-typed properties are opaque: pass through by reference, no
-            // member access inside. Reaching `result.output` is fine; reaching
-            // `result.output.text` is a wiring mistake — the consumer either iterates
-            // the stream in a JS.Script step or pipes it through an Encoder.
-            if (propSchema &&
-                typeof propSchema === "object" &&
-                propSchema["x-telo-stream"] === true &&
-                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)`;
-            }
-            // Known property — drill into it even if additionalProperties is true
-            current = propSchema;
-            continue;
-        }
-        // Unknown property — only flag if schema is closed
-        if (current.additionalProperties === true)
-            return null;
-        const path = chain.slice(0, i + 1).join(".");
-        const available = Object.keys(props).join(", ");
-        return `'${path}' is not defined (available: ${available})`;
-    }
-    return null;
-}
 /**
  * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
  * falls within the scope of a context (e.g. "$.routes[*].inputs").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,13 +41,17 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.7.0"
+    "@telorun/sdk": "0.7.0",
+    "@telorun/templating": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/analyzer.ts

@@ -1,5 +1,6 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
+import { defaultRegistry, walkCelExpressions } from "@telorun/templating";
 import { AliasResolver } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
@@ -21,19 +22,15 @@ import {
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
-  extractAccessChains,
   getManifestItem,
   pathMatchesScope,
   resolveContextAnnotations,
   resolveTypeFieldToSchema,
-  validateChainAgainstSchema,
 } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
-const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
-
 const SELF_PREFIX = "Self.";
 
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
@@ -69,24 +66,6 @@ function lookupDefinitionTypeField(
   return resolveTypeFieldToSchema(value, allManifests);
 }
 
-function walkCelExpressions(
-  value: unknown,
-  path: string,
-  cb: (expr: string, path: string) => void,
-): void {
-  if (typeof value === "string") {
-    for (const m of value.matchAll(TEMPLATE_REGEX)) {
-      cb(m[1].trim(), path);
-    }
-  } else if (Array.isArray(value)) {
-    value.forEach((v, i) => walkCelExpressions(v, `${path}[${i}]`, cb));
-  } else if (value !== null && typeof value === "object") {
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      walkCelExpressions(v, path ? `${path}.${k}` : k, cb);
-    }
-  }
-}
-
 const SOURCE = "telo-analyzer";
 
 /**
@@ -651,31 +630,17 @@ export class StaticAnalyzer {
           )
         : undefined;
 
-      walkCelExpressions(m, "", (expr, path) => {
-        let parsed: ReturnType<typeof this.celEnv.parse> | undefined;
-        try {
-          parsed = this.celEnv.parse(expr);
-        } catch (e) {
-          diagnostics.push({
-            severity: DiagnosticSeverity.Error,
-            code: "CEL_SYNTAX_ERROR",
-            source: SOURCE,
-            message: `CEL syntax error at ${path}: ${e instanceof Error ? e.message : String(e)}`,
-            data: { resource, filePath, path },
-          });
-          return;
-        }
-
-        const accessChains = extractAccessChains(parsed.ast);
-
+      walkCelExpressions(m, "", (expr, path, engineName) => {
+        // Resolve the effective context for this expression's path. The
+        // engine receives a single closed schema and validates member-access
+        // chains against it; per-path resolution (step context, x-telo-context,
+        // kernel-globals merge) stays on the analyzer side because it depends
+        // on analyzer-internal state (definitions, aliases).
         const contexts = mDefinition?.schema ? extractContextsFromSchema(mDefinition.schema) : [];
         const invocationContext = (m.metadata as any)?.xTeloInvocationContext as
           | Record<string, any>
           | undefined;
 
-        // If no static context but we have step context, inject it
-        if (contexts.length === 0 && !invocationContext && !stepContextSchema) return;
-
         let matchedContext: Record<string, any> | undefined;
         let matchedScope: string | undefined;
         for (const ctx of contexts) {
@@ -687,7 +652,6 @@ export class StaticAnalyzer {
         }
         if (!matchedContext) matchedContext = invocationContext;
 
-        // Merge step context into the effective context
         if (stepContextSchema) {
           const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
           matchedContext = {
@@ -699,28 +663,51 @@ export class StaticAnalyzer {
           };
         }
 
-        if (!matchedContext) return;
-
-        const manifestItem = matchedScope
-          ? getManifestItem(path, matchedScope, m as Record<string, any>)
-          : (m as Record<string, any>);
-        const resolvedContext = resolveContextAnnotations(
-          matchedContext,
-          manifestItem,
-          allManifests as Record<string, any>[],
-        );
-        const effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
-
-        for (const chain of accessChains) {
-          const err = validateChainAgainstSchema(chain, effectiveContext);
-          if (!err) continue;
-          diagnostics.push({
-            severity: DiagnosticSeverity.Error,
-            code: "CEL_UNKNOWN_FIELD",
-            source: SOURCE,
-            message: `${m.kind}/${resource.name}: CEL at '${path}': ${err}`,
-            data: { resource, filePath, path },
-          });
+        let effectiveContext: Record<string, any> | null = null;
+        if (matchedContext) {
+          const manifestItem = matchedScope
+            ? getManifestItem(path, matchedScope, m as Record<string, any>)
+            : (m as Record<string, any>);
+          const resolvedContext = resolveContextAnnotations(
+            matchedContext,
+            manifestItem,
+            allManifests as Record<string, any>[],
+          );
+          effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+        }
+
+        const engine = defaultRegistry().get(engineName);
+        if (!engine) return;
+        const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
+        for (const f of findings) {
+          if (f.code === "CEL_SYNTAX_ERROR") {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "CEL_SYNTAX_ERROR",
+              source: SOURCE,
+              message: `CEL syntax error at ${path}: ${f.message}`,
+              data: { resource, filePath, path },
+            });
+          } else if (f.code === "CEL_UNKNOWN_FIELD") {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "CEL_UNKNOWN_FIELD",
+              source: SOURCE,
+              message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+              data: { resource, filePath, path },
+            });
+          } else {
+            // Unknown code from a future engine — pass the message through,
+            // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
+            // filters can still bucket it.
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: f.code ?? "ENGINE_DIAGNOSTIC",
+              source: SOURCE,
+              message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+              data: { resource, filePath, path },
+            });
+          }
         }
       });
     }

package/src/cel-environment.ts

@@ -1,54 +1,9 @@
 import { Environment } from "@marcbachmann/cel-js";
-import { Stream, type ResourceManifest } from "@telorun/sdk";
+import type { ResourceManifest } from "@telorun/sdk";
 import { jsonSchemaToCelType } from "./schema-compat.js";
 
-export interface CelHandlers {
-  sha256: (s: string) => string;
-  json: (value: unknown) => string;
-}
-
-const stub = (name: string) => () => {
-  throw new Error(
-    `${name}() is not available in this environment. ` +
-      `Construct StaticAnalyzer or Loader with celHandlers to enable it.`,
-  );
-};
-
-const STUB_HANDLERS: CelHandlers = {
-  sha256: stub("sha256"),
-  json: stub("json"),
-};
-
-/** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
- *  same function signatures (so `env.check()` succeeds for type-inference) — the
- *  handlers govern what the function does when called at runtime. Analyzer-only
- *  callers can omit handlers; runtime callers (kernel) must supply real ones.
- *
- *  Also registers the `Stream` object type, backed by the `Stream` class from
- *  `@telorun/sdk`. CEL's type-checker rejects values whose constructor isn't
- *  Object/Map/Array/Set/registered; producers that need to expose an
- *  `AsyncIterable` through a stream-typed property must wrap the iterable in
- *  `new Stream(...)` so its constructor is the registered class. The type has
- *  no fields, so terminal access (passing the value through CEL) succeeds but
- *  member access raises a CEL error at runtime — matching the analyzer's
- *  static check on `x-telo-stream`-marked properties. */
-export function buildCelEnvironment(handlers: CelHandlers = STUB_HANDLERS): Environment {
-  return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
-    .registerFunction("join(list, string): string", (list: unknown[], sep: string) =>
-      list.map(String).join(sep),
-    )
-    .registerFunction("keys(map): list", (map: unknown) => {
-      if (map instanceof Map) return [...map.keys()];
-      return Object.keys(map as Record<string, unknown>);
-    })
-    .registerFunction("values(map): list", (map: unknown) => {
-      if (map instanceof Map) return [...map.values()];
-      return Object.values(map as Record<string, unknown>);
-    })
-    .registerFunction("sha256(string): string", (s: string) => handlers.sha256(s))
-    .registerFunction("json(dyn): string", (value: unknown) => handlers.json(value))
-    .registerType("Stream", Stream as unknown as new (...args: unknown[]) => unknown);
-}
+export { buildCelEnvironment } from "@telorun/templating";
+export type { CelHandlers } from "@telorun/templating";
 
 /** Clone `baseEnv` and register typed variable declarations so that
  *  `env.check(expr)` can infer return types for expressions referencing known variables.

package/src/manifest-loader.ts

@@ -1,5 +1,6 @@
 import type { Environment } from "@marcbachmann/cel-js";
 import { isCompiledValue, type ResourceManifest } from "@telorun/sdk";
+import { defaultCustomTags } from "@telorun/templating";
 import { isMap, isPair, isScalar, isSeq, parseAllDocuments, type Document } from "yaml";
 import { HttpSource } from "./sources/http-source.js";
 import { RegistrySource } from "./sources/registry-source.js";
@@ -74,7 +75,7 @@ export class Loader {
       return cloneManifestArray(cached.manifests);
     }
 
-    const parsedDocuments = parseAllDocuments(text);
+    const parsedDocuments = parseAllDocuments(text, { customTags: defaultCustomTags() });
     const rawDocs = parsedDocuments.map((d) => d.toJSON());
     const offsets = documentLineOffsets(text);
     const lineOffsets = buildLineOffsets(text);
@@ -194,7 +195,7 @@ export class Loader {
   ): Promise<ResourceManifest[]> {
     const { text, source } = await this.pick(url).read(url);
 
-    const parsedDocuments = parseAllDocuments(text);
+    const parsedDocuments = parseAllDocuments(text, { customTags: defaultCustomTags() });
     const rawDocs = parsedDocuments.map((d) => d.toJSON());
     const offsets = documentLineOffsets(text);
     const lineOffsets = buildLineOffsets(text);

package/src/precompile.ts

@@ -1,17 +1,43 @@
-import type { CompiledValue } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-
-const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
-const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+import { isCompiledValue } from "@telorun/sdk";
+import { compileString, defaultRegistry, isTaggedSentinel } from "@telorun/templating";
 
 /**
- * Walks a raw YAML document and replaces all "${{ expr }}" strings with
- * CompiledValue wrappers. Throws on CEL syntax errors.
- * Intended to be called once per document at load time.
- * Telo.Definition documents are returned unchanged — their schema fields
- * are static metadata and must not be treated as CEL templates.
+ * Walks a raw YAML document and replaces all `${{ expr }}` strings (and
+ * `!cel`-tagged sentinels) with CompiledValue wrappers. Throws on CEL syntax
+ * errors. Intended to be called once per document at load time.
+ *
+ * Note on Telo.Definition / Telo.Abstract: the walker traverses these too.
+ * Their `schema` fields are JSON Schema metadata and don't typically contain
+ * `${{ }}` text, so compile is a no-op there. Their `template` fields, on
+ * the other hand, *do* carry CEL — Definition-driven templates are expanded
+ * by the kernel and rely on the precompiled tree. If a description or
+ * example string inside a schema happens to contain `${{ }}`, it will be
+ * interpreted as CEL; tag it `!literal` to opt out.
  */
 export function precompileDoc(doc: unknown, env: Environment): unknown {
+  // Tagged sentinel: dispatch to the engine. The result is decorated with
+  // `__tagged` + `engine` + `source` when it's a CompiledValue so the
+  // analyzer's diagnostic walk can identify it on compiled trees too;
+  // engines returning plain values (e.g. `literal` → a string) pass through
+  // verbatim — the runtime contract is "any scalar value is fine."
+  if (isTaggedSentinel(doc)) {
+    const engine = defaultRegistry().get(doc.engine);
+    if (!engine) {
+      throw new Error(`Unknown templating engine: !${doc.engine}`);
+    }
+    const compiled = engine.compile(doc.source, { celEnv: env });
+    if (isCompiledValue(compiled)) {
+      return {
+        __tagged: true,
+        __compiled: true,
+        engine: doc.engine,
+        source: doc.source,
+        call: compiled.call.bind(compiled),
+      };
+    }
+    return compiled;
+  }
   if (typeof doc === "string") return compileString(doc, env);
   if (Array.isArray(doc)) return doc.map((item) => precompileDoc(item, env));
   // Only recurse into plain objects. Class instances (ResourceInstance, ScopeHandle, etc.)
@@ -25,33 +51,3 @@ export function precompileDoc(doc: unknown, env: Environment): unknown {
   }
   return doc;
 }
-
-function compileString(s: string, env: Environment): unknown {
-  if (!s.includes("${{")) return s;
-
-  const exact = s.match(EXACT_TEMPLATE_REGEX);
-  if (exact) {
-    const expr = exact[1].trim();
-    const fn = env.parse(expr);
-    return { __compiled: true, source: expr, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue;
-  }
-
-  // Interpolated template — collect literal parts + compiled sub-expressions
-  const parts: Array<string | CompiledValue> = [];
-  let last = 0;
-  for (const m of s.matchAll(TEMPLATE_REGEX)) {
-    if (m.index! > last) parts.push(s.slice(last, m.index));
-    const expr = m[1].trim();
-    const fn = env.parse(expr);
-    parts.push({ __compiled: true, source: expr, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue);
-    last = m.index! + m[0].length;
-  }
-  if (last < s.length) parts.push(s.slice(last));
-
-  return {
-    __compiled: true,
-    source: s,
-    call: (ctx: Record<string, unknown>) =>
-      parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
-  } satisfies CompiledValue;
-}

package/src/schema-compat.ts

@@ -1,5 +1,6 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
+import { isTaggedSentinel } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
@@ -300,6 +301,9 @@ export function substituteCelFields(
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     return celPlaceholderForSchema(resolved);
   }
+  if (isTaggedSentinel(data)) {
+    return celPlaceholderForSchema(resolved);
+  }
   if (Array.isArray(data)) {
     const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
     return data.map((item) => substituteCelFields(item, itemSchema, root));

package/src/validate-cel-context.ts

@@ -1,4 +1,4 @@
-import type { ASTNode } from "@marcbachmann/cel-js";
+export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
 
 /**
  * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
@@ -40,147 +40,6 @@ export function resolveTypeFieldToSchema(
   return undefined;
 }
 
-/**
- * Extract all member-access chains from a CEL AST.
- * Returns arrays like ["request", "query", "name"] for `request.query.name`.
- * Chains that start with a call or non-identifier root are ignored.
- * Bound variables in comprehension macros (filter, map, exists, all, exists_one) are excluded.
- */
-export function extractAccessChains(node: ASTNode): string[][] {
-  const chains: string[][] = [];
-  visitNode(node, chains, new Set());
-  return chains;
-}
-
-// CEL comprehension macros that bind a variable: list.filter(x, ...), list.map(x, ...), etc.
-const COMPREHENSION_METHODS = new Set(["filter", "map", "exists", "all", "exists_one"]);
-
-function visitNode(node: ASTNode, chains: string[][], boundVars: Set<string>): void {
-  const chain = extractChain(node, boundVars);
-  if (chain !== null) {
-    chains.push(chain);
-    return; // don't recurse into parts of an already-collected chain
-  }
-
-  // Comprehension macros bind a variable in their body — handle them specially
-  // AST shape: { op: "rcall", args: [methodName, receiver, [boundVarId, body, ...]] }
-  if (
-    node.op === "rcall" &&
-    Array.isArray(node.args) &&
-    typeof node.args[0] === "string" &&
-    COMPREHENSION_METHODS.has(node.args[0])
-  ) {
-    const receiver = node.args[1];
-    const comprehensionArgs = node.args[2];
-    if (isASTNode(receiver)) visitNode(receiver, chains, boundVars);
-    if (
-      Array.isArray(comprehensionArgs) &&
-      comprehensionArgs.length >= 2 &&
-      isASTNode(comprehensionArgs[0]) &&
-      (comprehensionArgs[0] as ASTNode).op === "id"
-    ) {
-      const newBoundVars = new Set(boundVars);
-      newBoundVars.add((comprehensionArgs[0] as ASTNode).args as string);
-      for (let i = 1; i < comprehensionArgs.length; i++) {
-        const arg = comprehensionArgs[i];
-        if (isASTNode(arg)) visitNode(arg as ASTNode, chains, newBoundVars);
-      }
-    }
-    return;
-  }
-
-  const args = node.args;
-  if (Array.isArray(args)) {
-    for (const arg of args) {
-      if (isASTNode(arg)) {
-        visitNode(arg, chains, boundVars);
-      } else if (Array.isArray(arg)) {
-        for (const item of arg) {
-          if (isASTNode(item)) visitNode(item, chains, boundVars);
-        }
-      }
-    }
-  }
-}
-
-function isASTNode(v: unknown): v is ASTNode {
-  return v !== null && typeof v === "object" && "op" in (v as object);
-}
-
-// Sentinel used in extracted chains to represent an `[index]` access. The
-// validator treats it like any other deeper segment, so a chain that reaches
-// past an `x-telo-stream`-marked property via `[N]` is rejected the same way
-// `.field` access is. The actual index expression is opaque to the chain
-// validator (it only checks property names against the schema).
-const INDEX_SEGMENT = "[*]";
-
-/** Returns the member-access chain for a node if it is purely an id, ".", or
- *  "[]" chain; else null. Bracket index access is captured as `INDEX_SEGMENT`
- *  so it counts as a chain extension for the stream-property opacity rule. */
-function extractChain(node: ASTNode, boundVars: Set<string>): string[] | null {
-  if (node.op === "id") {
-    const name = node.args as string;
-    if (boundVars.has(name)) return null; // bound by a comprehension macro, not a free access
-    return [name];
-  }
-  if (node.op === ".") {
-    const [obj, field] = node.args as [ASTNode, string];
-    const parent = extractChain(obj, boundVars);
-    if (parent !== null) return [...parent, field];
-  }
-  if (node.op === "[]") {
-    const [obj] = node.args as [ASTNode, ASTNode];
-    const parent = extractChain(obj, boundVars);
-    if (parent !== null) return [...parent, INDEX_SEGMENT];
-  }
-  return null;
-}
-
-/**
- * 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.
- * Returns null when the chain is valid or the schema is too open to judge.
- */
-export function validateChainAgainstSchema(
-  chain: string[],
-  schema: Record<string, any>,
-): string | null {
-  let current: Record<string, any> = schema;
-  for (let i = 0; i < chain.length; i++) {
-    const key = chain[i]!;
-    if (!current || typeof current !== "object") return null;
-    const props: Record<string, any> | undefined = current.properties;
-    if (!props) return null;
-    if (key in props) {
-      const propSchema = props[key];
-      // Stream-typed properties are opaque: pass through by reference, no
-      // member access inside. Reaching `result.output` is fine; reaching
-      // `result.output.text` is a wiring mistake — the consumer either iterates
-      // the stream in a JS.Script step or pipes it through an Encoder.
-      if (
-        propSchema &&
-        typeof propSchema === "object" &&
-        propSchema["x-telo-stream"] === true &&
-        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)`;
-      }
-      // Known property — drill into it even if additionalProperties is true
-      current = propSchema;
-      continue;
-    }
-    // Unknown property — only flag if schema is closed
-    if (current.additionalProperties === true) return null;
-    const path = chain.slice(0, i + 1).join(".");
-    const available = Object.keys(props).join(", ");
-    return `'${path}' is not defined (available: ${available})`;
-  }
-  return null;
-}
-
 /**
  * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
  * falls within the scope of a context (e.g. "$.routes[*].inputs").