yaml-flow 5.2.5 → 5.2.8

package/examples/example-board/scripts/copilot_wrapper.bat

@@ -0,0 +1,157 @@
+@echo off
+setlocal enabledelayedexpansion
+
+REM Copilot Wrapper - Manages session isolation for GitHub Copilot CLI
+REM Usage: copilot_wrapper.bat <output_file> <session_dir> <working_dir> <request_or_file> <result_type> [agent_name] [model] [result_shape_file]
+REM
+REM If request_or_file starts with @, it's treated as a file path containing the prompt.
+REM Otherwise, it's treated as the prompt string directly.
+REM result_type: "raw" to return plain text, "json" to extract JSON (passed to clean_copilot_output.ps1)
+REM agent_name: name of the agent for log files (optional)
+REM model: passed to copilot with --model flag (optional)
+
+SET "OUTPUT_FILE=%~1"
+SET "SESSION_DIR=%~2"
+SET "WORKING_DIR=%~3"
+SET "REQUEST_OR_FILE=%~4"
+SET "RESULT_TYPE=%~5"
+SET "AGENT_NAME=%~6"
+SET "MODEL=%~7"
+SET "RESULT_SHAPE_FILE=%~8"
+
+if not defined RESULT_TYPE SET "RESULT_TYPE=raw"
+
+SET "PROMPT_FILE="
+SET "REQUEST="
+echo !REQUEST_OR_FILE! | findstr /b "@" >nul
+if !errorlevel! equ 0 (
+    SET "PROMPT_FILE=!REQUEST_OR_FILE:~1!"
+) else (
+    SET "REQUEST=!REQUEST_OR_FILE!"
+)
+
+SET "_WD_HASH=!WORKING_DIR:\=!"
+SET "_WD_HASH=!_WD_HASH:/=!"
+SET "_WD_HASH=!_WD_HASH::=!"
+SET "_WD_HASH=!_WD_HASH:.=!"
+SET "_WD_HASH=!_WD_HASH: =!"
+SET "COPILOT_BASE=%TEMP%\copilot-sessions\!_WD_HASH!"
+SET "COPILOT_CACHE=%COPILOT_BASE%\session-state"
+SET "LOCK_FILE=%COPILOT_BASE%\copilot.lock"
+SET "UUID_FILE=%SESSION_DIR%\session.uuid"
+
+if not exist "%COPILOT_BASE%" mkdir "%COPILOT_BASE%"
+if not exist "%COPILOT_CACHE%" mkdir "%COPILOT_CACHE%"
+if not exist "%SESSION_DIR%" mkdir "%SESSION_DIR%"
+
+if exist "%LOCK_FILE%" (
+    for /f "tokens=*" %%a in ('powershell -NoProfile -Command "if ((Get-Item '%LOCK_FILE%').LastWriteTime -lt (Get-Date).AddMinutes(-20)) { Write-Output 'STALE' }"') do (
+        if "%%a"=="STALE" (
+            del "%LOCK_FILE%" 2>nul
+        )
+    )
+)
+:acquire_lock
+2>nul (
+    >"%LOCK_FILE%" (
+        echo %DATE% %TIME%
+    )
+) || (
+    timeout /t 1 /nobreak >nul
+    goto acquire_lock
+)
+
+SET "SESSION_UUID="
+if exist "%UUID_FILE%" (
+    set /p SESSION_UUID=<"%UUID_FILE%"
+) else (
+    for /f "tokens=*" %%a in ('powershell -NoProfile -Command "[guid]::NewGuid().ToString()"') do (
+        SET "SESSION_UUID=%%a"
+    )
+    echo !SESSION_UUID!>"%UUID_FILE%"
+)
+
+SET "CACHE_SESSION_PATH=%COPILOT_CACHE%\!SESSION_UUID!"
+
+if exist "%SESSION_DIR%\workspace.yaml" (
+    if exist "!CACHE_SESSION_PATH!" rmdir /s /q "!CACHE_SESSION_PATH!" 2>nul
+    mkdir "!CACHE_SESSION_PATH!" 2>nul
+    for %%f in ("%SESSION_DIR%\*") do (
+        if /i not "%%~nxf"=="session.uuid" (
+            move /y "%%f" "!CACHE_SESSION_PATH!\" >nul 2>&1
+        )
+    )
+    for /d %%d in ("%SESSION_DIR%\*") do (
+        robocopy "%%d" "!CACHE_SESSION_PATH!\%%~nxd" /E /MOVE /NFL /NDL /NJH /NJS >nul 2>&1
+    )
+)
+
+cd /d "%WORKING_DIR%"
+
+SET "MODEL_FLAG="
+if defined MODEL (
+    SET "MODEL_FLAG=--model !MODEL!"
+)
+
+if defined PROMPT_FILE (
+    type "!PROMPT_FILE!" | call copilot --allow-all --resume !SESSION_UUID! !MODEL_FLAG! > "%OUTPUT_FILE%" 2>&1
+) else (
+    call copilot -p "%REQUEST%" --allow-all --resume !SESSION_UUID! !MODEL_FLAG! > "%OUTPUT_FILE%" 2>&1
+)
+
+SET "LOG_DIR=%COPILOT_BASE%\copilot-logs"
+if not exist "!LOG_DIR!" mkdir "!LOG_DIR!"
+SET "LOG_AGENT=unknown"
+if defined AGENT_NAME SET "LOG_AGENT=!AGENT_NAME!"
+for /f "tokens=*" %%t in ('powershell -NoProfile -Command "Get-Date -Format 'yyyyMMdd-HHmmss'"') do SET "LOG_TS=%%t"
+SET "LOG_FILE=!LOG_DIR!\!LOG_AGENT!_!LOG_TS!.log"
+echo === PROMPT (!LOG_TS!) === > "!LOG_FILE!"
+echo Agent: !LOG_AGENT! >> "!LOG_FILE!"
+echo ResultType: !RESULT_TYPE! >> "!LOG_FILE!"
+echo Working Dir: %WORKING_DIR% >> "!LOG_FILE!"
+echo --- >> "!LOG_FILE!"
+if defined PROMPT_FILE (
+    type "!PROMPT_FILE!" >> "!LOG_FILE!" 2>nul
+) else (
+    echo %REQUEST% >> "!LOG_FILE!"
+)
+echo. >> "!LOG_FILE!"
+echo === RESPONSE === >> "!LOG_FILE!"
+type "%OUTPUT_FILE%" >> "!LOG_FILE!" 2>nul
+echo. >> "!LOG_FILE!"
+echo === END === >> "!LOG_FILE!"
+for /f "skip=50 tokens=*" %%f in ('dir /b /o-d "!LOG_DIR!\!LOG_AGENT!_*.log" 2^>nul') do (
+    del "!LOG_DIR!\%%f" 2>nul
+)
+
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0copilot_wrapper_helper.ps1" "%OUTPUT_FILE%" "!RESULT_TYPE!" "!RESULT_SHAPE_FILE!"
+
+REM If JSON extraction failed (exit 2) and result_type is json, retry once with a
+REM correction prompt in the same session (--resume SESSION_UUID continues the conversation).
+SET "PS1_EXIT=!ERRORLEVEL!"
+if "!PS1_EXIT!"=="2" (
+    SET "RETRY_PROMPT_FILE=%TEMP%\copilot-retry-!RANDOM!.txt"
+    (
+        echo Your previous response did not contain a valid JSON object.
+        echo Please respond with ONLY the JSON object — no markdown, no explanation, no preamble.
+        echo Start your response with { and end with }.
+    ) > "!RETRY_PROMPT_FILE!"
+    type "!RETRY_PROMPT_FILE!" | call copilot --allow-all --resume !SESSION_UUID! !MODEL_FLAG! > "%OUTPUT_FILE%" 2>&1
+    del "!RETRY_PROMPT_FILE!" 2>nul
+    REM Re-run PS1 with -IsRetry so it writes skeleton on second failure rather than exit 2
+    powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0copilot_wrapper_helper.ps1" "%OUTPUT_FILE%" "!RESULT_TYPE!" "!RESULT_SHAPE_FILE!" "-IsRetry"
+)
+
+if exist "!CACHE_SESSION_PATH!" (
+    for %%f in ("!CACHE_SESSION_PATH!\*") do (
+        move /y "%%f" "%SESSION_DIR%\" >nul 2>&1
+    )
+    for /d %%d in ("!CACHE_SESSION_PATH!\*") do (
+        robocopy "%%d" "%SESSION_DIR%\%%~nxd" /E /MOVE /NFL /NDL /NJH /NJS >nul 2>&1
+    )
+    rmdir "!CACHE_SESSION_PATH!" 2>nul
+)
+
+del "%LOCK_FILE%" 2>nul
+
+endlocal

