@telorun/templating 0.11.1 → 0.13.0

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

@@ -1 +1 @@
-{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;gCAIgC;AAChC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,gBAAgB,EAAE,CAmCxF;AAED;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBAWvB,CAAC"}
+{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAElG;;;;;;;;;;2BAU2B;AAC3B,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,CAgFnF;AAYD;yCACyC;AACzC,eAAO,MAAM,SAAS,EAAE,gBAWvB,CAAC"}

package/dist/engines/cel.js

@@ -1,10 +1,17 @@
 import { extractAccessChains, findNullableAccessIssues, validateChainAgainstSchema, } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
+import { auditCalls, explainUnresolved } from "../cel/diagnose.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. */
+ *  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, env) {
     const out = [];
     let parsed;
@@ -12,35 +19,86 @@ export function analyzeCelExpression(source, env) {
         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 chains = extractAccessChains(parsed.ast);
-    for (const chain of chains) {
-        const err = validateChainAgainstSchema(chain, env.contextSchema);
-        if (err)
-            out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+    const audit = auditCalls(source, parsed.ast, env.celEnv);
+    let type;
+    let checkError;
+    try {
+        const result = env.celEnv.check(source);
+        if (result.valid)
+            type = result.type;
+        else if (result.error) {
+            checkError = String(result.error.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,
+        };
+    }
+    // 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),
+            });
+        }
     }
-    for (const issue of findNullableAccessIssues(parsed.ast, env.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}'`,
-        });
+    if (env.contextSchema) {
+        const contextSchema = env.contextSchema;
+        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 out;
+    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) => 
+// 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 = {
     name: "cel",
     language: "cel",

package/dist/engines/include.d.ts

@@ -0,0 +1,25 @@
+import type { EngineDiagnostic, TemplatingEngine } from "../engine.js";
+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 declare function normalizeIncludePath(source: string): NormalizedIncludePath;
+/** Embeds a file's contents as a UTF-8 string. */
+export declare const includeTextEngine: TemplatingEngine;
+/** Embeds a file's contents as raw bytes — a `Uint8Array`, the shape every
+ *  `x-telo-binary` slot accepts. */
+export declare const includeBytesEngine: TemplatingEngine;
+//# sourceMappingURL=include.d.ts.map

package/dist/engines/include.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../../src/engines/include.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAaxF,MAAM,WAAW,qBAAqB;IACpC;kEAC8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CA0E1E;AA0CD,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,gBAAqD,CAAC;AAEtF;oCACoC;AACpC,eAAO,MAAM,kBAAkB,EAAE,gBAAsD,CAAC"}

package/dist/engines/include.js

@@ -0,0 +1,132 @@
+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;
+/**
+ * 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) {
+    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 = [];
+    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) {
+    return {
+        name,
+        compile(source) {
+            return makeTaggedSentinel(name, source);
+        },
+        analyze(source) {
+            const { diagnostic } = normalizeIncludePath(source);
+            return { diagnostics: diagnostic ? [diagnostic] : [], calls: [] };
+        },
+        fileClaims(source) {
+            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 = includeEngine(INCLUDE_TEXT_ENGINE);
+/** Embeds a file's contents as raw bytes — a `Uint8Array`, the shape every
+ *  `x-telo-binary` slot accepts. */
+export const includeBytesEngine = includeEngine(INCLUDE_BYTES_ENGINE);

package/dist/engines/literal.js

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

package/dist/engines/ref.js

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

package/dist/engines/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/engines/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAsB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,CAAC;AAErD;;;;;kFAKkF;AAClF,eAAO,MAAM,SAAS,EAAE,gBAqBvB,CAAC"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/engines/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAsB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7F,OAAO,KAAK,EAIV,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,CAAC;AAErD;;;;;kFAKkF;AAClF,eAAO,MAAM,SAAS,EAAE,gBAqCvB,CAAC"}

package/dist/engines/sql.js

