@telorun/templating 0.4.1 → 0.5.0

package/README.md

@@ -54,20 +54,13 @@ metadata:
   description: |
     A complete feedback collection REST API — no code, pure YAML.
     Persists entries to SQLite and serves them over HTTP.
+imports:
+  Http: std/http-server@0.8.0
+  Sql: std/sql@0.5.1
 targets:
   - Migrations
   - Server
 ---
-kind: Telo.Import
-metadata:
-  name: Http
-source: std/http-server@0.5.0
----
-kind: Telo.Import
-metadata:
-  name: Sql
-source: std/sql@0.3.0
----
 # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
 kind: Sql.Connection
 metadata:
@@ -127,7 +120,7 @@ routes:
               minLength: 1
             source:
               type: string
-          required: [text]
+          required: [ text ]
     handler:
       kind: Sql.Exec
       connection:
@@ -157,7 +150,7 @@ routes:
         kind: Sql.Connection
         name: Db
       from: feedback
-      columns: [id, text, source, score, created_at]
+      columns: [ id, text, source, score, created_at ]
       orderBy:
         - { column: created_at, direction: desc }
     response:
@@ -176,14 +169,14 @@ routes:
           properties:
             id:
               type: integer
-          required: [id]
+          required: [ id ]
     handler:
       kind: Sql.Select
       connection:
         kind: Sql.Connection
         name: Db
       from: feedback
-      columns: [id, text, source, score, created_at]
+      columns: [ id, text, source, score, created_at ]
       where:
         - { column: id, op: "=", value: "${{ request.params.id }}" }
     response:

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAA0C,CAAC;AAEjG,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAKrD,CAAC;AAEF,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}

package/dist/builtins.js

@@ -1,6 +1,7 @@
 import { celEngine } from "./engines/cel.js";
 import { literalEngine } from "./engines/literal.js";
 import { refEngine } from "./engines/ref.js";
+import { sqlEngine } from "./engines/sql.js";
 import { TemplatingEngineRegistry } from "./registry.js";
 /** Single source of truth for the built-in templating engines. Every host
  *  (kernel, analyzer, editor, vscode extension) calls `createDefaultRegistry`
@@ -8,7 +9,12 @@ import { TemplatingEngineRegistry } from "./registry.js";
  *  agree on which engines exist. Per-host à-la-carte registration would let
  *  a manifest validate clean in one host (e.g. `cel` only) and crash in
  *  another (e.g. `cel + literal`); always ship the same set. */
