yaml-flow 5.2.6 → 5.2.8

package/dist/index.cjs

@@ -10969,6 +10969,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;
@@ -11011,7 +11012,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",
@@ -11020,7 +11021,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
             timestamp: (/* @__PURE__ */ new Date()).toISOString()
           });
           drain();
+        }).finally(() => {
+          pendingHandlers.delete(p);
         });
+        pendingHandlers.add(p);
       }
     }
   }
@@ -11080,7 +11084,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",
@@ -11089,7 +11093,10 @@ function createReactiveGraph(configOrLive, options, executionId) {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
       drain();
+    }).finally(() => {
+      pendingHandlers.delete(p);
     });
+    pendingHandlers.add(p);
   }
   return {
     push(event) {
@@ -11203,7 +11210,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;
     }
   };
@@ -11670,10 +11680,10 @@ var live_cards_schema_default = {
       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"
@@ -11688,14 +11698,19 @@ var live_cards_schema_default = {
       }
     },
     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 \u2014 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 \u2014 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 \u2014 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: 12e4, 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." }
       }
@@ -11815,7 +11830,7 @@ var live_cards_schema_default = {
     }
   },
   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,
@@ -11858,22 +11873,22 @@ var live_cards_schema_default = {
         },
         llm_task_completion_inference: {
           type: "object",
-          description: "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard sources \u2192 compute \u2192 provides pattern for LLM-based signals.",
+          description: "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard source_defs \u2192 compute \u2192 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: {
@@ -11891,8 +11906,8 @@ var live_cards_schema_default = {
 // src/card-compute/schema-validator.ts
 var import_ajv3 = __toESM(require_ajv());
 var _compiled3 = null;
-var NAMESPACE_REFERENCE_RE = /\b(card_data|requires|fetched_sources|computed_values|sources)\b/g;
-var ROOT_PATH_NAMESPACE_RE = /^\s*(card_data|requires|fetched_sources|computed_values|sources)(\.|$)/;
+var NAMESPACE_REFERENCE_RE = /\b(card_data|requires|fetched_sources|computed_values|source_defs)\b/g;
+var ROOT_PATH_NAMESPACE_RE = /^\s*(card_data|requires|fetched_sources|computed_values|source_defs)(\.|$)/;
 function referencedNamespaces(expression) {
   const namespaces = /* @__PURE__ */ new Set();
   let match;
@@ -11957,22 +11972,22 @@ function validateLiveCardSchema(node) {
     return `${path}: ${e.message ?? "unknown error"}`;
   });
   if (node && typeof node === "object" && !Array.isArray(node)) {
-    const sources = node.sources;
-    if (Array.isArray(sources)) {
+    const source_defs = node.source_defs;
+    if (Array.isArray(source_defs)) {
       const bindTos = /* @__PURE__ */ new Set();
       const outputFiles = /* @__PURE__ */ new Set();
-      sources.forEach((src, i) => {
+      source_defs.forEach((src, i) => {
         if (!src || typeof src !== "object" || Array.isArray(src)) return;
         const s = src;
         if (typeof s.bindTo === "string" && s.bindTo) {
           if (bindTos.has(s.bindTo)) {
-            errors.push(`/sources/${i}/bindTo: bindTo "${s.bindTo}" must be unique across all sources`);
+            errors.push(`/source_defs/${i}/bindTo: bindTo "${s.bindTo}" must be unique across all source_defs`);
           }
           bindTos.add(s.bindTo);
         }
         if (typeof s.outputFile === "string" && s.outputFile) {
           if (outputFiles.has(s.outputFile)) {
-            errors.push(`/sources/${i}/outputFile: outputFile "${s.outputFile}" must be unique across all sources`);
+            errors.push(`/source_defs/${i}/outputFile: outputFile "${s.outputFile}" must be unique across all source_defs`);
           }
           outputFiles.add(s.outputFile);
         }
@@ -12002,10 +12017,48 @@ function validateLiveCardRuntimeExpressions(node) {
       );
     });
   }
+  const VALID_PROVIDES_SRC_NAMESPACES = /* @__PURE__ */ new Set([
+    "card_data",
+    "requires",
+    "fetched_sources",
+    "computed_values"
+  ]);
+  const provides = asRecord.provides;
+  if (Array.isArray(provides)) {
+    provides.forEach((entry, i) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
+      const ref = entry.ref;
+      if (typeof ref !== "string" || ref.trim().length === 0) return;
+      const rootNamespace = parseRootPathNamespace(ref);
+      if (rootNamespace === null) {
+        errors.push(`/provides/${i}/ref: path "${ref}" must start with a valid namespace (${[...VALID_PROVIDES_SRC_NAMESPACES].join(", ")})`);
+      } else if (!VALID_PROVIDES_SRC_NAMESPACES.has(rootNamespace)) {
+        errors.push(`/provides/${i}/ref: disallowed namespace "${rootNamespace}" in path "${ref}" (valid: ${[...VALID_PROVIDES_SRC_NAMESPACES].join(", ")})`);
+      }
+    });
+  }
   const view = asRecord.view;
   if (view && typeof view === "object" && !Array.isArray(view)) {
     walkViewPathReferences(view, "/view", errors);
   }
+  const VALID_PROJECTION_NAMESPACES = /* @__PURE__ */ new Set(["card_data", "requires"]);
+  const source_defs = asRecord.source_defs;
+  if (Array.isArray(source_defs)) {
+    source_defs.forEach((srcDef, i) => {
+      if (!srcDef || typeof srcDef !== "object" || Array.isArray(srcDef)) return;
+      const projections = srcDef.projections;
+      if (!projections || typeof projections !== "object" || Array.isArray(projections)) return;
+      for (const [key, exprVal] of Object.entries(projections)) {
+        if (typeof exprVal !== "string" || exprVal.trim().length === 0) continue;
+        validateJsonataExprWithNamespaces(
+          exprVal,
+          `/source_defs/${i}/projections/${key}`,
+          VALID_PROJECTION_NAMESPACES,
+          errors
+        );
+      }
+    });
+  }
   return { ok: errors.length === 0, errors };
 }
 function validateLiveCard(node) {
@@ -12092,7 +12145,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)) {
@@ -12118,15 +12171,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`);
         }
       });
     }
@@ -12146,35 +12199,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`);
           }
         }
       });