package/examples/example-board/scripts/copilot_wrapper_helper.ps1

@@ -0,0 +1,190 @@
+# clean_copilot_output.ps1
+# Cleans copilot CLI output: filters noise lines and stats footer.
+# Called by copilot_wrapper.bat after copilot runs and after logging (raw log preserved).
+#
+# Usage: clean_copilot_output.ps1 <output_file> <result_type> [result_shape_file]
+#   output_file       - file containing raw copilot output; overwritten with cleaned result
+#   result_type=raw   - strip noise + stats, write plain text back to output_file
+#   result_type=json  - extract first JSON object whose keys match result_shape;
+#                       if result_shape_file is absent, accepts any valid JSON object
+#   result_shape_file - (json result_type only) JSON file whose top-level keys are required in output
+#
+# raw  result_type: right for chat responses and task executor source_defs.
+# json result_type: right for structured calls where the input contained {prompt, result_shape}.
+
+param(
+    [Parameter(Mandatory)][string]$OutputFile,
+    [Parameter(Mandatory)][string]$ResultType,
+    [string]$ResultShapeFile = '',
+    # When $true (retry pass), write shape-skeleton fallback instead of exiting with code 2.
+    # On first pass, exit 2 signals the caller (.bat) to retry with a correction prompt.
+    [switch]$IsRetry
+)
+
+if (-not (Test-Path $OutputFile)) { exit 0 }
+
+$raw = [IO.File]::ReadAllText($OutputFile, [Text.Encoding]::UTF8)
+if ([string]::IsNullOrWhiteSpace($raw)) { exit 0 }
+
+# --- Step 1: Filter noise lines ---
+$lines = $raw -split "`r?`n" | Where-Object {
+    $_ -notmatch "^error: unknown option '--no-warnings'" -and
+    $_ -notmatch "^Try 'copilot --help' for more information"
+}
+$cleaned = ($lines -join "`n").Trim()
+
+# --- Step 1b: Strip copilot-cli tool operation lines ---
+# These are internal tool invocations that leak into output:
+#   ● Create/Read/Edit/List directory/Glob/Check ...
+#   X Read ... (failed tool ops)
+#   $ Get-Content/Set-Content ... (PowerShell invocations)
+#   └ N lines/files found
+#   ├ ... (tree lines)
+#   "The agent decision has been simulated and saved to ..."
+#   session-state file paths
+$noiseLines = New-Object System.Collections.Generic.List[string]
+$contentLines2 = New-Object System.Collections.Generic.List[string]
+foreach ($line in ($cleaned -split "`n")) {
+    $t = $line.TrimStart()
+    if ($t -match '^[\u25cf\u2022] ' -or           # ● bullet tool ops
+        $t -match '^X ' -or                          # X failed tool ops
+        $t -match '^\$ ' -or                         # $ shell commands
+        $t -match '^[\u2514\u251c]' -or              # └ ├ tree lines
+        $t -match 'session-state.*\.json' -or        # session-state file projections
+        $t -match 'agent.decision has been simulated' -or
+        $t -match 'has been simulated and saved' -or
+        $t -match '^\d+ (files?|lines?|matches?) found$' -or  # "3 files found"
+        $t -match '^No matches found$' -or
+        $t -match '^Path does not exist$' -or
+        $t -match '^\d+ lines?( read)?$') {          # "1 line read"
+        $noiseLines.Add($line)
+    } else {
+        $contentLines2.Add($line)
+    }
+}
+$cleaned = ($contentLines2 -join "`n").Trim()
+
+# Write noise to sidecar file for upstream visibility
+$NoiseFile = $OutputFile + '.noise'
+if ($noiseLines.Count -gt 0) {
+    $noiseContent = "STRIPPED_LINES=$($noiseLines.Count)`n" + ($noiseLines -join "`n")
+    [IO.File]::WriteAllText($NoiseFile, $noiseContent, [Text.Encoding]::UTF8)
+} elseif (Test-Path $NoiseFile) {
+    Remove-Item $NoiseFile -Force
+}
+
+# --- Step 2: Strip trailing usage stats ---
+$statsPrefixes = @('Total usage est:', 'API time spent:', 'Total session time:',
+                    'Total code changes:', 'Breakdown by AI model:', 'Session:',
+                    'Changes', 'Requests', 'Tokens')
+$resultLines = New-Object System.Collections.Generic.List[string]
+$hitStats = $false
+foreach ($line in $cleaned -split "`n") {
+    if (-not $hitStats) {
+        foreach ($sp in $statsPrefixes) {
+            if ($line.TrimStart().StartsWith($sp)) { $hitStats = $true; break }
+        }
+    }
+    if (-not $hitStats) { $resultLines.Add($line) }
+}
+$cleaned = ($resultLines -join "`n").Trim()
+
+# --- raw result_type: write cleaned plain text and exit ---
+if ($ResultType -eq 'raw') {
+    if ([string]::IsNullOrWhiteSpace($cleaned)) {
+        [IO.File]::WriteAllText($OutputFile, '', [Text.Encoding]::UTF8)
+    } else {
+        [IO.File]::WriteAllText($OutputFile, $cleaned, [Text.Encoding]::UTF8)
+    }
+    exit 0
+}
+
+# --- json result_type: extract JSON object matching result_shape ---
+
+# Load result_shape keys (if provided) to use as required-key filter
+$shapeKeys = @()
+if ($ResultShapeFile -and (Test-Path $ResultShapeFile)) {
+    try {
+        $shape = [IO.File]::ReadAllText($ResultShapeFile, [Text.Encoding]::UTF8) | ConvertFrom-Json -ErrorAction Stop
+        $shapeKeys = @($shape.PSObject.Properties.Name)
+    } catch {}
+}
+
+if ([string]::IsNullOrWhiteSpace($cleaned)) {
+    $fallback = if ($shapeKeys.Count -gt 0) {
+        $obj = [ordered]@{}
+        foreach ($k in $shapeKeys) { $obj[$k] = $null }
+        $obj | ConvertTo-Json -Depth 2 -Compress
+    } else { '{}' }
+    [IO.File]::WriteAllText($OutputFile, $fallback, [Text.Encoding]::UTF8)
+    exit 0
+}
+
+# Helper: check if a parsed object has all required shape keys
+function Test-ShapeMatch($obj) {
+    if ($shapeKeys.Count -eq 0) { return $true }  # no shape constraint — accept any JSON object
+    foreach ($k in $shapeKeys) {
+        if (-not $obj.PSObject.Properties[$k]) { return $false }
+    }
+    return $true
+}
+
+$foundJson = $null
+
+# 1: Look in ```json fenced blocks first
+if ($cleaned -match '(?s)```json\s*(.*?)```') {
+    try {
+        $obj = $Matches[1].Trim() | ConvertFrom-Json -ErrorAction Stop
+        if (Test-ShapeMatch $obj) { $foundJson = $Matches[1].Trim() }
+    } catch {}
+}
+
+# 2: Scan for bare JSON objects
+if (-not $foundJson) {
+    $depth = 0; $start = -1
+    for ($i = 0; $i -lt $cleaned.Length; $i++) {
+        if ($cleaned[$i] -eq '{') {
+            if ($depth -eq 0) { $start = $i }
+            $depth++
+        } elseif ($cleaned[$i] -eq '}') {
+            $depth--
+            if ($depth -eq 0 -and $start -ge 0) {
+                $candidate = $cleaned.Substring($start, $i - $start + 1)
+                try {
+                    $obj = $candidate | ConvertFrom-Json -ErrorAction Stop
+                    if (Test-ShapeMatch $obj) {
+                        $foundJson = $candidate
+                        break
+                    }
+                } catch {}
+                $start = -1
+            }
+        }
+    }
+}
+
+if ($foundJson) {
+    [IO.File]::WriteAllText($OutputFile, $foundJson, [Text.Encoding]::UTF8)
+} else {
+    # No matching JSON found — record raw in noise file for upstream visibility
+    $NoiseFile = $OutputFile + '.noise'
+    $fallbackNoise = "FALLBACK=no_json_match`nSHAPE_KEYS=$($shapeKeys -join ',')`nRAW_LENGTH=$($cleaned.Length)`n---`n$cleaned"
+    if (Test-Path $NoiseFile) {
+        $existing = [IO.File]::ReadAllText($NoiseFile, [Text.Encoding]::UTF8)
+        [IO.File]::WriteAllText($NoiseFile, "$existing`n$fallbackNoise", [Text.Encoding]::UTF8)
+    } else {
+        [IO.File]::WriteAllText($NoiseFile, $fallbackNoise, [Text.Encoding]::UTF8)
+    }
+    if ($IsRetry) {
+        # Second pass — write shape-skeleton so the card gets a structured (empty) result
+        $fallback = if ($shapeKeys.Count -gt 0) {
+            $obj = [ordered]@{}
+            foreach ($k in $shapeKeys) { $obj[$k] = $null }
+            $obj | ConvertTo-Json -Depth 2 -Compress
+        } else { '{}' }
+        [IO.File]::WriteAllText($OutputFile, $fallback, [Text.Encoding]::UTF8)
+    } else {
+        # First pass — exit 2 to signal the caller (.bat) to retry with a correction prompt
+        exit 2
+    }
+}