-export const builtinEngines = [celEngine, literalEngine, refEngine];
+export const builtinEngines = [
+    celEngine,
+    literalEngine,
+    refEngine,
+    sqlEngine,
+];
 export function createDefaultRegistry() {
     const registry = new TemplatingEngineRegistry();
     for (const engine of builtinEngines) {

package/dist/cel/compile.d.ts

@@ -1,4 +1,4 @@
-import type { CompiledValue } from "@telorun/sdk";
+import { type CompiledValue } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
 export declare const TEMPLATE_REGEX: RegExp;
 export declare const EXACT_TEMPLATE_REGEX: RegExp;
@@ -12,4 +12,18 @@ export declare function compileExpression(expr: string, env: Environment): Compi
  *  with stringified expression results. If no expressions are present, returns
  *  the input string unchanged. Throws on CEL syntax errors. */
 export declare function compileString(s: string, env: Environment): unknown;
+/** Split an interpolated value into literal fragments and the evaluated values
+ *  of its embedded expressions, instead of joining them into one string. Lets a
+ *  consumer emit its own placeholders between fragments and bind the values
+ *  separately (e.g. parameterized SQL). The invariant
+ *  `fragments.length === values.length + 1` always holds.
+ *
+ *  - plain string (no `${{ }}`)        → `{ fragments: [s], values: [] }`
+ *  - bare single expression `${{ x }}` → `{ fragments: ["", ""], values: [x] }`
+ *  - interpolated `"a ${{ x }} b"`     → `{ fragments: ["a ", " b"], values: [x] }`
+ */
+export declare function toParameterized(value: unknown, ctx: Record<string, unknown>): {
+    fragments: string[];
+    values: unknown[];
+};
 //# sourceMappingURL=compile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cel/compile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,eAAO,MAAM,cAAc,QAA8B,CAAC;AAC1D,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAEvE;;2CAE2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAO/E;AAED;;;;+DAI+D;AAC/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAuBlE"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cel/compile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,eAAO,MAAM,cAAc,QAA8B,CAAC;AAC1D,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAEvE;;2CAE2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAO/E;AAED;;;;+DAI+D;AAC/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAwBlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAsB5C"}

package/dist/cel/compile.js

@@ -1,3 +1,4 @@
+import { isCompiledValue } from "@telorun/sdk";
 export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 export const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
 /** Compile a single CEL expression (no `${{ }}` wrapping) into a CompiledValue.
@@ -36,6 +37,42 @@ export function compileString(s, env) {
     return {
         __compiled: true,
         source: s,
+        parts,
         call: (ctx) => parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
     };
 }
+/** Split an interpolated value into literal fragments and the evaluated values
+ *  of its embedded expressions, instead of joining them into one string. Lets a
+ *  consumer emit its own placeholders between fragments and bind the values
+ *  separately (e.g. parameterized SQL). The invariant
+ *  `fragments.length === values.length + 1` always holds.
+ *
+ *  - plain string (no `${{ }}`)        → `{ fragments: [s], values: [] }`
+ *  - bare single expression `${{ x }}` → `{ fragments: ["", ""], values: [x] }`
+ *  - interpolated `"a ${{ x }} b"`     → `{ fragments: ["a ", " b"], values: [x] }`
+ */
+export function toParameterized(value, ctx) {
+    if (typeof value === "string")
+        return { fragments: [value], values: [] };
+    if (!isCompiledValue(value)) {
+        throw new Error("toParameterized expects a string or CompiledValue");
+    }
+    if (!value.parts) {
+        return { fragments: ["", ""], values: [value.call(ctx)] };
+    }
+    const fragments = [];
+    const values = [];
+    let current = "";
+    for (const p of value.parts) {
+        if (typeof p === "string") {
+            current += p;
+        }
+        else {
+            fragments.push(current);
+            current = "";
+            values.push(p.call(ctx));
+        }
+    }
+    fragments.push(current);
+    return { fragments, values };
+}

package/dist/engines/cel.d.ts

@@ -1,4 +1,10 @@
-import type { TemplatingEngine } from "../engine.js";
+import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export declare function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[];
 /** 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

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,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBA4CvB,CAAC"}
+{"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"}

package/dist/engines/cel.js

@@ -1,5 +1,42 @@
 import { extractAccessChains, findNullableAccessIssues, validateChainAgainstSchema, } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export function analyzeCelExpression(source, env) {
+    const out = [];
+    let parsed;
+    try {
+        parsed = env.celEnv.parse(source);
+    }
+    catch (e) {
+        out.push({
+            code: "CEL_SYNTAX_ERROR",
+            message: e instanceof Error ? e.message : String(e),
+        });
+        return out;
+    }
+    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 });
+    }
+    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}'`,
+        });
+    }
+    return out;
+}
 /** 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
@@ -11,35 +48,6 @@ export const celEngine = {
         return compileExpression(source, env.celEnv);
     },
     analyze(source, env) {
-        const out = [];
-        let parsed;
-        try {
-            parsed = env.celEnv.parse(source);
-        }
-        catch (e) {
-            out.push({
-                code: "CEL_SYNTAX_ERROR",
-                message: e instanceof Error ? e.message : String(e),
-            });
-            return out;
-        }
-        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 });
-        }
-        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}'`,
-            });
-        }
-        return out;
+        return analyzeCelExpression(source, env);
     },
 };

package/dist/engines/sql.d.ts

@@ -0,0 +1,11 @@
+import { isParameterizedSql, type ParameterizedSql } from "@telorun/sdk";
+import type { TemplatingEngine } from "../engine.js";
+export { isParameterizedSql, type ParameterizedSql };
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export declare const sqlEngine: TemplatingEngine;
+//# sourceMappingURL=sql.d.ts.map

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

@@ -0,0 +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"}

package/dist/engines/sql.js

@@ -0,0 +1,38 @@
+import { isParameterizedSql } from "@telorun/sdk";
+import { analyzeCelExpression } from "./cel.js";
+import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
+export { isParameterizedSql };
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export const sqlEngine = {
+    name: "sql",
+    language: "sql",
+    compile(source, env) {
+        const inner = compileString(source, env.celEnv);
+        return {
+            __compiled: true,
+            source,
+            call: (ctx) => {
+                const { fragments, values } = toParameterized(inner, ctx);
+                return { __teloParameterized: true, fragments, values };
+            },
+        };
+    },
+    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));
+    },
+};
+/** Extract each `${{ expr }}` body from a `!sql` template source. */
+function expressionsOf(source) {
+    const exprs = [];
+    for (const m of source.matchAll(TEMPLATE_REGEX)) {
+        exprs.push(m[1].trim());
+    }
+    return exprs;
+}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
-export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.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 { celEngine } from "./engines/cel.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";

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,iBAAiB,EACjB,aAAa,EACb,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;AAE7C,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,GAClB,MAAM,uBAAuB,CAAC"}
+{"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,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,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,10 +1,11 @@
 export { buildCelEnvironment } from "./cel/environment.js";
-export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.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 { celEngine } from "./engines/cel.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";

package/package.json

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

package/src/builtins.ts

@@ -1,6 +1,7 @@
 import { celEngine } from "./engines/cel.js";
 import { literalEngine } from "./engines/literal.js";
 import { refEngine } from "./engines/ref.js";
+import { sqlEngine } from "./engines/sql.js";
 import { TemplatingEngineRegistry } from "./registry.js";
 import type { TemplatingEngine } from "./engine.js";
 
@@ -10,7 +11,12 @@ import type { TemplatingEngine } from "./engine.js";
  *  agree on which engines exist. Per-host à-la-carte registration would let
  *  a manifest validate clean in one host (e.g. `cel` only) and crash in
  *  another (e.g. `cel + literal`); always ship the same set. */
-export const builtinEngines: readonly TemplatingEngine[] = [celEngine, literalEngine, refEngine];
+export const builtinEngines: readonly TemplatingEngine[] = [
+  celEngine,
+  literalEngine,
+  refEngine,
+  sqlEngine,
+];
 
 export function createDefaultRegistry(): TemplatingEngineRegistry {
   const registry = new TemplatingEngineRegistry();

package/src/cel/compile.ts

@@ -1,4 +1,4 @@
-import type { CompiledValue } from "@telorun/sdk";
+import { isCompiledValue, type CompiledValue } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
 
 export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
@@ -41,7 +41,45 @@ export function compileString(s: string, env: Environment): unknown {
   return {
     __compiled: true,
     source: s,
+    parts,
     call: (ctx: Record<string, unknown>) =>
       parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
   } satisfies CompiledValue;
 }
+
+/** Split an interpolated value into literal fragments and the evaluated values
+ *  of its embedded expressions, instead of joining them into one string. Lets a
+ *  consumer emit its own placeholders between fragments and bind the values
+ *  separately (e.g. parameterized SQL). The invariant
+ *  `fragments.length === values.length + 1` always holds.
+ *
+ *  - plain string (no `${{ }}`)        → `{ fragments: [s], values: [] }`
+ *  - bare single expression `${{ x }}` → `{ fragments: ["", ""], values: [x] }`
+ *  - interpolated `"a ${{ x }} b"`     → `{ fragments: ["a ", " b"], values: [x] }`
+ */
+export function toParameterized(
+  value: unknown,
+  ctx: Record<string, unknown>,
+): { fragments: string[]; values: unknown[] } {
+  if (typeof value === "string") return { fragments: [value], values: [] };
+  if (!isCompiledValue(value)) {
+    throw new Error("toParameterized expects a string or CompiledValue");
+  }
+  if (!value.parts) {
+    return { fragments: ["", ""], values: [value.call(ctx)] };
+  }
+  const fragments: string[] = [];
+  const values: unknown[] = [];
+  let current = "";
+  for (const p of value.parts) {
+    if (typeof p === "string") {
+      current += p;
+    } else {
+      fragments.push(current);
+      current = "";
+      values.push(p.call(ctx));
+    }
+  }
+  fragments.push(current);
+  return { fragments, values };
+}

package/src/engines/cel.ts

@@ -4,7 +4,49 @@ import {
   validateChainAgainstSchema,
 } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
-import type { EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[] {
+  const out: EngineDiagnostic[] = [];
+
+  let parsed: ReturnType<typeof env.celEnv.parse>;
+  try {
+    parsed = env.celEnv.parse(source);
+  } catch (e) {
+    out.push({
+      code: "CEL_SYNTAX_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+    });
+    return out;
+  }
+
+  if (!env.contextSchema) return out;
+
+  const chains = extractAccessChains(parsed.ast);
+  for (const chain of chains) {
+    const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
+    if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+  }
+
+  for (const issue of findNullableAccessIssues(
+    parsed.ast,
+    env.contextSchema as Record<string, any>,
+  )) {
+    // Index access (member "[index]") attaches without a dot; a named field
+    // attaches with one — so the suggested CEL stays valid either way.
+    const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+    out.push({
+      code: "CEL_NULLABLE_ACCESS",
+      message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+    });
+  }
+  return out;
+}
 
 /** The `!cel` engine. Treats the entire tagged scalar as a single CEL
  *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
@@ -19,39 +61,6 @@ export const celEngine: TemplatingEngine = {
   },
 
   analyze(source, env) {
-    const out: EngineDiagnostic[] = [];
-
-    let parsed: ReturnType<typeof env.celEnv.parse>;
-    try {
-      parsed = env.celEnv.parse(source);
-    } catch (e) {
-      out.push({
-        code: "CEL_SYNTAX_ERROR",
-        message: e instanceof Error ? e.message : String(e),
-      });
-      return out;
-    }
-
-    if (!env.contextSchema) return out;
-
-    const chains = extractAccessChains(parsed.ast);
-    for (const chain of chains) {
-      const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
-      if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
-    }
-
-    for (const issue of findNullableAccessIssues(
-      parsed.ast,
-      env.contextSchema as Record<string, any>,
-    )) {
-      // Index access (member "[index]") attaches without a dot; a named field
-      // attaches with one — so the suggested CEL stays valid either way.
-      const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
-      out.push({
-        code: "CEL_NULLABLE_ACCESS",
-        message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
-      });
-    }
-    return out;
+    return analyzeCelExpression(source, env);
   },
 };

package/src/engines/sql.ts

@@ -0,0 +1,44 @@
+import { isParameterizedSql, type CompiledValue, type ParameterizedSql } from "@telorun/sdk";
+import { analyzeCelExpression } from "./cel.js";
+import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
+import type { TemplatingEngine } from "../engine.js";
+
+export { isParameterizedSql, type ParameterizedSql };
+
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export const sqlEngine: TemplatingEngine = {
+  name: "sql",
+  language: "sql",
+
+  compile(source, env) {
+    const inner = compileString(source, env.celEnv);
+    return {
+      __compiled: true,
+      source,
+      call: (ctx: Record<string, unknown>): ParameterizedSql => {
+        const { fragments, values } = toParameterized(inner, ctx);
+        return { __teloParameterized: true, fragments, values };
+      },
+    } satisfies CompiledValue;
+  },
+
+  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));
+  },
+};
+
+/** Extract each `${{ expr }}` body from a `!sql` template source. */
+function expressionsOf(source: string): string[] {
+  const exprs: string[] = [];
+  for (const m of source.matchAll(TEMPLATE_REGEX)) {
+    exprs.push(m[1]!.trim());
+  }
+  return exprs;
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
 export {
   compileExpression,
   compileString,
+  toParameterized,
   TEMPLATE_REGEX,
   EXACT_TEMPLATE_REGEX,
 } from "./cel/compile.js";
@@ -16,6 +17,7 @@ export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.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";