yaml-flow 5.4.2 → 7.0.0

package/examples/browser/boards/portfolio-tracker/portfolio-tracker-fetch-prices.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""portfolio-tracker-fetch-prices.py
+
+Task executor for the portfolio board demo.
+Handles run-source-fetch requests for source_defs with kind: "mock-quotes".
+Generates random prices (2dp, 10.00-999.99) for each projected ticker.
+
+Subcommands:
+  run-source-fetch      --in-ref <::kind::value> --out-ref <::kind::value> --err-ref <::kind::value>
+  validate-source-def   --in <source.json>
+  describe-capabilities
+
+Uses the public storage adapter for all storage and callback operations.
+The executor does NOT contain transport-specific callback logic.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import sys
+import time
+from typing import Any
+
+# Add pycli to path so we can import the public storage adapter.
+_REPO_ROOT = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', '..', '..', '..'))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+from pycli.sub.public_storage_adapter import (  # noqa: E402
+    parse_ref,
+    serialize_ref,
+    blob_storage_for_ref,
+    report_complete,
+    report_failed,
+    KindValueRef,
+)
+
+
+def _parse_ref_str(ref: str) -> KindValueRef:
+    """Convenience: parse a CLI ref string."""
+    return parse_ref(ref)
+
+
+def validate_source_def(source_def: dict[str, Any]) -> dict[str, Any]:
+    errors: list[str] = []
+
+    if source_def.get("kind") != "mock-quotes":
+        errors.append(f"kind must be \"mock-quotes\"; got \"{source_def.get('kind')}\".")
+    if not isinstance(source_def.get("bindTo"), str) or not source_def.get("bindTo"):
+        errors.append("bindTo is required and must be a string.")
+    if not isinstance(source_def.get("outputFile"), str) or not source_def.get("outputFile"):
+        errors.append("outputFile is required and must be a string.")
+    projections = source_def.get("projections")
+    if not isinstance(projections, dict) or not isinstance(projections.get("tickers"), str):
+        errors.append("projections.tickers is required and must be a JSONata expression string.")
+
+    return {"ok": len(errors) == 0, "errors": errors}
+
+
+def cmd_validate_source_def(args: argparse.Namespace) -> int:
+    if not os.path.exists(args.input):
+        print(json.dumps({"ok": False, "errors": [f"Input file not found: {args.input}"]}))
+        return 1
+
+    try:
+        with open(args.input, "r", encoding="utf-8") as f:
+            source_def = json.load(f)
+    except Exception as e:
+        print(json.dumps({"ok": False, "errors": [f"Cannot parse source file: {e}"]}))
+        return 1
+
+    result = validate_source_def(source_def if isinstance(source_def, dict) else {})
+    print(json.dumps(result))
+    return 0 if result["ok"] else 1
+
+
+def cmd_describe_capabilities(_: argparse.Namespace) -> int:
+    capabilities = {
+        "version": "1.0",
+        "executor": "portfolio-tracker-fetch-prices",
+        "subcommands": ["run-source-fetch", "validate-source-def", "describe-capabilities"],
+        "sourceKinds": {
+            "mock-quotes": {
+                "description": "Generates random mock market prices (10.00-999.99) for each ticker in _projections.tickers.",
+                "inputSchema": {
+                    "kind": {"type": "string", "required": True, "description": "Must be \"mock-quotes\"."},
+                    "bindTo": {"type": "string", "required": True, "description": "Token name for the output binding."},
+                    "outputFile": {"type": "string", "required": True, "description": "Relative path to write prices JSON."},
+                    "projections": {
+                        "type": "object",
+                        "required": True,
+                        "properties": {
+                            "tickers": {
+                                "type": "string",
+                                "required": True,
+                                "description": "JSONata expression resolving to a string[] of ticker symbols.",
+                            }
+                        },
+                    },
+                },
+                "outputShape": "{ [ticker: string]: number }",
+            }
+        },
+    }
+    print(json.dumps(capabilities, indent=2, ensure_ascii=True))
+    return 0
+
+
+def cmd_run_source_fetch(args: argparse.Namespace) -> int:
+    in_ref = _parse_ref_str(args.in_ref)
+    out_ref = _parse_ref_str(args.out_ref)
+    err_ref = _parse_ref_str(args.err_ref)
+
+    in_storage = blob_storage_for_ref(in_ref)
+    out_storage = blob_storage_for_ref(out_ref)
+    err_storage = blob_storage_for_ref(err_ref)
+
+    raw_in = in_storage.read(in_ref.value)
+    if not raw_in:
+        print(f"[portfolio-tracker-fetch-prices] input envelope not found at: {args.in_ref}", file=sys.stderr)
+        return 1
+
+    envelope = json.loads(raw_in)
+    callback = envelope.get("callback") if isinstance(envelope, dict) else None
+
+    def safe_fail(msg: str) -> int:
+        try:
+            err_storage.write(err_ref.value, msg)
+        except Exception:
+            pass
+        if isinstance(callback, dict):
+            try:
+                report_failed(callback, msg)
+                return 0
+            except Exception as e:
+                print(f"[portfolio-tracker-fetch-prices] callback fail: {e}", file=sys.stderr)
+                return 1
+        return 1
+
+    try:
+        source_def = envelope.get("source_def") if isinstance(envelope, dict) else None
+        if not isinstance(source_def, dict):
+            source_def = envelope if isinstance(envelope, dict) else {}
+
+        if source_def.get("kind") != "mock-quotes":
+            raise ValueError(f"Unsupported source kind: expected \"mock-quotes\", got \"{source_def.get('kind')}\"")
+
+        projections = source_def.get("_projections")
+        tickers = projections.get("tickers") if isinstance(projections, dict) else None
+        if not isinstance(tickers, list):
+            raise ValueError("sourceDef._projections.tickers is missing or not an array")
+
+        time.sleep(0.2 + random.random() * 0.1)
+
+        prices: dict[str, float] = {}
+        for ticker in tickers:
+            prices[str(ticker)] = round(10 + random.random() * 989.99, 2)
+
+        out_storage.write(out_ref.value, json.dumps(prices, ensure_ascii=True))
+        print(f"[portfolio-tracker-fetch-prices] wrote prices for: {', '.join([str(t) for t in tickers])}")
+
+        if isinstance(callback, dict):
+            report_complete(callback, out_ref)
+        return 0
+    except Exception as e:
+        msg = str(e)
+        print(f"[portfolio-tracker-fetch-prices] error: {msg}", file=sys.stderr)
+        return safe_fail(msg)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="portfolio-tracker-fetch-prices")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_cmd = sub.add_parser("run-source-fetch")
+    run_cmd.add_argument("--in-ref", required=True)
+    run_cmd.add_argument("--out-ref", required=True)
+    run_cmd.add_argument("--err-ref", required=True)
+    run_cmd.set_defaults(handler=cmd_run_source_fetch)
+
+    val_cmd = sub.add_parser("validate-source-def")
+    val_cmd.add_argument("--in", dest="input", required=True)
+    val_cmd.set_defaults(handler=cmd_validate_source_def)
+
+    cap_cmd = sub.add_parser("describe-capabilities")
+    cap_cmd.set_defaults(handler=cmd_describe_capabilities)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * portfolio-tracker-http-test.js
+ *
+ * E2E test for the portfolio-tracker board via HTTP + SSE.
+ *
+ * Two parallel tracks:
+ *
+ *   Worker thread (portfolio-tracker-sse-worker.js) — SSE consumer
+ *     Opens the board's /sse endpoint, parses every frame, and forwards it
+ *     to the main thread via parentPort.postMessage({ type: 'frame', payload }).
+ *
+ *   Main thread (this file) — Test driver
+ *     Accumulates state from worker messages into NotificationState (NS).
+ *     Drives sequential test steps (T1–T5) via HTTP PATCH/GET.
+ *     All "wait for X" helpers poll NS with setInterval — no callbacks needed.
+ *
+ * Usage:
+ *   node portfolio-tracker-http-test.js [--port 7800] [--server node|py]
+ */
+
+import { Worker } from 'node:worker_threads';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import http from 'node:http';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const cliArgs = process.argv.slice(2);
+const portArg = cliArgs.indexOf('--port');
+const serverArg = cliArgs.indexOf('--server');
+const SERVER_TYPE = serverArg !== -1 ? cliArgs[serverArg + 1] : 'node'; // 'node' | 'py'
+const PORT = portArg !== -1 ? parseInt(cliArgs[portArg + 1], 10) : (SERVER_TYPE === 'py' ? 7801 : 7800);
+const BASE = `http://127.0.0.1:${PORT}/api/board`;
+const SERVER_SCRIPT = path.join(__dirname, 'portfolio-tracker-server.js');
+const PY_SERVER_SCRIPT = path.join(__dirname, 'portfolio-tracker-server.py');
+const SSE_WORKER_SCRIPT = path.join(__dirname, 'portfolio-tracker-sse-worker.js');
+
+/** Find a working Python interpreter. Returns null if none found. */
+function findPython() {
+  const candidates = ['python3', 'python'];
+  for (const cmd of candidates) {
+    try {
+      const r = spawnSync(cmd, ['--version'], { stdio: 'pipe', timeout: 3000 });
+      if (r.status === 0 && r.stdout?.toString().startsWith('Python ')) return cmd;
+    } catch { /* next */ }
+  }
+  return null;
+}
+
+// =============================================================================
+// NOTIFICATION STATE — accumulated by the main thread from worker SSE frames
+// =============================================================================
+const NS = {
+  initialPayload: null,     // first full snapshot frame
+  statusSummary: null,      // latest { card_count, completed, failed, ... }
+  statusGeneration: 0,      // bumped on every status notification received
+  dataObjects: {},          // token → payload  (e.g. 'prices' → { AAPL: 142.5, ... })
+  computedValues: {},       // cardId → values  (e.g. 'holdings-table' → { table: { rows: [...] } })
+};
+
+// Apply a parsed SSE frame into NS (called from worker message handler)
+function applyFrame(payload) {
+    // Initial full snapshot — has cardDefinitions
+    if (payload.cardDefinitions) {
+      NS.initialPayload = payload;
+      if (payload.statusSnapshot?.summary) {
+        NS.statusSummary = payload.statusSnapshot.summary;
+        NS.statusGeneration++;
+      }
+      if (payload.dataObjectsByToken) {
+        Object.assign(NS.dataObjects, payload.dataObjectsByToken);
+      }
+      if (payload.cardRuntimeById) {
+        for (const [cardId, runtime] of Object.entries(payload.cardRuntimeById)) {
+          if (runtime?.computed_values && Object.keys(runtime.computed_values).length > 0) {
+            NS.computedValues[cardId] = runtime.computed_values;
+          }
+        }
+      }
+      return;
+    }
+    // Subsequent frames — notification-batch
+    if (payload.kind === 'notification-batch' && Array.isArray(payload.notifications)) {
+      for (const n of payload.notifications) {
+        if (n.kind === 'status' && n.status?.summary) {
+          NS.statusSummary = n.status.summary;
+          NS.statusGeneration++;
+        } else if (n.kind === 'data_object' && n.key) {
+          NS.dataObjects[n.key] = n.payload;
+        } else if (n.kind === 'computed_values' && n.cardId) {
+          NS.computedValues[n.cardId] = n.values;
+        }
+      }
+    }
+  }
+
+  // ── Polling helpers (poll NS, never block the event loop) ───────────────────
+
+  function assert(condition, message) {
+    if (!condition) {
+      console.error(`\n[ASSERT FAILED] ${message}`);
+      process.exit(1);
+    }
+  }
+
+  function waitUntil(predicate, timeoutMs, label) {
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeoutMs;
+      const interval = setInterval(() => {
+        let result;
+        try { result = predicate(); } catch { /* retry */ }
+        if (result !== undefined && result !== null && result !== false) {
+          clearInterval(interval);
+          resolve(result);
+          return;
+        }
+        if (Date.now() > deadline) {
+          clearInterval(interval);
+          reject(new Error(`Timeout (${timeoutMs}ms) waiting for: ${label}\n  NS.statusSummary=${JSON.stringify(NS.statusSummary)}\n  dataObjects=${JSON.stringify(Object.keys(NS.dataObjects))}`));
+        }
+      }, 150);
+    });
+  }
+
+  // Waits for first full payload frame from SSE worker
+  const waitForInitialPayload = (ms = 15_000) =>
+    waitUntil(() => NS.initialPayload || false, ms, 'initial SSE payload');
+
+  // Waits for all cards to reach completed status
+  const waitForAllCompleted = (ms = 60_000, label = 'all completed') =>
+    waitUntil(() => {
+      const s = NS.statusSummary;
+      return (s && s.card_count > 0 && s.completed === s.card_count) ? s : false;
+    }, ms, label);
+
+  // Waits until prices data object has exactly the expected set of symbols
+  function waitForPriceSymbols(expectedSymbols, ms = 30_000, label = 'price symbols') {
+    const expected = [...expectedSymbols].sort().join(',');
+    return waitUntil(() => {
+      const prices = NS.dataObjects['prices'];
+      if (!prices || typeof prices !== 'object') return false;
+      const actual = Object.keys(prices).sort().join(',');
+      return actual === expected ? prices : false;
+    }, ms, `${label}: expected [${expected}]`);
+  }
+
+  // ── HTTP helpers ─────────────────────────────────────────────────────────────
+
+  function httpGet(url) {
+    return new Promise((resolve, reject) => {
+      http.get(url, (res) => {
+        let body = '';
+        res.on('data', c => { body += c; });
+        res.on('end', () => {
+          try { resolve({ status: res.statusCode, data: JSON.parse(body) }); }
+          catch { resolve({ status: res.statusCode, data: body }); }
+        });
+      }).on('error', reject);
+    });
+  }
+
+  function httpPatch(url, payload) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(payload);
+      const req = http.request(url, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      }, (res) => {
+        let data = '';
+        res.on('data', c => { data += c; });
+        res.on('end', () => {
+          try { resolve({ status: res.statusCode, data: JSON.parse(data) }); }
+          catch { resolve({ status: res.statusCode, data }); }
+        });
+      });
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+
+  function makeHoldingsPatch(holdingsMap) {
+    return {
+      card_data: {
+        holdings: Object.entries(holdingsMap).map(([symbol, qty]) => ({ symbol, qty })),
+      },
+    };
+  }
+
+  // ── Server process ────────────────────────────────────────────────────────────
+
+  function startServer(port) {
+    const isPy = SERVER_TYPE === 'py';
+    let cmd, cmdArgs;
+    if (isPy) {
+      const python = findPython();
+      if (!python) throw new Error('Python interpreter not found on PATH');
+      cmd = python;
+      cmdArgs = [PY_SERVER_SCRIPT, '--port', String(port), '--reset'];
+    } else {
+      cmd = process.execPath;
+      cmdArgs = [SERVER_SCRIPT, '--port', String(port), '--reset'];
+    }
+    return new Promise((resolve, reject) => {
+      const proc = spawn(cmd, cmdArgs, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      let ready = false;
+      proc.stdout.on('data', (chunk) => {
+        const text = chunk.toString('utf-8');
+        process.stdout.write(`[server] ${text}`);
+        if (!ready && text.includes('listening on')) { ready = true; resolve(proc); }
+      });
+      proc.stderr.on('data', (chunk) => process.stderr.write(`[server:err] ${chunk}`));
+      proc.on('error', reject);
+      proc.on('exit', (code) => { if (!ready) reject(new Error(`Server exited early: code ${code}`)); });
+      setTimeout(() => { if (!ready) reject(new Error('Server startup timeout (15s)')); }, 15_000);
+    });
+  }
+
+  // ── Main ──────────────────────────────────────────────────────────────────────
+
+  console.log('\n=== portfolio-tracker HTTP E2E test ===');
+  console.log(`target: ${BASE}  [server: ${SERVER_TYPE}]`);
+  console.log(`architecture: main-thread (test driver) + worker-thread (SSE consumer)\n`);
+
+  const serverProc = await startServer(PORT);
+  await new Promise(r => setTimeout(r, 300)); // brief settle
+
+  let sseWorker = null;
+  try {
+    // ── Step 1: init-board ──────────────────────────────────────────────────────
+    console.log('\n=== Step 1: init-board ===');
+    const initRes = await httpGet(`${BASE}/init-board`);
+    assert(initRes.status === 200, `init-board returned ${initRes.status}`);
+    console.log('[step1] ok');
+
+    // ── Step 2: Start SSE consumer worker ───────────────────────────────────────
+    // The worker opens /sse and forwards every parsed frame here via postMessage.
+    // Main thread accumulates frames into NS via applyFrame().
+    console.log('\n=== Step 2: Start SSE consumer worker ===');
+    sseWorker = new Worker(SSE_WORKER_SCRIPT, {
+      workerData: { sseUrl: `${BASE}/sse` },
+    });
+    sseWorker.on('message', (msg) => {
+      if (msg.type === 'frame') {
+        applyFrame(msg.payload);
+      } else if (msg.type === 'error') {
+        console.error(`[sse-worker] error: ${msg.message}`);
+      } else if (msg.type === 'closed') {
+        console.log('[sse-worker] SSE stream closed by server');
+      }
+    });
+    sseWorker.on('error', (err) => console.error(`[sse-worker] uncaught: ${err.message}`));
+
+    const initialPayload = await waitForInitialPayload();
+    console.log(`[step2] SSE worker online — initial payload (${initialPayload.cardDefinitions?.length ?? 0} cards)`);
+    console.log(`        statusGen=${NS.statusGeneration}, dataObjects=${JSON.stringify(Object.keys(NS.dataObjects))}`);
+
+    // ── T1: Wait for initial drain ──────────────────────────────────────────────
+    console.log('\n=== T1: Wait for initial completion ===');
+    const t1Summary = await waitForAllCompleted(60_000, 'T1 initial drain');
+    console.log(`[T1] board completed — ${JSON.stringify(t1Summary)}`);
+
+    const t1Prices = await waitForPriceSymbols(['AAPL', 'MSFT'], 30_000, 'T1 prices');
+    assert(Object.values(t1Prices).every(v => typeof v === 'number'), 'T1: all prices must be numbers');
+    const t1Table = NS.computedValues['holdings-table']?.table;
+    assert(Array.isArray(t1Table?.rows) && t1Table.rows.length === 2, `T1: expected 2 rows, got ${t1Table?.rows?.length}`);
+    const t1Total = NS.computedValues['portfolio-value']?.totalValue;
+    assert(typeof t1Total === 'number' && t1Total > 0, `T1: totalValue must be positive, got ${t1Total}`);
+    console.log(`[T1] passed: prices=[AAPL,MSFT], rows=2, totalValue=${t1Total.toFixed(2)}`);
+
+    // ── T2a: Add GOOG to holdings ────────────────────────────────────────────────
+    console.log('\n=== T2a: Update holdings — add GOOG ===');
+    const t2Patch = await httpPatch(
+      `${BASE}/cards/portfolio-form`,
+      makeHoldingsPatch({ AAPL: 50, MSFT: 30, GOOG: 100 }),
+    );
+    assert(t2Patch.status === 200, `PATCH portfolio-form returned ${t2Patch.status}`);
+    console.log('[T2a] PATCH ok — worker will receive SSE notifications independently');
+
+    // ── T2b: Wait for 3-ticker completion ───────────────────────────────────────
+    console.log('\n=== T2b: Wait for 3-ticker completion ===');
+    const t2Summary = await waitForAllCompleted(60_000, 'T2b 3-ticker drain');
+    console.log(`[T2b] completed — ${JSON.stringify(t2Summary)}`);
+
+    const t2Prices = await waitForPriceSymbols(['AAPL', 'GOOG', 'MSFT'], 30_000, 'T2b prices');
+    const t2Table = NS.computedValues['holdings-table']?.table;
+    assert(Array.isArray(t2Table?.rows) && t2Table.rows.length === 3, `T2b: expected 3 rows, got ${t2Table?.rows?.length}`);
+    const t2Total = NS.computedValues['portfolio-value']?.totalValue;
+    assert(typeof t2Total === 'number' && t2Total > 0, 'T2b: totalValue must be positive');
+    console.log(`[T2b] passed: prices=[AAPL,GOOG,MSFT], rows=3, totalValue=${t2Total.toFixed(2)}`);
+
+    // ── T3: Rapid 3× holdings updates (queue stress) ─────────────────────────────
+    // The worker independently streams all SSE notifications while the driver
+    // fires rapid PATCHes. NS accumulates state continuously in both cases.
+    console.log('\n=== T3: Rapid 3× holdings updates ===');
+    const rapidUpdates = [
+      { AAPL: 45, MSFT: 30, GOOG: 110, TSLA: 60 },
+      { AAPL: 45, MSFT: 30, GOOG: 110, AMZN: 100 }, // intermediate — not expected to be final
+      { AAPL: 40, MSFT: 35, GOOG: 120, TSLA: 70 },  // V5 — expected final state
+    ];
+    for (const holdings of rapidUpdates) {
+      await httpPatch(`${BASE}/cards/portfolio-form`, makeHoldingsPatch(holdings));
+    }
+    console.log('[T3] rapid PATCHes sent — worker accumulates SSE state in parallel');
+
+    await waitForAllCompleted(60_000, 'T3 rapid-update drain');
+    const t3Prices = await waitForPriceSymbols(['AAPL', 'GOOG', 'MSFT', 'TSLA'], 30_000, 'T3 final prices');
+    const t3Table = NS.computedValues['holdings-table']?.table;
+    assert(Array.isArray(t3Table?.rows) && t3Table.rows.length === 4, `T3: expected 4 rows, got ${t3Table?.rows?.length}`);
+    assert(!Object.keys(t3Prices).includes('AMZN'), `T3: AMZN must not be present (got ${JSON.stringify(Object.keys(t3Prices))})`);
+    console.log(`[T3] passed: prices=${JSON.stringify(Object.keys(t3Prices).sort())}, rows=4, AMZN absent`);
+
+    // ── T4: Cross-verify portfolio-value totalValue ───────────────────────────────
+    console.log('\n=== T4: Cross-verify totalValue ===');
+    const t4Total = NS.computedValues['portfolio-value']?.totalValue;
+    assert(typeof t4Total === 'number' && t4Total > 0, `T4: totalValue must be positive, got ${t4Total}`);
+    const sumRows = t3Table.rows.reduce((acc, r) => acc + (r.value || 0), 0);
+    assert(Math.abs(sumRows - t4Total) < 0.01, `T4: mismatch: sumRows=${sumRows}, totalValue=${t4Total}`);
+    console.log(`[T4] passed: totalValue=${t4Total.toFixed(2)}, sumRows=${sumRows.toFixed(2)}`);
+
+    // ── T5: board-status HTTP cross-check ────────────────────────────────────────
+    // Compare the HTTP board-status endpoint response against what the worker
+    // accumulated via SSE — the two sources must agree.
+    console.log('\n=== T5: board-status HTTP cross-check ===');
+    const t5Res = await httpGet(`${BASE}/board-status`);
+    assert(t5Res.status === 200, `board-status returned ${t5Res.status}`);
+    const t5Summary = t5Res.data?.statusSnapshot?.summary;
+    assert(t5Summary, 'T5: statusSnapshot.summary missing from board-status');
+    assert(t5Summary.completed === t5Summary.card_count,
+      `T5: completed=${t5Summary.completed} !== card_count=${t5Summary.card_count}`);
+    assert(t5Summary.failed === 0, `T5: failed=${t5Summary.failed} (expected 0)`);
+
+    // Cross-check: dataObjects from HTTP response matches what worker accumulated
+    const httpDataObjKeys = Object.keys(t5Res.data.dataObjectsByToken || {}).sort().join(',');
+    const workerDataObjKeys = Object.keys(NS.dataObjects).sort().join(',');
+    assert(httpDataObjKeys === workerDataObjKeys,
+      `T5: HTTP dataObjects keys [${httpDataObjKeys}] differ from worker-accumulated [${workerDataObjKeys}]`);
+
+    console.log(`[T5] summary: ${JSON.stringify(t5Summary)}`);
+    console.log(`[T5] HTTP vs worker dataObjects agree: [${workerDataObjKeys}]`);
+    console.log(`[T5] statusGen at end: ${NS.statusGeneration}`);
+    console.log('[T5] all assertions passed');
+
+    console.log('\n=== All tests passed ✓ ===\n');
+
+  } finally {
+    sseWorker?.terminate();
+    serverProc.kill();
+    await new Promise(r => serverProc.on('exit', r));
+    console.log(`[portfolio-tracker-http-test] server stopped (${SERVER_TYPE})`);
+  }

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

@@ -1,20 +1,27 @@
 #!/usr/bin/env node
 
-import * as fs from 'node:fs';
 import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { parseRef, blobStorageForRef } from 'yaml-flow/storage-refs';
 
 function parseArgs(argv) {
-  const inIdx = argv.indexOf('--in');
-  const outIdx = argv.indexOf('--out');
-  const errIdx = argv.indexOf('--err');
-  const inFile = inIdx !== -1 ? argv[inIdx + 1] : undefined;
-  const outFile = outIdx !== -1 ? argv[outIdx + 1] : undefined;
-  const errFile = errIdx !== -1 ? argv[errIdx + 1] : undefined;
-  if (!inFile || !outFile || !errFile) {
-    console.error('Usage: <adapter> run-inference --in <input.json> --out <output.json> --err <error.txt>');
+  const inIdx  = argv.indexOf('--in-ref');
+  const outIdx = argv.indexOf('--out-ref');
+  const errIdx = argv.indexOf('--err-ref');
+  const inRefStr  = inIdx  !== -1 ? argv[inIdx + 1]  : undefined;
+  const outRefStr = outIdx !== -1 ? argv[outIdx + 1] : undefined;
+  const errRefStr = errIdx !== -1 ? argv[errIdx + 1] : undefined;
+  if (!inRefStr || !outRefStr || !errRefStr) {
+    console.error('Usage: <adapter> run-inference --in-ref <::kind::value> --out-ref <::kind::value> --err-ref <::kind::value>');
     process.exit(1);
   }
-  return { inFile, outFile, errFile };
+  const inRef  = parseRef(inRefStr);
+  const outRef = parseRef(outRefStr);
+  const errRef = parseRef(errRefStr);
+  const inStorage  = blobStorageForRef(inRef);
+  const outStorage = blobStorageForRef(outRef);
+  const errStorage = blobStorageForRef(errRef);
+  return { inRef, outRef, errRef, inStorage, outStorage, errStorage };
 }
 
 const envBoardDir = (process.env.BOARD_DIR ?? '').trim();
@@ -144,10 +151,12 @@ async function main() {
     process.exit(1);
   }
 
-  const { inFile, outFile, errFile } = parseArgs(process.argv.slice(3));
+  const { inRef, outRef, errRef, inStorage, outStorage, errStorage } = parseArgs(process.argv.slice(3));
 
   try {
-    const payload = JSON.parse(fs.readFileSync(inFile, 'utf-8'));
+    const rawIn = inStorage.read(inRef.value);
+    if (rawIn === null) throw new Error(`Input not found: ${inRef.value}`);
+    const payload = JSON.parse(rawIn);
     const tmpCandidates = resolveSyncTmpFileCandidates(payload);
     if (tmpCandidates.length > 0) {
       await waitForTmpSyncInput(tmpCandidates);
@@ -174,12 +183,12 @@ async function main() {
       };
     }
 
-    fs.writeFileSync(outFile, JSON.stringify(result), 'utf-8');
-    fs.writeFileSync(errFile, '', 'utf-8');
+    outStorage.write(outRef.value, JSON.stringify(result));
+    errStorage.write(errRef.value, '');
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    fs.writeFileSync(errFile, message, 'utf-8');
-    fs.writeFileSync(outFile, JSON.stringify({ isTaskCompleted: false, reason: message, evidence: '' }), 'utf-8');
+    errStorage.write(errRef.value, message);
+    outStorage.write(outRef.value, JSON.stringify({ isTaskCompleted: false, reason: message, evidence: '' }));
     process.exit(1);
   }
 }