@@ -25,14 +25,41 @@ export const sqlEngine = {
     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 = [];
+        const calls = [];
+        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. */
+/** Re-anchor a fix computed against one interpolation onto the full source. */
+function reanchor(source, expr, start, fix) {
+    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) {
-    const exprs = [];
+    const out = [];
     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/dist/index.d.ts

@@ -1,16 +1,18 @@
-export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export { buildCelEnvironment, celBuiltinFunctions, deriveSignatures, type CelHandlers, } from "./cel/environment.js";
 export { celFunctionCatalog, CEL_FUNCTIONS, type CelFunctionInfo, type CelFunctionDoc, type CelFunctionCategory, } from "./cel/catalog.js";
 export { compileExpression, compileString, toParameterized, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
 export { extractAccessChains, findNullableAccessIssues, 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 type { AnalyzeEnv, CompileEnv, EngineDiagnostic, TemplatingEngine, } from "./engine.js";
-export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export type { AnalyzeEnv, AnalyzeResult, CallSite, CompileEnv, DiagnosticFix, EngineDiagnostic, EngineFileClaim, TemplatingEngine, } from "./engine.js";
+export { INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, INCLUDE_TEXT_ENGINE, isIncludeSentinel, isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel, } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
 export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } from "./manifest-schemas.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,14 +1,16 @@
-export { buildCelEnvironment } from "./cel/environment.js";
+export { buildCelEnvironment, celBuiltinFunctions, deriveSignatures, } from "./cel/environment.js";
 export { celFunctionCatalog, CEL_FUNCTIONS, } from "./cel/catalog.js";
 export { compileExpression, compileString, toParameterized, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
 export { extractAccessChains, findNullableAccessIssues, INDEX_SEGMENT, validateChainAgainstSchema, } from "./cel/analyze.js";
+export { auditCalls, explainUnresolved, functionIndex } from "./cel/diagnose.js";
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
+export { includeBytesEngine, includeTextEngine, normalizeIncludePath, } from "./engines/include.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
 export { sqlEngine, isParameterizedSql } from "./engines/sql.js";
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
-export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";
+export { INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, INCLUDE_TEXT_ENGINE, isIncludeSentinel, isRefSentinel, isTaggedSentinel, makeTaggedSentinel, } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
 export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } from "./manifest-schemas.js";

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

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

package/dist/manifest-schemas.js

@@ -113,7 +113,12 @@ export function normalizeRefSlots(schema) {
     const out = { ...node };
     // Reference slot with a stale scalar `type` (legacy string-ref encoding):
     // drop the constraint so the resolved reference object / sentinel validates.
-    if (typeof node[REF_ANNOTATION] === "string" &&
+    //
+    // A presence test, not a shape test — deliberately, since `templating` sits
+    // BELOW the analyzer in the dependency order and cannot reach the shared
+    // `readRefSlot` accessor. Presence is the only thing this rule needs, and it
+    // is stable across every annotation shape.
+    if (node[REF_ANNOTATION] !== undefined &&
         typeof node.type === "string" &&
         LEGACY_REF_SCALAR_TYPES.has(node.type)) {
         delete out.type;

package/dist/sentinel.d.ts

@@ -19,4 +19,23 @@ export declare function makeTaggedSentinel(engine: string, source: string): Tagg
 export declare function isRefSentinel(v: unknown): v is TaggedSentinel & {
     engine: "ref";
 };
+/** Engine names of the two file-embedding tags. Named here beside the other
+ *  sentinel predicates so the kernel's resolution pass and the engines
+ *  themselves agree on one spelling. */
+export declare const INCLUDE_TEXT_ENGINE = "include-text";
+export declare const INCLUDE_BYTES_ENGINE = "include-bytes";
+/** Both file-embedding tag names, for a consumer holding an engine NAME rather
+ *  than a value (the analyzer's expression walk reports names). */
+export declare const INCLUDE_ENGINE_NAMES: ReadonlySet<string>;
+/** True when `v` is an `!include-text` / `!include-bytes` sentinel — a file
+ *  embed marked at parse time and still unresolved.
+ *
+ *  The kernel's creation-time resolution keys off this the way Phase-5
+ *  injection keys off {@link isRefSentinel}. Both tags survive precompile as
+ *  markers rather than collapsing to a value, because the read is deferred: a
+ *  manifest load must not pull payload layers, and the analyzer that types the
+ *  slot cannot open files at all. */
+export declare function isIncludeSentinel(v: unknown): v is TaggedSentinel & {
+    engine: typeof INCLUDE_TEXT_ENGINE | typeof INCLUDE_BYTES_ENGINE;
+};
 //# sourceMappingURL=sentinel.d.ts.map

package/dist/sentinel.d.ts.map

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

package/dist/sentinel.js

@@ -16,3 +16,25 @@ export function makeTaggedSentinel(engine, source) {
 export function isRefSentinel(v) {
     return isTaggedSentinel(v) && v.engine === "ref";
 }
+/** Engine names of the two file-embedding tags. Named here beside the other
+ *  sentinel predicates so the kernel's resolution pass and the engines
+ *  themselves agree on one spelling. */
+export const INCLUDE_TEXT_ENGINE = "include-text";
+export const INCLUDE_BYTES_ENGINE = "include-bytes";
+/** Both file-embedding tag names, for a consumer holding an engine NAME rather
+ *  than a value (the analyzer's expression walk reports names). */
+export const INCLUDE_ENGINE_NAMES = new Set([
+    INCLUDE_TEXT_ENGINE,
+    INCLUDE_BYTES_ENGINE,
+]);
+/** True when `v` is an `!include-text` / `!include-bytes` sentinel — a file
+ *  embed marked at parse time and still unresolved.
+ *
+ *  The kernel's creation-time resolution keys off this the way Phase-5
+ *  injection keys off {@link isRefSentinel}. Both tags survive precompile as
+ *  markers rather than collapsing to a value, because the read is deferred: a
+ *  manifest load must not pull payload layers, and the analyzer that types the
+ *  slot cannot open files at all. */
+export function isIncludeSentinel(v) {
+    return (isTaggedSentinel(v) && (v.engine === INCLUDE_TEXT_ENGINE || v.engine === INCLUDE_BYTES_ENGINE));
+}

package/package.json

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

package/src/builtins.ts

@@ -1,4 +1,5 @@
 import { celEngine } from "./engines/cel.js";
+import { includeBytesEngine, includeTextEngine } from "./engines/include.js";
 import { literalEngine } from "./engines/literal.js";
 import { refEngine } from "./engines/ref.js";
 import { sqlEngine } from "./engines/sql.js";
@@ -13,6 +14,8 @@ import type { TemplatingEngine } from "./engine.js";
  *  another (e.g. `cel + literal`); always ship the same set. */
 export const builtinEngines: readonly TemplatingEngine[] = [
   celEngine,
+  includeBytesEngine,
+  includeTextEngine,
   literalEngine,
   refEngine,
   sqlEngine,

package/src/cel/catalog.ts

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