package/examples/example-board/scripts/workiq_wrapper.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * workiq_wrapper.mjs — Calls the demo-server /api/workiq/ask proxy endpoint.
+ *
+ * Usage: node workiq_wrapper.mjs <out_file>
+ *   WORKIQ_QUERY env var:       the interpolated query string
+ *   WORKIQ_SERVER_URL env var:  base URL of demo-server (default: http://127.0.0.1:7799)
+ *
+ * The demo-server has a TTY so workiq can produce output there.
+ * Writes raw WorkIQ response text to <out_file>.
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+
+const outFile = process.argv[2];
+const query = process.env.WORKIQ_QUERY;
+const serverBase = (process.env.WORKIQ_SERVER_URL || 'http://127.0.0.1:7799').replace(/\/$/, '');
+
+if (!outFile) { console.error('workiq_wrapper: missing <out_file> argument'); process.exit(1); }
+if (!query)   { console.error('workiq_wrapper: WORKIQ_QUERY env var not set'); process.exit(1); }
+
+const body = JSON.stringify({ query });
+const url = new URL('/api/workiq/ask', serverBase);
+
+const reqOptions = {
+  hostname: url.hostname,
+  port: url.port || 80,
+  path: url.pathname,
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+};
+
+const req = http.request(reqOptions, (res) => {
+  let data = '';
+  res.on('data', chunk => { data += chunk; });
+  res.on('end', () => {
+    try {
+      const json = JSON.parse(data);
+      if (json.error) {
+        fs.writeFileSync(outFile, `workiq error: ${json.error}`, 'utf8');
+        process.exit(1);
+      }
+      fs.writeFileSync(outFile, json.response || '', 'utf8');
+      process.exit(0);
+    } catch {
+      fs.writeFileSync(outFile, data, 'utf8');
+      process.exit(0);
+    }
+  });
+});
+
+req.on('error', (err) => {
+  fs.writeFileSync(outFile, `workiq proxy error: ${err.message}\nIs demo-server running at ${serverBase}?`, 'utf8');
+  process.exit(1);
+});
+
+req.setTimeout(60_000, () => {
+  req.destroy();
+  fs.writeFileSync(outFile, 'workiq proxy timeout after 60s', 'utf8');
+  process.exit(1);
+});
+
+req.write(body);
+req.end();
+

package/examples/npm-libs/continuous-event-graph/live-cards-board.ts

@@ -46,9 +46,9 @@ const cards: LiveCard[] = [
     card_data: {},
     data: { requires: ['market-feed'] },
     compute: {
-      total: { fn: 'sum', input: 'sources.market-feed.prices' },
-      avg: { fn: 'avg', input: 'sources.market-feed.prices' },
-      count: { fn: 'count', input: 'sources.market-feed.prices' },
+      total: { fn: 'sum', input: 'source_defs.market-feed.prices' },
+      avg: { fn: 'avg', input: 'source_defs.market-feed.prices' },
+      count: { fn: 'count', input: 'source_defs.market-feed.prices' },
     },
   },
   {
@@ -132,8 +132,8 @@ const board: LiveBoard = {
       card_data: {},
       data: { requires: ['equity-feed', 'bond-feed'] },
       compute: {
-        equity_total: { fn: 'sum', input: 'sources.equity-feed.prices' },
-        bond_total: { fn: 'sum', input: 'sources.bond-feed.yields' },
+        equity_total: { fn: 'sum', input: 'source_defs.equity-feed.prices' },
+        bond_total: { fn: 'sum', input: 'source_defs.bond-feed.yields' },
       },
     },
     {

package/examples/npm-libs/continuous-event-graph/soc-incident-board.ts

@@ -2,7 +2,7 @@
  * SOC Incident Board — Correct Model
  *
  * A Security Operations Center dashboard demonstrating:
- *   • External data sources (alert-feed, threat-intel) — NO handlers
+ *   • External data source_defs (alert-feed, threat-intel) — NO handlers
  *   • Handler-driven compute (severity-score, blast-radius)
  *   • Fire-and-forget side effects (slack-alert, create-ticket)
  *   • Per-task refreshStrategy: 'once' on create-ticket (no duplicate tickets)
@@ -76,7 +76,7 @@ const config: GraphConfig = {
     refreshStrategy: 'data-changed',
   },
   tasks: {
-    // External sources — no handler, data pushed externally
+    // External source_defs — no handler, data pushed externally
     'alert-feed': {
       provides: ['alert-feed'],
       description: 'SIEM alert feed (external push)',
@@ -203,7 +203,7 @@ console.log(`create-ticket: refreshStrategy 'once' (no duplicate tickets)\n`);
 
 console.log(`--- T0: Initial incident (${siemAlerts.length} alerts, ${threatIntelV1.length} IOCs) ---\n`);
 
-// Push both sources simultaneously — engine stores data, auto-hash computed
+// Push both source_defs simultaneously — engine stores data, auto-hash computed
 graph.pushAll([
   {
     type: 'task-completed',

package/examples/npm-libs/event-graph/research-pipeline.ts

@@ -29,18 +29,18 @@ const graph: GraphConfig = {
   },
   tasks: {
     fetch_sources: {
-      provides: ['raw-sources'],
+      provides: ['raw-asources'],
       description: 'Fetch source documents from the web',
     },
     analyse_sentiment: {
-      requires: ['raw-sources'],
+      requires: ['raw-asources'],
       provides: ['sentiment-result'],
-      description: 'Run sentiment analysis on sources',
+      description: 'Run sentiment analysis on source_defs',
     },
     analyse_entities: {
-      requires: ['raw-sources'],
+      requires: ['raw-asources'],
       provides: ['entity-result'],
-      description: 'Extract named entities from sources',
+      description: 'Extract named entities from source_defs',
     },
     merge_analysis: {
       requires: ['sentiment-result', 'entity-result'],

package/examples/npm-libs/graph-of-graphs/multi-stage-etl.ts

@@ -13,7 +13,7 @@
  *  - Fan-out / fan-in in the outer graph
  *
  * Outer graph:
- *   discover-sources → extract-batch → transform-batch → [load ∥ validate] → finalize
+ *   discover-bsources → extract-batch → transform-batch → [load ∥ validate] → finalize
  *
  * Inner extract graph (event-graph, per source):
  *   connect → [fetch-metadata ∥ fetch-schema] → snapshot-data
@@ -129,11 +129,11 @@ const outerGraph: GraphConfig = {
   id: 'etl-pipeline',
   settings: { completion: 'all-tasks-complete' },
   tasks: {
-    'discover-sources': {
-      provides: ['sources-discovered'],
+    'discover-bsources': {
+      provides: ['source_defs-discovered'],
     },
     'extract-batch': {
-      requires: ['sources-discovered'],
+      requires: ['source_defs-discovered'],
       provides: ['extraction-complete'],
     },
     'transform-batch': {
@@ -191,7 +191,7 @@ async function runTransformFlow(record: { id: string; raw_data: string }) {
 // 4. Sample data
 // ============================================================================
 
-const sources = [
+const source_defs = [
   { id: 'src-orders', db: 'orders_db' },
   { id: 'src-users', db: 'users_db' },
   { id: 'src-products', db: 'products_db' },
@@ -211,13 +211,13 @@ const records = [
 // ============================================================================
 
 const outerHandlers: Record<string, () => Promise<void>> = {
-  'discover-sources': async () => {
-    console.log(`  Found ${sources.length} data sources`);
+  'discover-bsources': async () => {
+    console.log(`  Found ${source_defs.length} data source_defs`);
   },
 
   'extract-batch': async () => {
-    console.log(`  Extracting from ${sources.length} sources (concurrency: 2, mode: event-graph)`);
-    const result = await batch(sources, {
+    console.log(`  Extracting from ${source_defs.length} source_defs (concurrency: 2, mode: event-graph)`);
+    const result = await batch(source_defs, {
       concurrency: 2,
       processor: runExtractGraph,
       onItemComplete: (src, res) => {

package/examples/step-machine-cli/portfolio-tracker/cards/holdings-table.json

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

package/examples/step-machine-cli/portfolio-tracker/cards/portfolio-form.json

@@ -6,7 +6,7 @@
   "provides": [
     {
       "bindTo": "holdings",
-      "src": "card_data.holdings"
+      "ref": "card_data.holdings"
     }
   ],
   "card_data": {

package/examples/step-machine-cli/portfolio-tracker/cards/portfolio-value.json

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

package/examples/step-machine-cli/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" }],
+  "provides": [{ "bindTo": "prices", "ref": "fetched_sources.prices" }],
   "card_data": {},
-  "sources": [
+  "source_defs": [
     { "cli": "node ../fetch-prices.js --tmp-file-name tmp_file1", "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/step-machine-cli/portfolio-tracker/handlers/add-cards-cli.js

@@ -12,7 +12,7 @@ try {
     process.exit(0);
   }
 
-  runBoardCli(['add-cards', '--rg', boardDir, '--card-glob', cardsGlob]);
+  runBoardCli(['upsert-card', '--rg', boardDir, '--card-glob', cardsGlob]);
 
   writeResult({
     result: 'success',

package/examples/step-machine-cli/portfolio-tracker/handlers/update-holdings-cli.js

@@ -22,7 +22,7 @@ try {
   card.state.holdings = holdings;
   fs.writeFileSync(cardPath, `${JSON.stringify(card, null, 2)}\n`, 'utf-8');
 
-  runBoardCli(['update-card', '--rg', boardDir, '--card-id', 'portfolio-form', '--restart']);
+  runBoardCli(['upsert-card', '--rg', boardDir, '--card', cardPath, '--restart']);
 
   writeResult({
     result: 'success',

package/examples/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml

@@ -44,7 +44,7 @@ steps:
     expects_data: [board_dir, cards_template_dir]
     produces_data: [cards_dir]
     handler:
-      cli: node %%BOARDCLI_CMD%% add-cards --rg "%%BOARD_DIR%%" --card-glob "%%CARDS_GLOB%%"
+      cli: node %%BOARDCLI_CMD%% upsert-card --rg "%%BOARD_DIR%%" --card-glob "%%CARDS_GLOB%%"
       result-mode: exit-code
       input-transforms:
         BOARD_DIR: board_dir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "5.2.5",
+  "version": "5.2.8",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",
@@ -101,7 +101,7 @@
   "scripts": {
     "build": "tsup",
     "build:browser": "tsup --config tsup.browser.config.ts",
-    "build:example": "node example-board-src/build.js",
+    "build:example": "node demo-src/example-board/build.js",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",