yaml-flow 3.1.1 → 5.0.0

package/browser/card-compute.js

@@ -1,29 +1,28 @@
-// card_compute.js — Pure JSON expression evaluator for LiveCards nodes
+// card-compute.js — JSONata-powered compute engine for LiveCards (browser build)
 //
-// Isomorphic: works in browser (global), Node.js (require), and ESM (import).
-// No DOM dependency. Usable on both client and server.
+// Requires JSONata to be loaded first:
+//   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
 //
-// API:
-//   CardCompute.run(node)                 → mutates node.state with computed values, returns node
-//   CardCompute.eval(expr, node)          → evaluates a single compute_expr, returns value
-//   CardCompute.resolve(node, path)       → deep-get a state path like "state.foo.bar"
-//   CardCompute.registerFunction(name, fn) → add custom compute function
-//   CardCompute.functions                 → read-only map of all registered functions
+// API (all async where noted):
+//   CardCompute.run(node, options)         → Promise<node>  — eval all compute steps → computed_values
+//   CardCompute.eval(expr, node)           → Promise<value> — eval single JSONata expression
+//   CardCompute.resolve(node, path)        → value          — sync deep-get "card_data.foo" or "fetched_sources.foo"
+//   CardCompute.validate(node)             → { ok, errors } — sync structural validator
 //
