yaml-flow 5.2.5 → 5.2.8

package/dist/card-compute/index.d.cts

@@ -58,13 +58,16 @@ declare function validateLiveCardDefinition(node: unknown): ValidationResult;
  * Expressions are evaluated against { card_data, requires, fetched_sources, computed_values }.
  * computed_values is ephemeral — never persisted to disk.
  */
-/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. Both bindTo and outputFile must be unique across sources in a card. */
+/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. Both bindTo and outputFile must be unique across source_defs in a card. */
 interface ComputeSource {
     bindTo: string;
     outputFile: string;
     cli?: string;
     script?: string;
     optionalForCompletionGating?: boolean;
+    /** Named data projections: each key maps to a JSONata expression rooted at card_data or requires.
+     *  The engine evaluates these before spawning the executor and passes results as _projections. */
+    projections?: Record<string, string>;
     [key: string]: unknown;
 }
 /** Options for CardCompute.run() */
@@ -82,7 +85,7 @@ interface ComputeNode {
     id?: string;
     card_data?: Record<string, unknown>;
     requires?: Record<string, unknown>;
-    sources?: ComputeSource[];
+    source_defs?: ComputeSource[];
     compute?: ComputeStep[];
     computed_values?: Record<string, unknown>;
     /** Ephemeral: populated by run() from sourcesData option. Never persisted. */
@@ -113,18 +116,20 @@ interface ValidationResult {
 }
 declare function validateNode(node: unknown): ValidationResult;
 /**
- * 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 sources - Array of source definitions
+ * @param source_defs - Array of source definitions
  * @param context - Execution context containing requires, sourcesData, computed_values
- * @returns New array of sources with _requires, _sourcesData, _computed_values attached
+ * @returns Promise resolving to a new array of source_defs with _projections attached.
+ *          Each _projections entry is the evaluated result of the corresponding projections expression.
  */
-declare function enrichSources(sources: any[] | undefined, context: {
+declare function enrichSources(source_defs: any[] | undefined, context: {
+    card_data?: Record<string, any>;
     requires?: Record<string, any>;
     sourcesData?: Record<string, any>;
     computed_values?: Record<string, any>;
-}): any[];
+}): Promise<any[]>;
 declare const CardCompute: {
     run: typeof run;
     eval: typeof evalExpr;

package/dist/card-compute/index.d.ts

@@ -58,13 +58,16 @@ declare function validateLiveCardDefinition(node: unknown): ValidationResult;
  * Expressions are evaluated against { card_data, requires, fetched_sources, computed_values }.
  * computed_values is ephemeral — never persisted to disk.
  */
-/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. Both bindTo and outputFile must be unique across sources in a card. */
+/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. Both bindTo and outputFile must be unique across source_defs in a card. */
 interface ComputeSource {
     bindTo: string;
     outputFile: string;
     cli?: string;
     script?: string;
     optionalForCompletionGating?: boolean;
+    /** Named data projections: each key maps to a JSONata expression rooted at card_data or requires.
+     *  The engine evaluates these before spawning the executor and passes results as _projections. */
+    projections?: Record<string, string>;
     [key: string]: unknown;
 }
 /** Options for CardCompute.run() */
@@ -82,7 +85,7 @@ interface ComputeNode {
     id?: string;
     card_data?: Record<string, unknown>;
     requires?: Record<string, unknown>;
-    sources?: ComputeSource[];
+    source_defs?: ComputeSource[];
     compute?: ComputeStep[];
     computed_values?: Record<string, unknown>;
     /** Ephemeral: populated by run() from sourcesData option. Never persisted. */
@@ -113,18 +116,20 @@ interface ValidationResult {
 }
 declare function validateNode(node: unknown): ValidationResult;
 /**
- * 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 sources - Array of source definitions
+ * @param source_defs - Array of source definitions
  * @param context - Execution context containing requires, sourcesData, computed_values
- * @returns New array of sources with _requires, _sourcesData, _computed_values attached
+ * @returns Promise resolving to a new array of source_defs with _projections attached.
+ *          Each _projections entry is the evaluated result of the corresponding projections expression.
  */
-declare function enrichSources(sources: any[] | undefined, context: {
+declare function enrichSources(source_defs: any[] | undefined, context: {
+    card_data?: Record<string, any>;
     requires?: Record<string, any>;
     sourcesData?: Record<string, any>;
     computed_values?: Record<string, any>;
-}): any[];
+}): Promise<any[]>;
 declare const CardCompute: {
     run: typeof run;
     eval: typeof evalExpr;

package/dist/card-compute/index.js

@@ -6522,10 +6522,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"
@@ -6540,14 +6540,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." }
       }
@@ -6667,7 +6672,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,
@@ -6710,22 +6715,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: {
@@ -6743,8 +6748,8 @@ var live_cards_schema_default = {
 // src/card-compute/schema-validator.ts
 var import_ajv = __toESM(require_ajv());
 var _compiled = 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;
@@ -6809,22 +6814,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);
         }
@@ -6854,10 +6859,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) {
@@ -6944,7 +6987,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)) {
@@ -6970,15 +7013,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`);
         }
       });
     }
@@ -6998,35 +7041,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`);
           }
         }
       });
@@ -7061,14 +7104,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(expr).evaluate(evalCtx);
+            } catch {
+              _projections[key] = void 0;
+            }
+          }
+        }
+      }
+      return { ...src, _projections };
+    })
+  );
 }
 var CardCompute = {
   run,