@telorun/templating 0.12.0 → 0.14.0

package/dist/engine.d.ts

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

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;wEAEwE;AACxE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;2BAI2B;AAC3B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;oDAEoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;wBAEwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;2EAKuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;yDAGqD;IACrD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,CAAC;IAElE;2EACuE;IACvE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,gBAAgB,EAAE,CAAC;CACvE"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;wEAEwE;AACxE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;eASe;AACf,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;;;;;;;0EAa0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;oDAEoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;yBAIyB;AACzB,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;iFAGiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;4CAgB4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;wBAEwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;2EAKuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;yDAGqD;IACrD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,CAAC;IAElE;;iEAE6D;IAC7D,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC;IAExD;;;;;;;;;;;;uBAYmB;IACnB,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAAC;IAExD;;;;;;;;;;;;;;;;;2CAiBuC;IACvC,YAAY,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C"}

package/dist/engines/cel.d.ts

@@ -1,13 +1,17 @@
-import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import type { AnalyzeEnv, AnalyzeResult, TemplatingEngine } from "../engine.js";
 /** Statically analyze one CEL expression against the effective context schema:
- *  parse → extract member-access chains → validate each chain → flag nullable
- *  access. Single source of truth shared by the `!cel` engine (one expression)
- *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
- *  can't drift between them. */
-export declare function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[];
+ *  parse → classify every call → type-check → validate member-access chains →
+ *  flag nullable access. Single source of truth shared by the `!cel` engine
+ *  (one expression) and the `!sql` engine (one per `${{ }}` interpolation), so
+ *  diagnostic wording can't drift between them.
+ *
+ *  The type-check lives here, not in the analyzer, so one expression produces
+ *  one verdict against one environment. Splitting them let an opaque
+ *  "no matching overload" survive next to the diagnostic that actually
+ *  explained it, and left `${{ }}` interpolations chain-validated but never
+ *  type-checked at all. */
+export declare function analyzeCelExpression(source: string, env: AnalyzeEnv): AnalyzeResult;
 /** 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 declare const celEngine: TemplatingEngine;
 //# sourceMappingURL=cel.d.ts.map

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,28 @@
+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 — the shape every `Telo.Bytes` slot
+ *  accepts. The name is written as a literal rather than imported from the SDK:
+ *  templating is the lower package, and a produced type is a schema fragment,
+ *  which is data. What checks it is the registry the analyzer and the kernel both
+ *  read. */
+export 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;AA8CD,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,gBAE9B,CAAC;AAEH;;;;YAIY;AACZ,eAAO,MAAM,kBAAkB,EAAE,gBAE/B,CAAC"}

package/dist/engines/include.js

@@ -0,0 +1,142 @@
+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, produced) {
+    return {
+        name,
+        compile(source) {
+            return makeTaggedSentinel(name, source);
+        },
+        producedType() {
+            return produced;
+        },
+        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, {
+    type: "string",
+});
+/** Embeds a file's contents as raw bytes — the shape every `Telo.Bytes` slot
+ *  accepts. The name is written as a literal rather than imported from the SDK:
+ *  templating is the lower package, and a produced type is a schema fragment,
+ *  which is data. What checks it is the registry the analyzer and the kernel both
+ *  read. */
+export const includeBytesEngine = includeEngine(INCLUDE_BYTES_ENGINE, {
+    "x-telo-type": "Telo.Bytes",
+});

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 { builtinEngines, createDefaultRegistry, defaultRegistry, producedTypeOf, } from "./builtins.js";
+export type { AnalyzeEnv, AnalyzeResult, CallSite, CompileEnv, DiagnosticFix, EngineDiagnostic, EngineFileClaim, TemplatingEngine, } from "./engine.js";
+export { CEL_ENGINE, INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, INCLUDE_TEXT_ENGINE, isIncludeSentinel, isRefSentinel, isTaggedSentinel, makeTaggedSentinel, plainChainOf, type TaggedSentinel, } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
-export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } from "./manifest-schemas.js";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, } 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,EACL,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,aAAa,EACb,QAAQ,EACR,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,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 { builtinEngines, createDefaultRegistry, defaultRegistry, producedTypeOf, } from "./builtins.js";
+export { CEL_ENGINE, INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, INCLUDE_TEXT_ENGINE, isIncludeSentinel, isRefSentinel, isTaggedSentinel, makeTaggedSentinel, plainChainOf, } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
-export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } from "./manifest-schemas.js";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, } from "./manifest-schemas.js";

package/dist/manifest-schemas.d.ts

@@ -70,22 +70,6 @@ export declare const ResourceRefSchema: {
         additionalProperties: boolean;
     })[];
 };
-/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
- *  reference-slot node — one carrying an `x-telo-ref` string annotation.
- *
- *  A reference slot's value is always a `!ref` sentinel or its resolved
- *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
- *  published modules still pin `type: "string"` on these slots — the encoding
- *  references took when they were written as plain strings — which now rejects
- *  the resolved object. Removing only the scalar `type` lets the analyzer and
- *  kernel accept references uniformly across module versions during the
- *  migration away from `{kind, name}` / string references, without disturbing
- *  slots that legitimately accept an inline object (e.g. `inputType` /
- *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
- *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
- *  checked separately by the analyzer's reference walker, which reads the
- *  original schema — not this validation-only copy. */
-export declare function normalizeRefSlots(schema: unknown): unknown;
 /** Stable URI under which the shared manifest root schema is registered
  *  with module-side AJV instances. Module YAMLs reach the fragments via
  *  `$ref: "telo://manifest#/$defs/<Name>"`. The URI is the contract;