@telorun/templating 0.4.1 → 0.6.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/catalog.d.ts

@@ -0,0 +1,45 @@
+/** Host-injected functions that need platform APIs the templating package must
+ *  not import directly (Node `crypto` / `Buffer`), keeping it browser-safe. The
+ *  kernel supplies real implementations; the analyzer omits them (the stubs
+ *  throw, since static analysis never executes these). */
+export interface CelHandlers {
+    sha256: (s: string) => string;
+    md5: (s: string) => string;
+    sha1: (s: string) => string;
+    sha512: (s: string) => string;
+    hmac: (algorithm: string, key: string, message: string) => string;
+    base64Encode: (s: string) => string;
+    base64Decode: (s: string) => string;
+    json: (value: unknown) => string;
+}
+export type CelFunctionCategory = "conversion" | "time" | "uuid" | "string" | "math" | "collection" | "json" | "encoding" | "hashing" | "null";
+/** One entry in the CEL standard library — the single source of truth that both
+ *  registers the function (`build`) and documents it (everything else). `telo
+ *  cel functions` and `celFunctionCatalog()` read the metadata; `buildCelEnvironment`
+ *  calls `build`. */
+export interface CelFunctionDoc {
+    /** Bare function name (`nowIso`, `uuidv4`). */
+    readonly name: string;
+    /** Human-facing signature for docs (`nowIso(tz?): string`). May use `?` for
+     *  optional args even though cel-js itself has no optional syntax. */
+    readonly signature: string;
+    /** Actual cel-js signatures to register — one per arity for an overloaded
+     *  function. Defaults to `[signature]` when omitted (the common single-arity
+     *  case, where `signature` is itself a valid cel-js signature). */
+    readonly register?: readonly string[];
+    readonly category: CelFunctionCategory;
+    readonly summary: string;
+    /** False → re-evaluates per call; in an `x-telo-eval: compile` field it bakes
+     *  once at load. */
+    readonly deterministic: boolean;
+    /** Needs a `CelHandlers` implementation (Node `crypto` / `Buffer`); the
+     *  analyzer's stub throws if such a function is actually evaluated. */
+    readonly hostBacked: boolean;
+    readonly build: (h: CelHandlers) => (...args: any[]) => unknown;
+}
+/** Public, build-free view of a catalog entry (for `--json` / docs). */
+export type CelFunctionInfo = Omit<CelFunctionDoc, "build">;
+export declare const CEL_FUNCTIONS: readonly CelFunctionDoc[];
+/** Build-free catalog for the CLI / docs (`telo cel functions`). */
+export declare function celFunctionCatalog(): CelFunctionInfo[];
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/cel/catalog.ts"],"names":[],"mappings":"AAEA;;;0DAG0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX;;;qBAGqB;AACrB,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;uEAEmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;wBACoB;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACjE;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAyE5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAsZlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}

package/dist/cel/catalog.js

