yaml-flow 5.2.6 → 5.3.0

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." }
       }
@@ -121,7 +126,7 @@
         "kind":      {
           "enum": ["metric", "table", "editable-table", "chart", "form", "filter", "list",
                    "notes", "todo", "alert", "narrative", "badge", "text",
-                   "markdown", "custom", "actions"]
+                   "markdown", "ref", "custom", "actions"]
         },
         "label":     { "type": "string", "description": "Heading above this element" },
         "className": { "type": "string", "description": "Bootstrap grid class, e.g. 'col-12 col-md-6'" },
@@ -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

@@ -70,6 +70,7 @@ function resolve(node, path) {
 var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
   "metric",
   "table",
+  "editable-table",
   "chart",
   "form",
   "filter",
@@ -81,9 +82,11 @@ var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
   "badge",
   "text",
   "markdown",
-  "custom"
+  "ref",
+  "custom",
+  "actions"
 ]);
-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 +112,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 +140,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 +203,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 +926,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 +969,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 +978,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
             timestamp: (/* @__PURE__ */ new Date()).toISOString()
           });
           drain();
+        }).finally(() => {
+          pendingHandlers.delete(p);
         });
+        pendingHandlers.add(p);
       }
     }
   }
@@ -1019,7 +1041,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 +1050,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
       drain();
+    }).finally(() => {
+      pendingHandlers.delete(p);
     });
+    pendingHandlers.add(p);
   }
   return {
     push(event) {
@@ -1142,7 +1167,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 +1192,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 +1338,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 +1355,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 +1364,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] = {