yaml-flow 4.0.0 → 5.1.0

package/dist/journal-DRfJiheM.d.cts

@@ -0,0 +1,28 @@
+import { f as GraphEvent } from './types-CMFSIjpc.cjs';
+
+/**
+ * Continuous Event Graph — Journal
+ *
+ * Append-only event log for the reactive layer.
+ * Handlers append events here; drain() reads and clears atomically.
+ *
+ * Adapter:
+ *   - MemoryJournal: in-process array (default)
+ */
+
+interface Journal {
+    /** Append an event to the journal. Safe to call from concurrent callbacks. */
+    append(event: GraphEvent): void;
+    /** Read all pending events and clear the journal atomically. */
+    drain(): GraphEvent[];
+    /** Number of pending events (for observability). */
+    readonly size: number;
+}
+declare class MemoryJournal implements Journal {
+    private buffer;
+    append(event: GraphEvent): void;
+    drain(): GraphEvent[];
+    get size(): number;
+}
+
+export { type Journal as J, MemoryJournal as M };

package/dist/journal-NLYuqege.d.ts

@@ -0,0 +1,28 @@
+import { f as GraphEvent } from './types-CMFSIjpc.js';
+
+/**
+ * Continuous Event Graph — Journal
+ *
+ * Append-only event log for the reactive layer.
+ * Handlers append events here; drain() reads and clears atomically.
+ *
+ * Adapter:
+ *   - MemoryJournal: in-process array (default)
+ */
+
+interface Journal {
+    /** Append an event to the journal. Safe to call from concurrent callbacks. */
+    append(event: GraphEvent): void;
+    /** Read all pending events and clear the journal atomically. */
+    drain(): GraphEvent[];
+    /** Number of pending events (for observability). */
+    readonly size: number;
+}
+declare class MemoryJournal implements Journal {
+    private buffer;
+    append(event: GraphEvent): void;
+    drain(): GraphEvent[];
+    get size(): number;
+}
+
+export { type Journal as J, MemoryJournal as M };

package/dist/{journal-B_2JnBMF.d.ts → live-cards-bridge-Or7fdEJV.d.ts}

@@ -1,5 +1,5 @@
-import { e as GraphEngineStore, T as TaskConfig, f as GraphEvent, G as GraphConfig } from './types-CMFSIjpc.js';
-import { L as LiveGraph, S as ScheduleResult, b as LiveGraphSnapshot } from './types-C2eJ7DAV.js';
+import { f as GraphEvent, T as TaskConfig, e as GraphEngineStore, G as GraphConfig } from './types-CMFSIjpc.js';
+import { b as LiveGraphSnapshot, L as LiveGraph, S as ScheduleResult } from './types-C2eJ7DAV.js';
 
 /**
  * Continuous Event Graph — Reactive Layer
@@ -20,7 +20,7 @@ import { L as LiveGraph, S as ScheduleResult, b as LiveGraphSnapshot } from './t
 
 /**
  * Deterministic hash of a data payload.
- * Recursively-sorted JSON → SHA-256 hex (first 16 chars for compactness).
+ * Recursively-sorted JSON → stable 64-bit hex.
  * Used to auto-compute dataHash when the handler doesn't provide one.
  * Exported so handler authors can pre-compute or test hashes.
  */
@@ -211,7 +211,7 @@ interface LiveCard {
         title?: string;
         tags?: string[];
     };
