yaml-flow 5.2.6 → 5.2.8

package/browser/card-compute.js

@@ -126,7 +126,7 @@
 
   var VALID_ELEMENT_KINDS = ['metric','table','chart','form','filter','list','notes','todo','alert','narrative','badge','text','markdown','custom'];
   var VALID_STATUSES = ['fresh','stale','loading','error'];
-  var ALLOWED_KEYS = ['id','meta','requires','provides','view','card_data','compute','sources'];
+  var ALLOWED_KEYS = ['id','meta','requires','provides','view','card_data','compute','source_defs'];
 
   function validateNode(node) {
     var errors = [];
@@ -191,17 +191,17 @@
       }
     }
 
-    // sources
-    if (node.sources != null) {
-      if (!Array.isArray(node.sources)) {
-        errors.push('sources: must be an array');
+    // source_defs
+    if (node.source_defs != null) {
+      if (!Array.isArray(node.source_defs)) {
+        errors.push('source_defs: 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');
+        node.source_defs.forEach(function (src, i) {
+          if (!src || typeof src !== 'object' || Array.isArray(src)) errors.push('source_defs[' + i + ']: must be an object');
+          else if (typeof src.bindTo !== 'string' || !src.bindTo) errors.push('source_defs[' + 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');
+            if (src.outputFile != null && typeof src.outputFile !== 'string') errors.push('source_defs[' + i + ']: outputFile must be a string');
+            if (src.optional != null && typeof src.optional !== 'boolean') errors.push('source_defs[' + i + ']: optional must be a boolean');
           }
         });
       }
@@ -231,18 +231,18 @@
   }
 
   /**
-   * Enrich sources with execution context for template interpolation and prompt rendering.
-   * Pure function: no side effects, returns new enriched sources array.
+   * Enrich source_defs with execution context for template interpolation and prompt rendering.
+   * Pure function: no side effects, returns new enriched source_defs array.
    * 
-   * @param {Array} sources - Array of source definitions
+   * @param {Array} source_defs - 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
+   * @returns {Array} New array of source_defs with _requires, _sourcesData, _computed_values attached
    */
-  function enrichSources(sources, context) {
-    if (!sources || sources.length === 0) return [];
+  function enrichSources(source_defs, context) {
+    if (!source_defs || source_defs.length === 0) return [];
     context = context || {};
     
-    return sources.map(function (src) {
+    return source_defs.map(function (src) {
       return Object.assign({}, src, {
         _requires: context.requires || {},
         _sourcesData: context.sourcesData || {},

package/browser/live-cards.js

@@ -1,10 +1,10 @@
 // live-cards.js — LiveCards v3: Node-based Board/Canvas engine
 //
 // Schema: Each node has { id } required; all else optional.
-//   id, meta, card_data, requires, provides, sources, compute, view
-//   Nodes with view render as cards; nodes with sources but no view render as source pills in canvas.
+//   id, meta, card_data, requires, provides, source_defs, compute, view
+//   Nodes with view render as cards; nodes with source_defs but no view render as source pills in canvas.
 //   compute[] — ordered array of { bindTo, expr } JSONata steps → writes to node.computed_values (ephemeral)
-//   sources[] — open objects: only bindTo + outputFile matter to the engine; all other fields are
+//   source_defs[] — open objects: only bindTo + outputFile matter to the engine; all other fields are
 //               passed verbatim to the board's task-executor (--in JSON). Users define their own
 //               shape (kind, url, mailbox, channel, model, ...) per executor.
 //   requires[] — upstream node IDs; engine subscribes automatically
@@ -89,6 +89,15 @@ var LiveCard = (function () {
       .lc-files-modal-backdrop .modal-dialog { max-height:90vh; }
       .lc-files-modal-backdrop .modal-content { display:flex; flex-direction:column; max-height:90vh; }
       .lc-files-modal-backdrop .modal-body { overflow-y:auto; flex:1; min-height:200px; padding:1rem; }
+      .lc-simulation-card { background:#fdf6ec; border-color:#e0c97f !important; }
+      .lc-simulation-card .card-header { background:#faecc8; border-bottom-color:#e0c97f; }
+      .lc-gandalf-card { background:#eef4ff; border-color:#6ea4e0 !important; }
+      .lc-gandalf-card .card-header { background:#d7e8fa; border-bottom-color:#6ea4e0; cursor:pointer; user-select:none; }
+      .lc-gandalf-card .card-header:hover { background:#c8dcf5; }
+      .lc-gandalf-caret { transition:transform .2s; display:inline-flex; align-items:center; margin-left:auto; opacity:.6; flex-shrink:0; cursor:pointer; padding:2px; }
+      .lc-gandalf-caret:hover { opacity:1; }
+      .lc-gandalf-card.lc-collapsed .lc-gandalf-caret { transform:rotate(-90deg); }
+      .lc-gandalf-card.lc-collapsed .card-body { display:none !important; }
       @media (max-width:576px) {
         .lc-metric-value { font-size:1.5rem; }
         .lc-chart-wrap { min-height:150px; }
@@ -1847,6 +1856,68 @@ var LiveCard = (function () {
       };
     }
 
+    // ---- ref ----
+    // Indirection element: resolves a bind path to get the view definition,
+    // then dispatches to the real renderer. The resolved value may be:
+    //   - a string  → treated directly as the element kind ("table", "chart", etc.)
+    //   - an object → { kind, label, data: { columns, chartType, chartOptions, writeTo } }
+    //                 merged with static elemDef (static fields win for protection)
+    //   - null/undefined → falls back to elemDef.data.fallbackKind or shape-inferred kind
+    //
+    // Allowed kinds from resolved value (whitelist, unknown → "table"):
+    //   table, editable-table, chart, metric, list, badge, text, narrative, markdown
+    //
+    // Usage:
+    //   { "kind": "ref",
+    //     "data": { "bind": "fetched_sources.rebalance.proposed_trades",
+    //               "viewBind": "card_data.display_mode",
+    //               "fallbackKind": "table" } }
+    //
+    // viewBind can point to any namespace: card_data, fetched_sources, requires, computed_values.
+    // If the resolved view object contains a "bind" sub-path, that overrides data.bind.
+    const _REF_KIND_WHITELIST = new Set([
+      'table','editable-table','chart','metric','list','badge',
+      'text','narrative','markdown','form','filter','todo','alert',
+    ]);
+    function _renderRef(data, el, elemDef, node) {
+      const ed = elemDef.data || {};
+
+      // Resolve the view hint
+      const viewRaw = ed.viewBind ? _resolveBind(node, ed.viewBind) : undefined;
+
+      let resolvedKind, resolvedExtra;
+      if (typeof viewRaw === 'string' && viewRaw) {
+        resolvedKind  = viewRaw;
+        resolvedExtra = {};
+      } else if (viewRaw && typeof viewRaw === 'object' && !Array.isArray(viewRaw)) {
+        resolvedKind  = typeof viewRaw.kind === 'string' ? viewRaw.kind : undefined;
+        resolvedExtra = viewRaw.data && typeof viewRaw.data === 'object' ? viewRaw.data : {};
+      }
+
+      // Validate kind against whitelist; fall back to shape inference
+      if (!resolvedKind || !_REF_KIND_WHITELIST.has(resolvedKind)) {
+        resolvedKind = ed.fallbackKind && _REF_KIND_WHITELIST.has(ed.fallbackKind)
+          ? ed.fallbackKind
+          : (Array.isArray(data) ? 'table' : typeof data === 'string' ? 'text' : 'narrative');
+      }
+
+      // Build effective elemDef: resolved hints first, static elemDef fields override (card author wins)
+      const mergedData = Object.assign({}, resolvedExtra, ed);
+      delete mergedData.viewBind;
+      delete mergedData.fallbackKind;
+
+      // If the resolved hint provided its own bind path, honour it (but static ed.bind still wins)
+      if (!mergedData.bind && resolvedExtra.bind) mergedData.bind = resolvedExtra.bind;
+
+      const effectiveElemDef = Object.assign({}, elemDef, { kind: resolvedKind }, { data: mergedData });
+
+      // Re-resolve data using effective bind (may have changed)
+      const effectiveData = mergedData.bind ? _resolveBind(node, mergedData.bind) : data;
+
+      const renderer = _renderers[resolvedKind] || _renderers.table;
+      renderer(effectiveData, el, effectiveElemDef, node);
+    }
+
     // ---- Register built-in renderers ----
 
     _renderers.table          = _renderTable;
@@ -1867,6 +1938,7 @@ var LiveCard = (function () {
     _renderers['file-upload'] = _renderFileUpload;
     _renderers['chat']        = _renderChatEl;
     _renderers.actions        = _renderActions;
+    _renderers.ref            = _renderRef;
 
     // ===========================================================================
     // _renderElements — render all view.elements for a card node
@@ -2453,26 +2525,75 @@ var LiveCard = (function () {
 
     function _buildCardWrapper(node) {
       const wrap = document.createElement('div');
-      wrap.className = 'card shadow-sm h-100';
+      const card = node && node.card ? node.card : {};
+      const isSimulation = card.meta && card.meta.simulation === true;
+      const isGandalfCard  = card.meta && card.meta._gandalfCard === true;
+      const extraClass   = isSimulation ? ' lc-simulation-card' : (isGandalfCard ? ' lc-gandalf-card' : '');
+      wrap.className = 'card shadow-sm h-100' + extraClass;
       const header = document.createElement('div');
       header.className = 'card-header d-flex align-items-center gap-2 py-2';
-      const card = node && node.card ? node.card : {};
       const title = (card.meta && card.meta.title) || node.id;
       const tags = (card.meta && card.meta.tags) || [];
       let badgeHtml = '';
-      if ((card.sources && card.sources.length) && !card.view) {
-        var src = card.sources[0] || {};
+      if ((card.source_defs && card.source_defs.length) && !card.view) {
+        var src = card.source_defs[0] || {};
         badgeHtml = '<span class="badge bg-info text-dark ms-auto">' + _esc(src.kind || 'source') + '</span>';
       } else if (tags.length) {
         badgeHtml = tags.map(t => '<span class="badge bg-secondary ms-1">' + _esc(t) + '</span>').join('');
       }
       header.innerHTML = '<strong class="small">' + _esc(title) + '</strong>' + badgeHtml;
-      
+
+      // Gandalf cards: collapsible via caret — caret gets its own click listener,
+      // header is left alone for dragging in canvas mode.
+      if (isGandalfCard) {
+        const caret = document.createElement('span');
+        caret.className = 'lc-gandalf-caret';
+        caret.title = 'Collapse / expand';
+        caret.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>';
+        header.appendChild(caret);
+
+        const storageKey = 'lc-gandalf-collapsed:' + (node.id || title);
+        if (sessionStorage.getItem(storageKey) === '1') {
+          wrap.classList.add('lc-collapsed');
+          header.dataset.gandalfCollapsed = '1';
+        }
+
+        caret.addEventListener('click', function(e) {
+          e.stopPropagation();
+          const cardEl = caret.closest('.lc-gandalf-card') || wrap;
+          cardEl.classList.toggle('lc-collapsed');
+          sessionStorage.setItem(storageKey, cardEl.classList.contains('lc-collapsed') ? '1' : '0');
+        });
+        caret.addEventListener('pointerdown', e => e.stopPropagation()); // prevent drag start
+      }
+      if (isSimulation) {
+        const simBtns = document.createElement('span');
+        simBtns.className = 'd-inline-flex align-items-center gap-1 ms-auto';
+
+        const pinBtn = document.createElement('button');
+        pinBtn.className = 'btn btn-sm btn-outline-success lc-sim-pin';
+        pinBtn.style.cssText = 'padding: 2px 6px;';
+        pinBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 17v5"/><path d="M9 2h6l-1 7h-4L9 2z"/><path d="M6 17h12l-2-4H8L6 17z"/></svg>';
+        pinBtn.title = 'Pin this simulation card';
+        pinBtn.dataset.nodeId = node.id;
+
+        const discardBtn = document.createElement('button');
+        discardBtn.className = 'btn btn-sm btn-outline-danger lc-sim-discard';
+        discardBtn.style.cssText = 'padding: 2px 6px;';
+        discardBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>';
+        discardBtn.title = 'Discard this simulation card';
+        discardBtn.dataset.nodeId = node.id;
+
+        simBtns.appendChild(pinBtn);
+        simBtns.appendChild(discardBtn);
+        header.appendChild(simBtns);
+      }
+
       // Add dev mode code icon button if devMode is enabled
       if (devMode.current) {
         const codeBtn = document.createElement('button');
         codeBtn.className = 'btn btn-sm btn-outline-secondary';
-        codeBtn.style.cssText = 'padding: 2px 6px; margin-left: auto;';
+        codeBtn.style.cssText = 'padding: 2px 6px;' + (isSimulation ? '' : ' margin-left: auto;');
         codeBtn.innerHTML = '&lt;/&gt;';
         codeBtn.title = 'Inspect card data';
         codeBtn.addEventListener('click', function(e) {
@@ -2495,7 +2616,7 @@ var LiveCard = (function () {
       const status = (node.card_data && node.card_data.status) || 'fresh';
       const card = node && node.card ? node.card : {};
       const title = (card.meta && card.meta.title) || node.id;
-      const kind = (card.sources && card.sources[0] && card.sources[0].kind) || 'source';
+      const kind = (card.source_defs && card.source_defs[0] && card.source_defs[0].kind) || 'source';
       el.innerHTML = `<div class="lc-source-pill shadow-sm">
         ${_statusDot(status)}
         <span class="fw-medium">${_esc(title)}</span>
@@ -2615,7 +2736,7 @@ var LiveCard = (function () {
       nodeList.forEach(node => {
         const pos = _positions[node.id] || { x: 0, y: 0 };
 
-        if ((!node.card || !node.card.view) && (node.card && node.card.sources && node.card.sources.length)) {
+        if ((!node.card || !node.card.view) && (node.card && node.card.source_defs && node.card.source_defs.length)) {
           const el = _buildSourcePill(node);
           el.dataset.nodeId = node.id;
           el.style.left = pos.x + 'px';
@@ -2625,7 +2746,10 @@ var LiveCard = (function () {
           _makeDraggable(el, node);
         } else {
           const el = document.createElement('div');
-          el.className = 'lc-canvas-card card shadow-sm';
+          const isSimCanvas   = node.card && node.card.meta && node.card.meta.simulation === true;
+          const isGandalfCanvas = node.card && node.card.meta && node.card.meta._gandalfCard === true;
+          const canvasExtra   = isSimCanvas ? ' lc-simulation-card' : (isGandalfCanvas ? ' lc-gandalf-card' : '');
+          el.className = 'lc-canvas-card card shadow-sm' + canvasExtra;
           el.dataset.nodeId = node.id;
           el.style.left = pos.x + 'px';
           el.style.top  = pos.y + 'px';
@@ -2633,6 +2757,9 @@ var LiveCard = (function () {
 
           const { wrap, body } = _buildCardWrapper(node);
           while (wrap.firstChild) el.appendChild(wrap.firstChild);
+          // Re-apply collapsed state: in canvas mode el is the card container, not wrap
+          const movedHeader = el.querySelector('.card-header');
+          if (movedHeader && movedHeader.dataset.gandalfCollapsed === '1') el.classList.add('lc-collapsed');
           canvasInner.appendChild(el);
           nodeMap[node.id] = { node, colEl: el, bodyEl: body };
           engine.render(node, body, { showNotes: false, showChat: false });

package/browser/live-cards.schema.json

@@ -80,10 +80,10 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["bindTo", "src"],
+        "required": ["bindTo", "ref"],
         "properties": {
           "bindTo": { "type": "string", "description": "Token name published downstream" },
-          "src":    { "type": "string", "description": "Path to read value from (card_data.*, requires.*, fetched_sources.*, computed_values.*)" }
+          "ref":    { "type": "string", "description": "Path to read value from (card_data.*, requires.*, fetched_sources.*, computed_values.*)" }
         }
       },
       "description": "Explicit bindings exposing computed or card_data values downstream as named tokens"
@@ -100,14 +100,19 @@
     },
 
     "source_def": {
-      "description": "One source entry. The engine requires 'bindTo' (compute namespace key) and 'outputFile' (delivery signal path). bindTo and outputFile must be unique across all sources in a card. Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
+      "description": "One source entry. The engine requires 'bindTo' (compute namespace key) and 'outputFile' (delivery signal path). bindTo and outputFile must be unique across all source_defs in a card. Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
       "type": "object",
       "required": ["bindTo", "outputFile"],
       "additionalProperties": true,
       "properties": {
         "bindTo":     { "type": "string",  "description": "Key under fetched_sources.* available in compute expressions" },
         "outputFile": { "type": "string",  "description": "Board-relative path the executor writes its JSON result to. Presence of this file signals delivery." },
-        "optionalForCompletionGating":   { "type": "boolean", "default": false, "description": "When true this source does not gate card completion. Default false when absent, so sources are completion-gating by default." },
+        "projections": {
+          "type": "object",
+          "description": "Named data projections from card_data or requires, evaluated before the executor is called. Each key is a ref name; each value is a JSONata expression rooted at card_data or requires. The resolved values are passed to the executor as _projections. fetched_sources, computed_values, and source_defs are not accessible here — sources run before those exist.",
+          "additionalProperties": { "type": "string" }
+        },
+        "optionalForCompletionGating":   { "type": "boolean", "default": false, "description": "When true this source does not gate card completion. Default false when absent, so source_defs are completion-gating by default." },
         "timeout":    { "type": "integer", "minimum": 0, "default": 120000, "description": "Executor/script timeout in ms. Default: 120 000 (2 min)." },
         "script":     { "type": "string",  "description": "Legacy direct-run: shell command executed when no .task-executor is registered. stdout is captured as the result." }
       }
@@ -215,7 +220,7 @@
   },
 
   "title": "LiveCard",
-  "description": "A unified card node. Behavior depends on which sections are present (sources, compute, view, etc.)",
+  "description": "A unified card node. Behavior depends on which sections are present (source_defs, compute, view, etc.)",
   "type": "object",
   "required": ["id"],
   "additionalProperties": false,
@@ -258,22 +263,22 @@
         },
         "llm_task_completion_inference": {
           "type": "object",
-          "description": "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard sources → compute → provides pattern for LLM-based signals.",
+          "description": "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard source_defs → compute → provides pattern for LLM-based signals.",
           "properties": {
             "inferenceRequested": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request was initiated" },
             "inferenceCompletedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request completed" },
             "isTaskCompleted": { "type": "boolean", "description": "Whether the task is considered complete by the adapter" },
             "reasoning": { "type": "string", "description": "Explanation of completion decision" },
-            "evidence": { "type": "array", "description": "Supporting evidence from sources/compute" }
+            "evidence": { "type": "array", "description": "Supporting evidence from source_defs/compute" }
           },
           "additionalProperties": true
         }
       },
       "additionalProperties": true
     },
-    "sources": {
+    "source_defs": {
       "type": "array",
-      "description": "Source entries. Each entry is passed verbatim to the board's .task-executor (registered via init --task-executor) as the --in JSON file. The executor fetches/generates the data and writes JSON to --out. If no executor is registered, the built-in executor runs the entry's 'cli' command directly. Sources gate completion by default. Set optionalForCompletionGating: true for enrichment-only sources that should not block task-completed.",
+      "description": "Source entries. Each entry is passed verbatim to the board's .task-executor (registered via init --task-executor) as the --in JSON file. The executor fetches/generates the data and writes JSON to --out. If no executor is registered, the built-in executor runs the entry's 'cli' command directly. Sources gate completion by default. Set optionalForCompletionGating: true for enrichment-only source_defs that should not block task-completed.",
       "items": { "$ref": "#/definitions/source_def" }
     },
     "compute": {

package/dist/board-livegraph-runtime/index.cjs

@@ -83,7 +83,7 @@ var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
   "markdown",
   "custom"
 ]);
-var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "meta", "requires", "provides", "view", "card_data", "compute", "sources"]);
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "meta", "requires", "provides", "view", "card_data", "compute", "source_defs"]);
 function validateNode(node) {
   const errors = [];
   if (!node || typeof node !== "object" || Array.isArray(node)) {
@@ -109,15 +109,15 @@ function validateNode(node) {
   if (n.requires != null && !Array.isArray(n.requires)) errors.push("requires: must be an array of strings");
   if (n.provides != null) {
     if (!Array.isArray(n.provides)) {
-      errors.push("provides: must be an array of { bindTo, src } bindings");
+      errors.push("provides: must be an array of { bindTo, ref } bindings");
     } else {
       n.provides.forEach((p, i) => {
         if (!p || typeof p !== "object" || Array.isArray(p)) {
-          errors.push(`provides[${i}]: must be an object with bindTo and src`);
+          errors.push(`provides[${i}]: must be an object with bindTo and ref`);
         } else {
           const b = p;
           if (typeof b.bindTo !== "string" || !b.bindTo) errors.push(`provides[${i}]: missing required "bindTo" string`);
-          if (typeof b.src !== "string" || !b.src) errors.push(`provides[${i}]: missing required "src" string`);
+          if (typeof b.ref !== "string" || !b.ref) errors.push(`provides[${i}]: missing required "ref" string`);
         }
       });
     }
@@ -137,35 +137,35 @@ function validateNode(node) {
       });
     }
   }
-  if (n.sources != null) {
-    if (!Array.isArray(n.sources)) {
-      errors.push("sources: must be an array");
+  if (n.source_defs != null) {
+    if (!Array.isArray(n.source_defs)) {
+      errors.push("source_defs: must be an array");
     } else {
       const bindTos = /* @__PURE__ */ new Set();
       const outputFiles = /* @__PURE__ */ new Set();
-      n.sources.forEach((src, i) => {
+      n.source_defs.forEach((src, i) => {
         if (!src || typeof src !== "object" || Array.isArray(src)) {
-          errors.push(`sources[${i}]: must be an object`);
+          errors.push(`source_defs[${i}]: must be an object`);
         } else {
           const s = src;
           if (typeof s.bindTo !== "string" || !s.bindTo) {
-            errors.push(`sources[${i}]: missing required "bindTo" property`);
+            errors.push(`source_defs[${i}]: missing required "bindTo" property`);
           } else {
             if (bindTos.has(s.bindTo)) {
-              errors.push(`sources[${i}]: bindTo "${s.bindTo}" is not unique across sources`);
+              errors.push(`source_defs[${i}]: bindTo "${s.bindTo}" is not unique across source_defs`);
             }
             bindTos.add(s.bindTo);
           }
           if (typeof s.outputFile !== "string" || !s.outputFile) {
-            errors.push(`sources[${i}]: missing required "outputFile" property`);
+            errors.push(`source_defs[${i}]: missing required "outputFile" property`);
           } else {
             if (outputFiles.has(s.outputFile)) {
-              errors.push(`sources[${i}]: outputFile "${s.outputFile}" is not unique across sources`);
+              errors.push(`source_defs[${i}]: outputFile "${s.outputFile}" is not unique across source_defs`);
             }
             outputFiles.add(s.outputFile);
           }
           if (s.optionalForCompletionGating != null && typeof s.optionalForCompletionGating !== "boolean") {
-            errors.push(`sources[${i}]: optionalForCompletionGating must be a boolean`);
+            errors.push(`source_defs[${i}]: optionalForCompletionGating must be a boolean`);
           }
         }
       });
@@ -200,14 +200,29 @@ function validateNode(node) {
   }
   return { ok: errors.length === 0, errors };
 }
-function enrichSources(sources, context) {
-  if (!sources || sources.length === 0) return [];
-  return sources.map((src) => ({
-    ...src,
-    _requires: context.requires ?? {},
-    _sourcesData: context.sourcesData ?? {},
-    _computed_values: context.computed_values ?? {}
-  }));
+async function enrichSources(source_defs, context) {
+  if (!source_defs || source_defs.length === 0) return [];
+  const evalCtx = {
+    card_data: context.card_data ?? {},
+    requires: context.requires ?? {}
+  };
+  return Promise.all(
+    source_defs.map(async (src) => {
+      const _projections = {};
+      if (src.projections && typeof src.projections === "object" && !Array.isArray(src.projections)) {
+        for (const [key, expr] of Object.entries(src.projections)) {
+          if (typeof expr === "string" && expr.trim().length > 0) {
+            try {
+              _projections[key] = await jsonata2__default.default(expr).evaluate(evalCtx);
+            } catch {
+              _projections[key] = void 0;
+            }
+          }
+        }
+      }
+      return { ...src, _projections };
+    })
+  );
 }
 var CardCompute = {
   run,
@@ -908,6 +923,7 @@ function createReactiveGraph(configOrLive, options, executionId) {
   const inputQueue = new MemoryJournal();
   let live = "state" in configOrLive && "config" in configOrLive ? configOrLive : createLiveGraph(configOrLive, executionId);
   let disposed = false;
+  const pendingHandlers = /* @__PURE__ */ new Set();
   const handlers = new Map(Object.entries(initialHandlers));
   const internalJournal = new MemoryJournal();
   let draining = false;
@@ -950,7 +966,7 @@ function createReactiveGraph(configOrLive, options, executionId) {
         const taskState = live.state.tasks[taskName];
         if (!taskState || taskState.status !== "running") continue;
         const callbackToken = encodeCallbackToken(taskName);
-        runPipeline(taskName, callbackToken, update).catch((error) => {
+        const p = runPipeline(taskName, callbackToken, update).catch((error) => {
           if (disposed) return;
           internalJournal.append({
             type: "task-failed",
@@ -959,7 +975,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
             timestamp: (/* @__PURE__ */ new Date()).toISOString()
           });
           drain();
+        }).finally(() => {
+          pendingHandlers.delete(p);
         });
+        pendingHandlers.add(p);
       }
     }
   }
@@ -1019,7 +1038,7 @@ function createReactiveGraph(configOrLive, options, executionId) {
     });
     drain();
     const callbackToken = encodeCallbackToken(taskName);
-    runPipeline(taskName, callbackToken).catch((error) => {
+    const p = runPipeline(taskName, callbackToken).catch((error) => {
       if (disposed) return;
       internalJournal.append({
         type: "task-failed",
@@ -1028,7 +1047,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
       drain();
+    }).finally(() => {
+      pendingHandlers.delete(p);
     });
+    pendingHandlers.add(p);
   }
   return {
     push(event) {
@@ -1142,7 +1164,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
     getSchedule() {
       return schedule(live);
     },
-    dispose() {
+    async dispose(options2) {
+      if (options2?.wait && pendingHandlers.size > 0) {
+        await Promise.allSettled([...pendingHandlers]);
+      }
       disposed = true;
     }
   };
@@ -1164,7 +1189,7 @@ function toTaskConfig(card) {
 function buildTokenProviders(cards) {
   const tokenToCardId = /* @__PURE__ */ new Map();
   for (const [cardId, card] of cards.entries()) {
-    const bindings = card.provides && card.provides.length > 0 ? card.provides : [{ bindTo: cardId, src: "card_data" }];
+    const bindings = card.provides && card.provides.length > 0 ? card.provides : [{ bindTo: cardId, ref: "card_data" }];
     for (const binding of bindings) tokenToCardId.set(binding.bindTo, cardId);
   }
   return tokenToCardId;
@@ -1310,14 +1335,14 @@ function createBoardLiveGraphRuntime(input, options = {}) {
         requiresData[token] = providesData2[token];
       }
       const sourcesData = {};
-      if (card.sources && card.sources.length > 0) {
+      if (card.source_defs && card.source_defs.length > 0) {
         const adapter = sourceAdapters[cardId] ?? defaultSourceAdapter;
         const fetched = taskExecutor ? await taskExecutor({ card, input: inputArgs }) : adapter ? await adapter({ card, input: inputArgs }) : void 0;
         if (fetched && typeof fetched === "object") {
-          for (const src of card.sources) {
+          for (const src of card.source_defs) {
             if (Object.prototype.hasOwnProperty.call(fetched, src.bindTo)) {
               sourcesData[src.bindTo] = fetched[src.bindTo];
-            } else if (card.sources.length === 1) {
+            } else if (card.source_defs.length === 1) {
               sourcesData[src.bindTo] = fetched;
             }
           }
@@ -1327,7 +1352,7 @@ function createBoardLiveGraphRuntime(input, options = {}) {
         id: card.id,
         card_data: deepClone(card.card_data ?? {}),
         requires: requiresData,
-        sources: card.sources,
+        source_defs: card.source_defs,
         compute: card.compute
       };
       computeNode._sourcesData = sourcesData;
@@ -1336,8 +1361,8 @@ function createBoardLiveGraphRuntime(input, options = {}) {
       }
       const providesData = {};
       if (card.provides && card.provides.length > 0) {
-        for (const { bindTo, src } of card.provides) {
-          providesData[bindTo] = CardCompute.resolve(computeNode, src);
+        for (const { bindTo, ref } of card.provides) {
+          providesData[bindTo] = CardCompute.resolve(computeNode, ref);
         }
       } else {
         providesData[card.id] = {