@@ -12209,14 +12262,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,
@@ -12259,7 +12327,7 @@ function liveCardsToReactiveGraph(input, options = {}) {
   const allTokens = /* @__PURE__ */ new Set();
   const tokenToCardId = /* @__PURE__ */ new Map();
   for (const card of cards) {
-    for (const binding of card.provides ?? [{ bindTo: card.id, src: "card_data" }]) {
+    for (const binding of card.provides ?? [{ bindTo: card.id, ref: "card_data" }]) {
       allTokens.add(binding.bindTo);
       tokenToCardId.set(binding.bindTo, card.id);
     }
@@ -12273,7 +12341,7 @@ function liveCardsToReactiveGraph(input, options = {}) {
     }
     tasks[card.id] = {
       requires: requires.length > 0 ? requires : void 0,
-      provides: (card.provides ?? [{ bindTo: card.id, src: "card_data" }]).map((p) => p.bindTo),
+      provides: (card.provides ?? [{ bindTo: card.id, ref: "card_data" }]).map((p) => p.bindTo),
       taskHandlers: [card.id],
       description: card.meta?.title ?? card.id
     };
@@ -12294,7 +12362,7 @@ function liveCardsToReactiveGraph(input, options = {}) {
     graphRef.resolveCallback(token, data, errors);
   };
   for (const card of cards) {
-    if (card.sources && card.sources.length > 0) {
+    if (card.source_defs && card.source_defs.length > 0) {
       handlers[card.id] = buildSourceHandler(card, sourceHandlers, defaultSourceHandler, sharedState, getResolve);
     } else {
       handlers[card.id] = buildCardHandler(card, cardHandlers, sharedState, cardMap, tokenToCardId, getResolve);
@@ -12358,8 +12426,8 @@ function buildCardHandler(card, cardHandlers, sharedState, _cardMap, tokenToCard
     let resultData;
     if (card.provides && card.provides.length > 0) {
       resultData = {};
-      for (const { bindTo, src } of card.provides) {
-        resultData[bindTo] = CardCompute.resolve(computeNode, src);
+      for (const { bindTo, ref } of card.provides) {
+        resultData[bindTo] = CardCompute.resolve(computeNode, ref);
       }
     } else {
       resultData = { ...computeNode.card_data, ...computeNode.computed_values };
@@ -12387,7 +12455,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;
@@ -12443,14 +12511,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;
             }
           }
@@ -12460,7 +12528,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;
@@ -12469,8 +12537,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] = {