-// Compute declarations (node.compute):
-//   {
-//     "total_value": { "fn": "sum", "input": "state.raw_quotes" },
-//     "avg_price":   { "fn": "avg", "input": "state.raw_quotes" },
-//     "direction":   { "fn": "if", "cond": { "fn": "gt", "input": ["state.latest", "state.prev"] }, "then": "up", "else": "down" }
-//   }
+// Compute steps shape: { bindTo: string, expr: string }
+//   expr is a JSONata expression evaluated against { card_data, requires, fetched_sources, computed_values }
+//   computed_values and _sourcesData are ephemeral — reset on each run(), never persisted.
+//
+// Sequential steps: later steps see earlier results via computed_values.*
+// options.sourcesData: pre-loaded { [bindTo]: data } map for the fetched_sources.* namespace
 
 (function (root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory();                       // Node / CommonJS
+    module.exports = factory();        // Node / CommonJS
   } else if (typeof define === 'function' && define.amd) {
-    define(factory);                                   // AMD
+    define(factory);                   // AMD
   } else {
-    root.CardCompute = factory();                      // Browser global
+    root.CardCompute = factory();      // Browser global
   }
 }(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
@@ -33,10 +32,10 @@
   // ===========================================================================
 
   function _deepGet(obj, path) {
-    if (!path || !obj) return undefined;
-    const parts = path.split('.');
-    let cur = obj;
-    for (let i = 0; i < parts.length; i++) {
+    if (!path || obj == null) return undefined;
+    var parts = path.split('.');
+    var cur = obj;
+    for (var i = 0; i < parts.length; i++) {
       if (cur == null) return undefined;
       cur = cur[parts[i]];
     }
@@ -44,487 +43,214 @@
   }
 
   function _deepSet(obj, path, value) {
-    const parts = path.split('.');
-    let cur = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
+    var parts = path.split('.');
+    var cur = obj;
+    for (var i = 0; i < parts.length - 1; i++) {
       if (cur[parts[i]] == null || typeof cur[parts[i]] !== 'object') cur[parts[i]] = {};
       cur = cur[parts[i]];
     }
     cur[parts[parts.length - 1]] = value;
   }
 
-  function resolve(node, path) {
-    if (!path) return undefined;
-    return _deepGet(node, path);
-  }
-
   // ===========================================================================
-  // Built-in function registry
+  // run — evaluate all compute steps on a node (async, returns Promise<node>)
   // ===========================================================================
 
-  var _fns = {};
-
-  // ---- Aggregates ----
-
-  _fns.sum = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input : [];
-    return opts.field
-      ? a.reduce(function (s, r) { return s + (Number(r[opts.field]) || 0); }, 0)
-      : a.reduce(function (s, v) { return s + (Number(v) || 0); }, 0);
-  };
-
-  _fns.avg = function (input, _eval, opts) {
-    var s = _fns.sum(input, _eval, opts);
-    var n = Array.isArray(input) ? input.length : 1;
-    return n ? s / n : 0;
-  };
-
-  _fns.min = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input : [];
-    var vals = opts.field ? a.map(function (r) { return Number(r[opts.field]); }) : a.map(Number);
-    return vals.length ? Math.min.apply(null, vals) : 0;
-  };
-
-  _fns.max = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input : [];
-    var vals = opts.field ? a.map(function (r) { return Number(r[opts.field]); }) : a.map(Number);
-    return vals.length ? Math.max.apply(null, vals) : 0;
-  };
-
-  _fns.count = function (input) {
-    return Array.isArray(input) ? input.length : (input != null ? 1 : 0);
-  };
-
-  _fns.first = function (input) {
-    return Array.isArray(input) ? input[0] : input;
-  };
-
-  _fns.last = function (input) {
-    return Array.isArray(input) ? input[input.length - 1] : input;
-  };
-
-  // ---- Math ----
-
-  _fns.add = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.reduce(function (s, v) { return s + Number(v); }, 0);
-  };
-
-  _fns.sub = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.length >= 2 ? Number(a[0]) - Number(a[1]) : 0;
-  };
-
-  _fns.mul = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.reduce(function (s, v) { return s * Number(v); }, 1);
-  };
-
-  _fns.div = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.length >= 2 && Number(a[1]) !== 0 ? Number(a[0]) / Number(a[1]) : 0;
-  };
-
-  _fns.round = function (input, _eval, opts) {
-    var decimals = opts.decimals != null ? opts.decimals : 0;
-    var factor = Math.pow(10, decimals);
-    return Math.round(Number(input) * factor) / factor;
-  };
-
-  _fns.abs = function (input) { return Math.abs(Number(input)); };
-
-  _fns.mod = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.length >= 2 ? Number(a[0]) % Number(a[1]) : 0;
-  };
-
-  // ---- Compare ----
+  function run(node, options) {
+    if (!node || !node.compute || !node.compute.length) return Promise.resolve(node);
 
-  _fns.gt  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) > Number(a[1]); };
-  _fns.gte = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) >= Number(a[1]); };
-  _fns.lt  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) < Number(a[1]); };
-  _fns.lte = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && Number(a[0]) <= Number(a[1]); };
-  _fns.eq  = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && a[0] === a[1]; };
-  _fns.neq = function (input) { var a = Array.isArray(input) ? input : []; return a.length >= 2 && a[0] !== a[1]; };
+    if (!node.card_data) node.card_data = {};
+    node.computed_values = {};
+    node._sourcesData = (options && options.sourcesData) || {};
 
-  // ---- Logic ----
-
-  _fns.and = function (input) { var a = Array.isArray(input) ? input : []; return a.every(Boolean); };
-  _fns.or  = function (input) { var a = Array.isArray(input) ? input : []; return a.some(Boolean); };
-  _fns.not = function (input) { return !input; };
-  // "if" is handled specially in evalExpr
-
-  // ---- String ----
-
-  _fns.concat = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.map(function (v) { return v != null ? String(v) : ''; }).join('');
-  };
-
-  _fns.upper = function (input) { return String(input || '').toUpperCase(); };
-  _fns.lower = function (input) { return String(input || '').toLowerCase(); };
-
-  _fns.template = function (input, _eval, opts) {
-    var t = String(opts.format || '');
-    if (input && typeof input === 'object') {
-      Object.keys(input).forEach(function (k) {
-        t = t.split('{{' + k + '}}').join(input[k] != null ? String(input[k]) : '');
-      });
+    if (typeof jsonata === 'undefined') {
+      console.error('CardCompute: JSONata not loaded. Add <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script> before card-compute.js');
+      return Promise.resolve(node);
     }
-    return t;
-  };
-
-  _fns.join = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input : [];
-    var sep = opts.separator != null ? opts.separator : ', ';
-    return a.map(function (v) { return v != null ? String(v) : ''; }).join(sep);
-  };
-
-  _fns.split = function (input, _eval, opts) {
-    var sep = opts.separator != null ? opts.separator : ',';
-    return String(input || '').split(sep).map(function (s) { return s.trim(); });
-  };
-
-  _fns.trim = function (input) { return String(input || '').trim(); };
-
-  // ---- Collection ----
-
-  _fns.pluck = function (input, _eval, opts) {
-    return Array.isArray(input) ? input.map(function (r) { return r[opts.field]; }) : [];
-  };
-
-  _fns.filter = function (input, evalFn, opts) {
-    // Handled specially in evalExpr for the where clause; fallback for simple truthy filter
-    if (!Array.isArray(input)) return [];
-    if (opts.field) return input.filter(function (r) { return !!r[opts.field]; });
-    return input.filter(Boolean);
-  };
 