@@ -0,0 +1,475 @@
+import { v1, v3, v4, v5, v6, v7, validate as uuidValidate, version as uuidVersion } from "uuid";
+const num = (x) => Number(x);
+const minMax = (list, isMin) => {
+    if (!Array.isArray(list) || list.length === 0)
+        return null;
+    let best = list[0];
+    let bestN = num(best);
+    for (const x of list) {
+        const n = num(x);
+        if (isMin ? n < bestN : n > bestN) {
+            best = x;
+            bestN = n;
+        }
+    }
+    return best;
+};
+const sortList = (list) => [...list].sort((a, b) => {
+    if (typeof a === "number" || typeof a === "bigint") {
+        const d = num(a) - num(b);
+        return d < 0 ? -1 : d > 0 ? 1 : 0;
+    }
+    return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+});
+/** `Intl.DateTimeFormat` is an ECMA-402 global in Node (full ICU) and browsers,
+ *  so timezone handling needs no Node-only API and stays browser-safe. */
+const zoneParts = (date, tz, opts) => {
+    const parts = {};
+    for (const p of new Intl.DateTimeFormat("en-US", { timeZone: tz, ...opts }).formatToParts(date)) {
+        parts[p.type] = p.value;
+    }
+    return parts;
+};
+/** Current instant as ISO-8601 in `tz`: UTC `…Z` for "UTC", else the zone's
+ *  offset (e.g. `2026-06-06T18:30:00.000-05:00`). Uses only standard Intl
+ *  fields and derives the offset arithmetically, so it needs no newer Intl
+ *  type-lib features and stays portable. */
+const isoInZone = (tz) => {
+    const now = new Date();
+    if (tz === "UTC" || tz === "Z")
+        return now.toISOString();
+    const p = zoneParts(now, tz, {
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    // Sub-second is timezone-independent; read it off the instant directly.
+    const ms = String(now.getUTCMilliseconds()).padStart(3, "0");
+    // Offset = the zone's wall-clock read as UTC, minus the real instant.
+    const asUtc = Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour, +p.minute, +p.second);
+    const offsetMin = Math.round((asUtc - now.getTime()) / 60000);
+    const offset = offsetMin === 0
+        ? "Z"
+        : `${offsetMin > 0 ? "+" : "-"}${String(Math.floor(Math.abs(offsetMin) / 60)).padStart(2, "0")}:${String(Math.abs(offsetMin) % 60).padStart(2, "0")}`;
+    return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}.${ms}${offset}`;
+};
+/** Current calendar date (`YYYY-MM-DD`) in `tz`. */
+const dateInZone = (tz) => {
+    const now = new Date();
+    if (tz === "UTC" || tz === "Z")
+        return now.toISOString().slice(0, 10);
+    const p = zoneParts(now, tz, { year: "numeric", month: "2-digit", day: "2-digit" });
+    return `${p.year}-${p.month}-${p.day}`;
+};
+export const CEL_FUNCTIONS = [
+    // Collections
+    {
+        name: "join",
+        signature: "join(list, string): string",
+        category: "collection",
+        summary: "Join list elements into a string with a separator.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list, sep) => list.map(String).join(sep),
+    },
+    {
+        name: "keys",
+        signature: "keys(map): list",
+        category: "collection",
+        summary: "List a map's keys.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (map) => map instanceof Map ? [...map.keys()] : Object.keys(map),
+    },
+    {
+        name: "values",
+        signature: "values(map): list",
+        category: "collection",
+        summary: "List a map's values.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (map) => map instanceof Map ? [...map.values()] : Object.values(map),
+    },
+    {
+        name: "distinct",
+        signature: "distinct(list): list",
+        category: "collection",
+        summary: "Remove duplicate elements, preserving order.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => [...new Set(list)],
+    },
+    {
+        name: "reverse",
+        signature: "reverse(list): list",
+        category: "collection",
+        summary: "Reverse a list (copy; never mutates the input).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => [...list].reverse(),
+    },
+    {
+        name: "flatten",
+        signature: "flatten(list): list",
+        category: "collection",
+        summary: "Flatten one level of nested lists.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => list.flat(),
+    },
+    {
+        name: "sort",
+        signature: "sort(list): list",
+        category: "collection",
+        summary: "Sort a list numerically (numbers) or lexicographically; copy.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => sortList(list),
+    },
+    // Strings
+    {
+        name: "lower",
+        signature: "lower(string): string",
+        category: "string",
+        summary: "Lowercase a string.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => s.toLowerCase(),
+    },
+    {
+        name: "upper",
+        signature: "upper(string): string",
+        category: "string",
+        summary: "Uppercase a string.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => s.toUpperCase(),
+    },
+    {
+        name: "trim",
+        signature: "trim(string): string",
+        category: "string",
+        summary: "Strip leading/trailing whitespace.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => s.trim(),
+    },
+    {
+        name: "replace",
+        signature: "replace(string, string, string): string",
+        category: "string",
+        summary: "Replace all occurrences of a substring.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s, a, b) => s.split(a).join(b),
+    },
+    {
+        name: "split",
+        signature: "split(string, string): list",
+        category: "string",
+        summary: "Split a string on a separator into a list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s, sep) => s.split(sep),
+    },
+    // Math
+    {
+        name: "abs",
+        signature: "abs(dyn): double",
+        category: "math",
+        summary: "Absolute value.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x) => Math.abs(num(x)),
+    },
+    {
+        name: "floor",
+        signature: "floor(dyn): double",
+        category: "math",
+        summary: "Round down to an integer.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x) => Math.floor(num(x)),
+    },
+    {
+        name: "ceil",
+        signature: "ceil(dyn): double",
+        category: "math",
+        summary: "Round up to an integer.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x) => Math.ceil(num(x)),
+    },
+    {
+        name: "round",
+        signature: "round(dyn): double",
+        category: "math",
+        summary: "Round to the nearest integer.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (x) => Math.round(num(x)),
+    },
+    {
+        name: "min",
+        signature: "min(list): dyn",
+        category: "math",
+        summary: "Smallest element (by numeric value); null for an empty list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => minMax(list, true),
+    },
+    {
+        name: "max",
+        signature: "max(list): dyn",
+        category: "math",
+        summary: "Largest element (by numeric value); null for an empty list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => minMax(list, false),
+    },
+    // JSON
+    {
+        name: "json",
+        signature: "json(dyn): string",
+        category: "json",
+        summary: "Serialize any value to a JSON string.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (value) => h.json(value),
+    },
+    {
+        name: "parseJson",
+        signature: "parseJson(string): dyn",
+        category: "json",
+        summary: "Parse a JSON string into a value (numbers come back as doubles).",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => JSON.parse(s),
+    },
+    // Encoding
+    {
+        name: "base64Encode",
+        signature: "base64Encode(string): string",
+        category: "encoding",
+        summary: "Encode a UTF-8 string as base64.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.base64Encode(s),
+    },
+    {
+        name: "base64Decode",
+        signature: "base64Decode(string): string",
+        category: "encoding",
+        summary: "Decode a base64 string to UTF-8.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.base64Decode(s),
+    },
+    {
+        name: "urlEncode",
+        signature: "urlEncode(string): string",
+        category: "encoding",
+        summary: "Percent-encode a URI component.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => encodeURIComponent(s),
+    },
+    {
+        name: "urlDecode",
+        signature: "urlDecode(string): string",
+        category: "encoding",
+        summary: "Decode a percent-encoded URI component.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => decodeURIComponent(s),
+    },
+    // Hashing
+    {
+        name: "sha256",
+        signature: "sha256(string): string",
+        category: "hashing",
+        summary: "SHA-256 hash, hex-encoded.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.sha256(s),
+    },
+    {
+        name: "md5",
+        signature: "md5(string): string",
+        category: "hashing",
+        summary: "MD5 hash, hex-encoded.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.md5(s),
+    },
+    {
+        name: "sha1",
+        signature: "sha1(string): string",
+        category: "hashing",
+        summary: "SHA-1 hash, hex-encoded.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.sha1(s),
+    },
+    {
+        name: "sha512",
+        signature: "sha512(string): string",
+        category: "hashing",
+        summary: "SHA-512 hash, hex-encoded.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (s) => h.sha512(s),
+    },
+    {
+        name: "hmac",
+        signature: "hmac(string, string, string): string",
+        category: "hashing",
+        summary: "HMAC of message under key for an algorithm (e.g. 'sha256'), hex.",
+        deterministic: true,
+        hostBacked: true,
+        build: (h) => (algo, key, msg) => h.hmac(algo, key, msg),
+    },
+    // Null handling
+    {
+        name: "default",
+        signature: "default(dyn, dyn): dyn",
+        category: "null",
+        summary: "Return the value, or the fallback when it is null.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (v, fallback) => v === null || v === undefined ? fallback : v,
+    },
+    {
+        name: "coalesce",
+        signature: "coalesce(list): dyn",
+        category: "null",
+        summary: "First non-null element of a list, or null.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => {
+            const found = list.find((x) => x !== null && x !== undefined);
+            return found === undefined ? null : found;
+        },
+    },
+    // Time (non-deterministic). `nowIso`/`today` take an optional IANA timezone
+    // (default "UTC"); epoch values are absolute and take none.
+    {
+        name: "nowIso",
+        signature: "nowIso(tz?): string",
+        register: ["nowIso(): string", "nowIso(string): string"],
+        category: "time",
+        summary: "Current time as ISO-8601; UTC by default, or in the given IANA timezone.",
+        deterministic: false,
+        hostBacked: false,
+        build: () => (tz) => isoInZone(tz ?? "UTC"),
+    },
+    {
+        name: "today",
+        signature: "today(tz?): string",
+        register: ["today(): string", "today(string): string"],
+        category: "time",
+        summary: "Current calendar date (YYYY-MM-DD); UTC by default, or in the given IANA timezone.",
+        deterministic: false,
+        hostBacked: false,
+        build: () => (tz) => dateInZone(tz ?? "UTC"),
+    },
+    {
+        name: "nowMillis",
+        signature: "nowMillis(): int",
+        category: "time",
+        summary: "Current time as epoch milliseconds (absolute; timezone-independent).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => BigInt(Date.now()),
+    },
+    {
+        name: "nowSeconds",
+        signature: "nowSeconds(): int",
+        category: "time",
+        summary: "Current time as epoch seconds (absolute; timezone-independent).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => BigInt(Math.floor(Date.now() / 1000)),
+    },
+    // UUID
+    {
+        name: "uuidv1",
+        signature: "uuidv1(): string",
+        category: "uuid",
+        summary: "Time-based UUID (v1).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => v1(),
+    },
+    {
+        name: "uuidv4",
+        signature: "uuidv4(): string",
+        category: "uuid",
+        summary: "Random UUID (v4).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => v4(),
+    },
+    {
+        name: "uuidv6",
+        signature: "uuidv6(): string",
+        category: "uuid",
+        summary: "Time-ordered UUID (v6).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => v6(),
+    },
+    {
+        name: "uuidv7",
+        signature: "uuidv7(): string",
+        category: "uuid",
+        summary: "Time-ordered UUID (v7).",
+        deterministic: false,
+        hostBacked: false,
+        build: () => () => v7(),
+    },
+    {
+        name: "uuidv3",
+        signature: "uuidv3(string, string): string",
+        category: "uuid",
+        summary: "Name-based UUID (v3, MD5) under a namespace UUID.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (name, ns) => v3(name, ns),
+    },
+    {
+        name: "uuidv5",
+        signature: "uuidv5(string, string): string",
+        category: "uuid",
+        summary: "Name-based UUID (v5, SHA-1) under a namespace UUID.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (name, ns) => v5(name, ns),
+    },
+    {
+        name: "uuidValidate",
+        signature: "uuidValidate(string): bool",
+        category: "uuid",
+        summary: "True if the string is a valid UUID.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => uuidValidate(s),
+    },
+    {
+        name: "uuidVersion",
+        signature: "uuidVersion(string): int",
+        category: "uuid",
+        summary: "The version number of a UUID.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (s) => BigInt(uuidVersion(s)),
+    },
+];
+/** Build-free catalog for the CLI / docs (`telo cel functions`). */
+export function celFunctionCatalog() {
+    return CEL_FUNCTIONS.map(({ build: _build, ...info }) => info);
+}

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 };
+}