-    state?: Record<string, unknown>;
+    card_data?: Record<string, unknown>;
     compute?: {
         bindTo: string;
         fn: string;
@@ -219,14 +219,12 @@ interface LiveCard {
     }[];
     sources?: {
         cli?: string;
-        script?: string;
         bindTo: string;
         kind?: 'api' | 'websocket' | 'static' | 'llm';
         [key: string]: unknown;
     }[];
     optionalSources?: {
         cli?: string;
-        script?: string;
         bindTo: string;
         kind?: 'api' | 'websocket' | 'static' | 'llm';
         [key: string]: unknown;
@@ -315,29 +313,4 @@ interface LiveCardsToReactiveResult {
  */
 declare function liveCardsToReactiveGraph(input: LiveCard[] | LiveBoard, options?: LiveCardsToReactiveOptions): LiveCardsToReactiveResult;
 
-/**
- * Continuous Event Graph — Journal
- *
- * Append-only event log for the reactive layer.
- * Handlers append events here; drain() reads and clears atomically.
- *
- * Adapter:
- *   - MemoryJournal: in-process array (default)
- */
-
-interface Journal {
-    /** Append an event to the journal. Safe to call from concurrent callbacks. */
-    append(event: GraphEvent): void;
-    /** Read all pending events and clear the journal atomically. */
-    drain(): GraphEvent[];
-    /** Number of pending events (for observability). */
-    readonly size: number;
-}
-declare class MemoryJournal implements Journal {
-    private buffer;
-    append(event: GraphEvent): void;
-    drain(): GraphEvent[];
-    get size(): number;
-}
-
-export { type Journal as J, type LiveBoard as L, MemoryJournal as M, type ReactiveGraph as R, type TaskHandlerFn as T, type LiveCard as a, type LiveCardsToReactiveOptions as b, type LiveCardsToReactiveResult as c, type ReactiveGraphOptions as d, type TaskHandlerInput as e, type TaskHandlerReturn as f, createReactiveGraph as g, computeDataHash as h, liveCardsToReactiveGraph as l };
+export { type LiveBoard as L, type ReactiveGraph as R, type TaskHandlerFn as T, type LiveCard as a, type LiveCardsToReactiveOptions as b, type LiveCardsToReactiveResult as c, type ReactiveGraphOptions as d, type TaskHandlerInput as e, type TaskHandlerReturn as f, createReactiveGraph as g, computeDataHash as h, liveCardsToReactiveGraph as l };

package/dist/{journal-BJDjWb5Q.d.cts → live-cards-bridge-vGJ6tMzN.d.cts}

@@ -1,5 +1,5 @@
-import { e as GraphEngineStore, T as TaskConfig, f as GraphEvent, G as GraphConfig } from './types-CMFSIjpc.cjs';
-import { L as LiveGraph, S as ScheduleResult, b as LiveGraphSnapshot } from './types-BzLD8bjb.cjs';
+import { f as GraphEvent, T as TaskConfig, e as GraphEngineStore, G as GraphConfig } from './types-CMFSIjpc.cjs';
+import { b as LiveGraphSnapshot, L as LiveGraph, S as ScheduleResult } from './types-BzLD8bjb.cjs';
 
 /**
  * Continuous Event Graph — Reactive Layer
@@ -20,7 +20,7 @@ import { L as LiveGraph, S as ScheduleResult, b as LiveGraphSnapshot } from './t
 
 /**
  * Deterministic hash of a data payload.
- * Recursively-sorted JSON → SHA-256 hex (first 16 chars for compactness).
+ * Recursively-sorted JSON → stable 64-bit hex.
  * Used to auto-compute dataHash when the handler doesn't provide one.
  * Exported so handler authors can pre-compute or test hashes.
  */
@@ -211,7 +211,7 @@ interface LiveCard {
         title?: string;
         tags?: string[];
     };
-    state?: Record<string, unknown>;
+    card_data?: Record<string, unknown>;
     compute?: {
         bindTo: string;
         fn: string;
@@ -219,14 +219,12 @@ interface LiveCard {
     }[];
     sources?: {
         cli?: string;
-        script?: string;
         bindTo: string;
         kind?: 'api' | 'websocket' | 'static' | 'llm';
         [key: string]: unknown;
     }[];
     optionalSources?: {
         cli?: string;
-        script?: string;
         bindTo: string;
         kind?: 'api' | 'websocket' | 'static' | 'llm';
         [key: string]: unknown;
@@ -315,29 +313,4 @@ interface LiveCardsToReactiveResult {
  */
 declare function liveCardsToReactiveGraph(input: LiveCard[] | LiveBoard, options?: LiveCardsToReactiveOptions): LiveCardsToReactiveResult;
 
-/**
- * Continuous Event Graph — Journal
- *
- * Append-only event log for the reactive layer.
- * Handlers append events here; drain() reads and clears atomically.
- *
- * Adapter:
- *   - MemoryJournal: in-process array (default)
- */
-
-interface Journal {
-    /** Append an event to the journal. Safe to call from concurrent callbacks. */
-    append(event: GraphEvent): void;
-    /** Read all pending events and clear the journal atomically. */
-    drain(): GraphEvent[];
-    /** Number of pending events (for observability). */
-    readonly size: number;
-}
-declare class MemoryJournal implements Journal {
-    private buffer;
-    append(event: GraphEvent): void;
-    drain(): GraphEvent[];
-    get size(): number;
-}
-
-export { type Journal as J, type LiveBoard as L, MemoryJournal as M, type ReactiveGraph as R, type TaskHandlerFn as T, type LiveCard as a, type LiveCardsToReactiveOptions as b, type LiveCardsToReactiveResult as c, type ReactiveGraphOptions as d, type TaskHandlerInput as e, type TaskHandlerReturn as f, createReactiveGraph as g, computeDataHash as h, liveCardsToReactiveGraph as l };
+export { type LiveBoard as L, type ReactiveGraph as R, type TaskHandlerFn as T, type LiveCard as a, type LiveCardsToReactiveOptions as b, type LiveCardsToReactiveResult as c, type ReactiveGraphOptions as d, type TaskHandlerInput as e, type TaskHandlerReturn as f, createReactiveGraph as g, computeDataHash as h, liveCardsToReactiveGraph as l };

package/dist/schedule-CMcZe5Ny.d.ts

@@ -0,0 +1,21 @@
+import { L as LiveGraph, S as ScheduleResult } from './types-C2eJ7DAV.js';
+
+/**
+ * Continuous Event Graph — Schedule
+ *
+ * Pure read-only projection: LiveGraph → ScheduleResult
+ *
+ * Classifies every non-terminal task into one of:
+ *   - eligible: all requires satisfied, ready to dispatch
+ *   - pending: requires not yet met, but a viable producer exists (normal waiting)
+ *   - unresolved: requires not met, NO task in the graph can produce them (caller's problem)
+ *   - blocked: requires not met because the producing task FAILED (caller's problem)
+ */
+
+/**
+ * Compute the scheduling status of every task in the live graph.
+ * Pure function — no side effects.
+ */
+declare function schedule(live: LiveGraph): ScheduleResult;
+
+export { schedule as s };

package/dist/schedule-CiucyCan.d.cts

@@ -0,0 +1,21 @@
+import { L as LiveGraph, S as ScheduleResult } from './types-BzLD8bjb.cjs';
+
+/**
+ * Continuous Event Graph — Schedule
+ *
+ * Pure read-only projection: LiveGraph → ScheduleResult
+ *
+ * Classifies every non-terminal task into one of:
+ *   - eligible: all requires satisfied, ready to dispatch
+ *   - pending: requires not yet met, but a viable producer exists (normal waiting)
+ *   - unresolved: requires not met, NO task in the graph can produce them (caller's problem)
+ *   - blocked: requires not met because the producing task FAILED (caller's problem)
+ */
+
+/**
+ * Compute the scheduling status of every task in the live graph.
+ * Pure function — no side effects.
+ */
+declare function schedule(live: LiveGraph): ScheduleResult;
+
+export { schedule as s };

package/examples/browser/boards/portfolio-tracker/cards/holdings-table.json

@@ -3,7 +3,7 @@
   "meta": { "title": "Holdings Table" },
   "requires": ["holdings", "prices"],
   "provides": [{ "bindTo": "table", "src": "computed_values.table" }],
-  "state": {},
+  "card_data": {},
   "compute": [
     {
       "bindTo": "table",

package/examples/browser/boards/portfolio-tracker/cards/portfolio-form.json

@@ -1,8 +1,8 @@
 {
   "id": "portfolio-form",
   "meta": { "title": "Portfolio Holdings Form" },
-  "provides": [{ "bindTo": "holdings", "src": "state.holdings" }],
-  "state": {
+  "provides": [{ "bindTo": "holdings", "src": "card_data.holdings" }],
+  "card_data": {
     "holdings": [
       { "symbol": "AAPL", "qty": 50 },
       { "symbol": "MSFT", "qty": 30 }
@@ -10,7 +10,7 @@
   },
   "view": {
     "elements": [
-      { "kind": "table", "label": "Holdings", "data": { "bind": "state.holdings", "columns": ["symbol", "qty"] } }
+      { "kind": "table", "label": "Holdings", "data": { "bind": "card_data.holdings", "columns": ["symbol", "qty"] } }
     ]
   }
 }

package/examples/browser/boards/portfolio-tracker/cards/portfolio-value.json

@@ -3,7 +3,7 @@
   "meta": { "title": "Portfolio Total Value" },
   "requires": ["table"],
   "provides": [{ "bindTo": "totalValue", "src": "computed_values.totalValue" }],
-  "state": {},
+  "card_data": {},
   "compute": [
     { "bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)" }
   ],

package/examples/browser/boards/portfolio-tracker/cards/price-fetch.json

@@ -2,14 +2,14 @@
   "id": "price-fetch",
   "meta": { "title": "Fetch Market Prices" },
   "requires": ["holdings"],
-  "provides": [{ "bindTo": "prices", "src": "sources.prices" }],
-  "state": {},
+  "provides": [{ "bindTo": "prices", "src": "fetched_sources.prices" }],
+  "card_data": {},
   "sources": [
     { "cli": "node ../fetch-prices.js", "bindTo": "prices", "outputFile": "prices.json" }
   ],
   "view": {
     "elements": [
-      { "kind": "table", "label": "Market Prices", "data": { "bind": "sources.prices" } }
+      { "kind": "table", "label": "Market Prices", "data": { "bind": "fetched_sources.prices" } }
     ]
   }
 }

package/examples/browser/boards/portfolio-tracker/portfolio-tracker-task-executor.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Portfolio Tracker Task-Executor
+ * 
+ * Implements the run-source-fetch protocol for board-live-cards.
+ * This script acts as an external task-executor that can be registered via .task-executor file.
+ * 
+ * Contract:
+ *   portfolio-tracker-task-executor.js run-source-fetch --in <defFile> --out <resultFile> --err <errFile>
+ * 
+ * Input (--in file):
+ *   JSON source definition with { cli: "...", bindTo: "...", outputFile: "...", ... }
+ * 
+ * Output (on success):
+ *   --out file contains the execution result
+ *   Exit code: 0
+ * 
+ * Output (on error):
+ *   --err file contains error message
+ *   Exit code: 1
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+let subcommand = '';
+let inFile = '';
+let outFile = '';
+let errFile = '';
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === 'run-source-fetch') {
+    subcommand = 'run-source-fetch';
+  } else if (args[i] === '--in' && i + 1 < args.length) {
+    inFile = args[i + 1];
+  } else if (args[i] === '--out' && i + 1 < args.length) {
+    outFile = args[i + 1];
+  } else if (args[i] === '--err' && i + 1 < args.length) {
+    errFile = args[i + 1];
+  }
+}
+
+if (subcommand !== 'run-source-fetch' || !inFile || !outFile || !errFile) {
+  console.error('Usage: portfolio-tracker-task-executor.js run-source-fetch --in <defFile> --out <resultFile> --err <errFile>');
+  process.exit(1);
+}
+
+try {
+  // 1. Read source definition from --in file
+  console.log(`[portfolio-tracker-task-executor] Reading source definition from ${inFile}`);
+  const sourceDefStr = fs.readFileSync(inFile, 'utf-8');
+  const sourceDef = JSON.parse(sourceDefStr);
+  
+  // 2. Extract cli command from source definition
+  const { cli: sourceCliCommand } = sourceDef;
+  if (!sourceCliCommand) {
+    throw new Error('cli is required in source definition');
+  }
+  
+  console.log(`[portfolio-tracker-task-executor] Executing: ${sourceCliCommand}`);
+  
+  // 3. Execute source.cli synchronously and capture output
+  let output;
+  try {
+    output = execSync(sourceCliCommand, {
+      encoding: 'utf-8',
+      timeout: (sourceDef.timeout ?? 120) * 1000,  // Convert to ms
+      cwd: sourceDef.cwd,
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe'],  // Capture stdout/stderr
+    });
+  } catch (execErr) {
+    // Even on error, try to use what output we got
+    output = execErr.stdout || '';
+    if (!output) {
+      throw new Error(`Command execution failed: ${execErr.message}`);
+    }
+  }
+  
+  // 4. Write output to --out file
+  console.log(`[portfolio-tracker-task-executor] Writing result to ${outFile}`);
+  fs.writeFileSync(outFile, output.trim(), 'utf-8');
+  
+  console.log(`[portfolio-tracker-task-executor] Success`);
+  process.exit(0);
+} catch (error) {
+  // 3a. On error: write error message to --err file and exit non-zero
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  console.error(`[portfolio-tracker-task-executor] Error:`, errorMsg);
+  
+  fs.writeFileSync(errFile, errorMsg, 'utf-8');
+  process.exit(1);
+}

package/examples/browser/boards/portfolio-tracker/portfolio-tracker.js

@@ -6,7 +6,9 @@
  * This is a BLACK-BOX client of board-live-cards CLI.
  * It only calls CLI commands and does NOT inspect board internals.
  *
- * Usage: node portfolio-tracker.js
+ * Usage:
+ *   node portfolio-tracker.js
+ *   node portfolio-tracker.js --task-executor <path>
  */
 
 import * as fs from 'node:fs';
@@ -30,6 +32,28 @@ const BOARD = path.join(RUNTIME_ROOT, 'board-runtime');
 const CARDS = path.join(RUNTIME_ROOT, 'cards');
 const TMP_FILE = path.join(BOARD, 'tmp_file1');
 
+function parseArgs(argv) {
+  let taskExecutor;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--task-executor') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        console.error('[ERROR] Missing value for --task-executor');
+        process.exit(1);
+      }
+      taskExecutor = value;
+      i += 1;
+      continue;
+    }
+    console.error(`[ERROR] Unknown argument: ${arg}`);
+    process.exit(1);
+  }
+  return { taskExecutor };
+}
+
+const options = parseArgs(process.argv.slice(2));
+
 console.log(`Runtime root: ${RUNTIME_ROOT}`);
 
 function sleep(ms) {
@@ -131,7 +155,11 @@ function setupRuntimeCards() {
   console.log('\n=== T0: Init board ===');
   fs.rmSync(BOARD, { recursive: true, force: true });
 
-  cli('init', BOARD);
+  if (options.taskExecutor) {
+    cli('init', BOARD, '--task-executor', options.taskExecutor);
+  } else {
+    cli('init', BOARD);
+  }
   cli('add-cards', '--rg', BOARD, '--card-glob', path.join(CARDS, '*.json'));
 
   console.log('\n--- T0 Status (after add-cards) ---');
@@ -149,8 +177,8 @@ function setupRuntimeCards() {
   const portfolioFormV2 = {
     id: 'portfolio-form',
     meta: { title: 'Portfolio Holdings Form' },
-    provides: [{ bindTo: 'holdings', src: 'state.holdings' }],
-    state: {
+    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    card_data: {
       holdings: [
         { symbol: 'AAPL', qty: 50 },
         { symbol: 'MSFT', qty: 30 },
@@ -159,7 +187,7 @@ function setupRuntimeCards() {
     },
     view: {
       elements: [
-        { kind: 'table', label: 'Holdings', data: { bind: 'state.holdings', columns: ['symbol', 'qty'] } },
+        { kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } },
       ],
     },
   };