-  _fns.map = function (input) {
-    // Handled specially in evalExpr for the apply clause
-    return Array.isArray(input) ? input.slice() : [];
-  };
-
-  _fns.sort = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input.slice() : [];
-    var f = opts.field;
-    var dir = opts.direction === 'desc' ? -1 : 1;
-    if (f) return a.sort(function (x, y) { return x[f] > y[f] ? dir : x[f] < y[f] ? -dir : 0; });
-    return a.sort(function (x, y) { return x > y ? dir : x < y ? -dir : 0; });
-  };
-
-  _fns.slice = function (input, _eval, opts) {
-    return Array.isArray(input) ? input.slice(opts.start || 0, opts.end) : input;
-  };
-
-  _fns.flat = function (input, _eval, opts) {
-    var depth = opts.depth != null ? opts.depth : 1;
-    return Array.isArray(input) ? input.flat(depth) : [input];
-  };
-
-  _fns.unique = function (input) {
-    if (!Array.isArray(input)) return [input];
-    // For primitives, use Set. For objects, use JSON comparison.
-    var seen = new Set();
-    return input.filter(function (v) {
-      var key = typeof v === 'object' ? JSON.stringify(v) : v;
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
-    });
-  };
-
-  _fns.group = function (input, _eval, opts) {
-    var a = Array.isArray(input) ? input : [];
-    var g = {};
-    a.forEach(function (r) {
-      var k = String(r[opts.field] || '');
-      if (!g[k]) g[k] = [];
-      g[k].push(r);
-    });
-    return g;
-  };
-
-  _fns.flatten_keys = function (input) {
-    // { a: [1,2], b: [3] } → [{ key: "a", value: 1 }, { key: "a", value: 2 }, { key: "b", value: 3 }]
-    if (!input || typeof input !== 'object' || Array.isArray(input)) return [];
-    var result = [];
-    Object.keys(input).forEach(function (k) {
-      var vals = Array.isArray(input[k]) ? input[k] : [input[k]];
-      vals.forEach(function (v) { result.push({ key: k, value: v }); });
+    var ctx = {
+      card_data: node.card_data,
+      requires: node.requires || {},
+      fetched_sources: node._sourcesData,
+      computed_values: node.computed_values,
+    };
+
+    var chain = Promise.resolve();
+    node.compute.forEach(function (step) {
+      chain = chain.then(function () {
+        if (!step || typeof step.expr !== 'string') return;
+        return jsonata(step.expr).evaluate(ctx).then(function (val) {
+          _deepSet(node.computed_values, step.bindTo, val);
+          ctx.computed_values = node.computed_values; // subsequent steps see earlier results
+        }).catch(function (e) {
+          console.error('CardCompute.run error on "' + (node.id || '?') + '.' + step.bindTo + '":', e);
+        });
+      });
     });
-    return result;
-  };
 
-  _fns.entries = function (input) {
-    if (!input || typeof input !== 'object' || Array.isArray(input)) return [];
-    return Object.keys(input).map(function (k) { return { key: k, value: input[k] }; });
-  };
-
-  _fns.from_entries = function (input) {
-    if (!Array.isArray(input)) return {};
-    var obj = {};
-    input.forEach(function (item) { if (item.key != null) obj[item.key] = item.value; });
-    return obj;
-  };
-
-  _fns.length = function (input) {
-    if (Array.isArray(input)) return input.length;
-    if (typeof input === 'string') return input.length;
-    if (input && typeof input === 'object') return Object.keys(input).length;
-    return 0;
-  };
-
-  // ---- Lookup ----
-
-  _fns.get = function (input, _eval, opts) {
-    return _deepGet(input, opts.field || opts.path || '');
-  };
-
-  _fns.default = function (input, _eval, opts) {
-    return input != null ? input : opts.value;
-  };
-
-  _fns.coalesce = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    for (var i = 0; i < a.length; i++) { if (a[i] != null) return a[i]; }
-    return null;
-  };
-
-  // ---- Date ----
-
-  _fns.now = function () { return new Date().toISOString(); };
-
-  _fns.diff_days = function (input) {
-    var a = Array.isArray(input) ? input : [];
-    return a.length >= 2 ? Math.floor((new Date(a[0]) - new Date(a[1])) / 86400000) : 0;
-  };
-
-  _fns.format_date = function (input, _eval, opts) {
-    try {
-      var d = new Date(input);
-      if (opts.format === 'iso') return d.toISOString();
-      if (opts.format === 'date') return d.toLocaleDateString();
-      if (opts.format === 'time') return d.toLocaleTimeString();
-      return d.toLocaleDateString();
-    } catch (e) {
-      return String(input);
-    }
-  };
-
-  _fns.parse_date = function (input) {
-    try { return new Date(input).toISOString(); } catch (e) { return null; }
-  };
-
-  // ---- Type ----
-
-  _fns.to_number = function (input) { return Number(input) || 0; };
-  _fns.to_string = function (input) { return input != null ? String(input) : ''; };
-  _fns.to_bool   = function (input) { return !!input; };
-  _fns.type_of   = function (input) { return Array.isArray(input) ? 'array' : typeof input; };
-  _fns.is_null   = function (input) { return input == null; };
-  _fns.is_empty  = function (input) {
-    if (input == null) return true;
-    if (Array.isArray(input)) return input.length === 0;
-    if (typeof input === 'string') return input.length === 0;
-    if (typeof input === 'object') return Object.keys(input).length === 0;
-    return false;
-  };
+    return chain.then(function () { return node; });
+  }
 
   // ===========================================================================
-  // Expression evaluator
+  // eval — evaluate a single JSONata expression (async, returns Promise<value>)
   // ===========================================================================
 
-  var _customFns = {};
-
   function evalExpr(expr, node) {
-    if (expr == null) return expr;
-
-    // Literal values pass through
-    if (typeof expr !== 'object' || Array.isArray(expr)) return expr;
-
-    // Must have fn to be an expression
-    if (!expr.fn) return expr;
-
-    // Resolve input
-    var input = expr.input;
-    if (typeof input === 'string' && input.startsWith('state.')) {
-      input = resolve(node, input);
-    } else if (Array.isArray(input)) {
-      input = input.map(function (v) {
-        if (typeof v === 'string' && v.startsWith('state.')) return resolve(node, v);
-        if (v && typeof v === 'object' && v.fn) return evalExpr(v, node);
-        return v;
-      });
-    } else if (input && typeof input === 'object' && input.fn) {
-      input = evalExpr(input, node);
-    }
-
-    // Special: if
-    if (expr.fn === 'if') {
-      var cond = evalExpr(expr.cond, node);
-      if (cond) {
-        return (expr.then && typeof expr.then === 'object' && expr.then.fn) ? evalExpr(expr.then, node) : expr.then;
-      } else {
-        return (expr.else && typeof expr.else === 'object' && expr.else.fn) ? evalExpr(expr.else, node) : expr.else;
-      }
-    }
-
-    // Special: filter with where clause
-    if (expr.fn === 'filter' && Array.isArray(input) && expr.where) {
-      return input.filter(function (item) {
-        var tmp = { state: Object.assign({}, node.state, { $: item }) };
-        return evalExpr(expr.where, tmp);
-      });
-    }
-
-    // Special: map with apply clause
-    if (expr.fn === 'map' && Array.isArray(input) && expr.apply) {
-      return input.map(function (item) {
-        var tmp = { state: Object.assign({}, node.state, { $: item }) };
-        return evalExpr(expr.apply, tmp);
-      });
-    }
-
-    // Look up function
-    var fn = _customFns[expr.fn] || _fns[expr.fn];
-    if (!fn) {
-      console.warn('CardCompute: unknown function "' + expr.fn + '"');
-      return undefined;
+    if (typeof jsonata === 'undefined') {
+      console.error('CardCompute: JSONata not loaded.');
+      return Promise.resolve(undefined);
     }
-
-    return fn(input, evalExpr, expr);
+    var ctx = {
+      card_data: (node && node.card_data) || {},
+      requires: (node && node.requires) || {},
+      fetched_sources: (node && node._sourcesData) || {},
+      computed_values: (node && node.computed_values) || {},
+    };
+    return jsonata(expr).evaluate(ctx);
   }
 
   // ===========================================================================
-  // run — evaluate all compute declarations on a node
+  // resolve — synchronous deep-get from a node
   // ===========================================================================
 
-  function run(node) {
-    if (!node || !node.compute) return node;
-    if (!node.state) node.state = {};
-
-    var keys = Object.keys(node.compute);
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      try {
-        var val = evalExpr(node.compute[key], node);
-        _deepSet(node.state, key, val);
-      } catch (e) {
-        console.error('CardCompute.run error on "' + (node.id || '?') + '.' + key + '":', e);
-      }
+  function resolve(node, path) {
+    if (path && path.indexOf('fetched_sources.') === 0) {
+      return _deepGet((node && node._sourcesData) || {}, path.slice('fetched_sources.'.length));
     }
-
-    return node;
-  }
-
-  // ===========================================================================
-  // registerFunction — extend the vocabulary
-  // ===========================================================================
-
-  function registerFunction(name, fn) {
-    _customFns[name] = fn;
+    return _deepGet(node, path);
   }
 
   // ===========================================================================
-  // validate — lightweight structural validator for LiveCards nodes
+  // validate — lightweight structural validator (sync)
   // ===========================================================================
 
   var VALID_ELEMENT_KINDS = ['metric','table','chart','form','filter','list','notes','todo','alert','narrative','badge','text','markdown','custom'];
-  var VALID_SOURCE_KINDS = ['api','websocket','static','llm'];
   var VALID_STATUSES = ['fresh','stale','loading','error'];
-  var CARD_KEYS = ['id','type','meta','data','view','state','compute'];
-  var SOURCE_KEYS = ['id','type','meta','data','source','state','compute'];
+  var ALLOWED_KEYS = ['id','meta','requires','provides','view','card_data','compute','sources'];
 
   function validateNode(node) {
     var errors = [];
+
     if (!node || typeof node !== 'object' || Array.isArray(node)) {
       return { ok: false, errors: ['Node must be a non-null object'] };
     }
 
     if (typeof node.id !== 'string' || !node.id) errors.push('id: required, must be a non-empty string');
 
-    if (node.type !== 'card' && node.type !== 'source') {
-      errors.push('type: must be "card" or "source"');
-      return { ok: false, errors: errors };
-    }
-
-    var allowed = node.type === 'card' ? CARD_KEYS : SOURCE_KEYS;
     Object.keys(node).forEach(function (k) {
-      if (allowed.indexOf(k) === -1) errors.push('Unknown top-level key: "' + k + '"');
+      if (ALLOWED_KEYS.indexOf(k) === -1) errors.push('Unknown top-level key: "' + k + '"');
     });
 
-    // state
-    if (node.state == null || typeof node.state !== 'object' || Array.isArray(node.state)) {
-      errors.push('state: required, must be an object');
-    } else if (node.state.status != null && VALID_STATUSES.indexOf(node.state.status) === -1) {
-      errors.push('state.status: must be one of: ' + VALID_STATUSES.join(', '));
+    // card_data
+    if (node.card_data == null || typeof node.card_data !== 'object' || Array.isArray(node.card_data)) {
+      errors.push('card_data: required, must be an object');
     }
 
     // meta
     if (node.meta != null) {
-      if (typeof node.meta !== 'object' || Array.isArray(node.meta)) errors.push('meta: must be an object');
-      else {
+      if (typeof node.meta !== 'object' || Array.isArray(node.meta)) {
+        errors.push('meta: must be an object');
+      } else {
         if (node.meta.title != null && typeof node.meta.title !== 'string') errors.push('meta.title: must be a string');
         if (node.meta.tags != null && !Array.isArray(node.meta.tags)) errors.push('meta.tags: must be an array');
       }
     }
 
-    // data
-    if (node.data != null) {
-      if (typeof node.data !== 'object' || Array.isArray(node.data)) errors.push('data: must be an object');
-      else {
-        if (node.data.requires != null && !Array.isArray(node.data.requires)) errors.push('data.requires: must be an array');
-        if (node.data.provides != null && (typeof node.data.provides !== 'object' || Array.isArray(node.data.provides))) errors.push('data.provides: must be an object');
+    // requires
+    if (node.requires != null && !Array.isArray(node.requires)) errors.push('requires: must be an array of strings');
+
+    // provides
+    if (node.provides != null) {
+      if (!Array.isArray(node.provides)) {
+        errors.push('provides: must be an array of { bindTo, src } bindings');
+      } else {
+        node.provides.forEach(function (p, i) {
+          if (!p || typeof p !== 'object' || Array.isArray(p)) {
+            errors.push('provides[' + i + ']: must be an object with bindTo and src');
+          } else {
+            if (typeof p.bindTo !== 'string' || !p.bindTo) errors.push('provides[' + i + ']: missing required "bindTo" string');
+            if (typeof p.src !== 'string' || !p.src) errors.push('provides[' + i + ']: missing required "src" string');
+          }
+        });
       }
     }
 
-    // compute
+    // compute — ordered array of { bindTo, expr } steps
     if (node.compute != null) {
-      if (typeof node.compute !== 'object' || Array.isArray(node.compute)) errors.push('compute: must be an object');
-      else {
-        Object.keys(node.compute).forEach(function (key) {
-          var expr = node.compute[key];
-          if (!expr || typeof expr !== 'object' || Array.isArray(expr)) errors.push('compute.' + key + ': must be a compute expression object');
-          else if (!expr.fn) errors.push('compute.' + key + ': missing required "fn" property');
-          else if (!_fns[expr.fn] && !_customFns[expr.fn]) errors.push('compute.' + key + ': unknown function "' + expr.fn + '"');
+      if (!Array.isArray(node.compute)) {
+        errors.push('compute: must be an array of compute steps');
+      } else {
+        node.compute.forEach(function (step, i) {
+          if (!step || typeof step !== 'object' || Array.isArray(step)) {
+            errors.push('compute[' + i + ']: must be a compute step object');
+          } else {
+            if (typeof step.bindTo !== 'string' || !step.bindTo) errors.push('compute[' + i + ']: missing required "bindTo" property');
+            if (typeof step.expr !== 'string' || !step.expr) errors.push('compute[' + i + ']: missing required "expr" string (JSONata expression)');
+          }
         });
       }
     }
 
-    // Card-specific
-    if (node.type === 'card') {
-      if (node.source != null) errors.push('Card nodes must not have "source"');
-      if (node.view == null || typeof node.view !== 'object' || Array.isArray(node.view)) {
-        errors.push('view: required for card nodes, must be an object');
+    // sources
+    if (node.sources != null) {
+      if (!Array.isArray(node.sources)) {
+        errors.push('sources: must be an array');
+      } else {
+        node.sources.forEach(function (src, i) {
+          if (!src || typeof src !== 'object' || Array.isArray(src)) errors.push('sources[' + i + ']: must be an object');
+          else if (typeof src.bindTo !== 'string' || !src.bindTo) errors.push('sources[' + i + ']: missing required "bindTo" property');
+          else {
+            if (src.outputFile != null && typeof src.outputFile !== 'string') errors.push('sources[' + i + ']: outputFile must be a string');
+            if (src.optional != null && typeof src.optional !== 'boolean') errors.push('sources[' + i + ']: optional must be a boolean');
+          }
+        });
+      }
+    }
+
+    // view
+    if (node.view != null) {
+      if (typeof node.view !== 'object' || Array.isArray(node.view)) {
+        errors.push('view: must be an object');
       } else {
         if (!Array.isArray(node.view.elements) || node.view.elements.length === 0) {
           errors.push('view.elements: required, must be a non-empty array');
         } else {
           node.view.elements.forEach(function (elem, i) {
             if (!elem || typeof elem !== 'object') { errors.push('view.elements[' + i + ']: must be an object'); return; }
-            if (!elem.kind || typeof elem.kind !== 'string') errors.push('view.elements[' + i + '].kind: required');
-            else if (VALID_ELEMENT_KINDS.indexOf(elem.kind) === -1) errors.push('view.elements[' + i + '].kind: unknown "' + elem.kind + '"');
+            if (!elem.kind || typeof elem.kind !== 'string') {
+              errors.push('view.elements[' + i + '].kind: required, must be a string');
+            } else if (VALID_ELEMENT_KINDS.indexOf(elem.kind) === -1) {
+              errors.push('view.elements[' + i + '].kind: unknown kind "' + elem.kind + '". Valid: ' + VALID_ELEMENT_KINDS.join(', '));
+            }
           });
         }
       }
     }
 
-    // Source-specific
-    if (node.type === 'source') {
-      if (node.view != null) errors.push('Source nodes must not have "view"');
-      if (node.source == null || typeof node.source !== 'object' || Array.isArray(node.source)) {
-        errors.push('source: required for source nodes, must be an object');
-      } else {
-        if (!node.source.kind || VALID_SOURCE_KINDS.indexOf(node.source.kind) === -1) errors.push('source.kind: required, must be one of: ' + VALID_SOURCE_KINDS.join(', '));
-        if (typeof node.source.bindTo !== 'string' || !node.source.bindTo) errors.push('source.bindTo: required, must be a state path string');
-        else if (node.source.bindTo.indexOf('state.') !== 0) errors.push('source.bindTo: must start with "state."');
-      }
-    }
-
     return { ok: errors.length === 0, errors: errors };
   }
 
+  /**
+   * Enrich sources with execution context for template interpolation and prompt rendering.
+   * Pure function: no side effects, returns new enriched sources array.
+   * 
+   * @param {Array} sources - Array of source definitions
+   * @param {Object} context - Execution context containing requires, sourcesData, computed_values
+   * @returns {Array} New array of sources with _requires, _sourcesData, _computed_values attached
+   */
+  function enrichSources(sources, context) {
+    if (!sources || sources.length === 0) return [];
+    context = context || {};
+    
+    return sources.map(function (src) {
+      return Object.assign({}, src, {
+        _requires: context.requires || {},
+        _sourcesData: context.sourcesData || {},
+        _computed_values: context.computed_values || {},
+      });
+    });
+  }
+
   // ===========================================================================
   // Export
   // ===========================================================================
@@ -534,13 +260,7 @@
     eval: evalExpr,
     resolve: resolve,
     validate: validateNode,
-    registerFunction: registerFunction,
-    get functions() {
-      var all = {};
-      Object.keys(_fns).forEach(function (k) { all[k] = _fns[k]; });
-      Object.keys(_customFns).forEach(function (k) { all[k] = _customFns[k]; });
-      return all;
-    }
+    enrichSources: enrichSources,
   };
 
 }));