yaml-flow 7.1.0 → 8.0.0

package/examples/board/test/demo-http-test.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * demo-http-test.js
+ *
+ * Smoke test for public-examples/board/demo-server.js over HTTP + SSE.
+ *
+ * Usage:
+ *   node demo-http-test.js [--port 7799]
+ */
+
+import { spawn } from 'node:child_process';
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import http from 'node:http';
+import fs from 'node:fs';
+import net from 'node:net';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const cliArgs = process.argv.slice(2);
+const portArg = cliArgs.indexOf('--port');
+const cliPort = portArg !== -1 ? parseInt(cliArgs[portArg + 1], 10) : NaN;
+const RUN_ID = `run-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+
+async function pickFreePort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      const port = addr && typeof addr === 'object' ? addr.port : 0;
+      server.close((err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(port);
+      });
+    });
+  });
+}
+
+const PORT = Number.isInteger(cliPort) && cliPort > 0 ? cliPort : await pickFreePort();
+
+const BOARD_ID = 'default';
+const BASE = `http://127.0.0.1:${PORT}/api/boards/${BOARD_ID}`;
+const SERVER_SCRIPT = path.join(__dirname, '..', 'demo-server.js');
+const SERVER_DIR = path.dirname(SERVER_SCRIPT);
+const SSE_WORKER_SCRIPT = path.join(__dirname, 'portfolio-tracker-sse-worker.js');
+const CARD_PATTERN = 'cardT*';
+
+// Resolve and wipe the setup directory before starting the server so each
+// test run begins from a clean slate.  The location is read from
+// demo-server-config.json (setupDir key) with the same fallback the server uses.
+function resolveSetupDirRoot() {
+  const configPath = path.join(SERVER_DIR, 'demo-server-config.json');
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (cfg && typeof cfg.setupDir === 'string' && cfg.setupDir.trim()) {
+      return path.resolve(SERVER_DIR, cfg.setupDir.trim());
+    }
+  } catch { /* ignore */ }
+  return path.join(SERVER_DIR, '.demo-setup');
+}
+
+const SETUP_DIR = path.join(resolveSetupDirRoot(), RUN_ID);
+if (fs.existsSync(SETUP_DIR)) {
+  fs.rmSync(SETUP_DIR, { recursive: true, force: true });
+  console.log(`[demo-http-test] wiped setup dir: ${SETUP_DIR}`);
+}
+
+
+const NS = {
+  initialPayload: null,
+  statusSummary: null,
+  statusGeneration: 0,
+  computedValues: {},
+};
+
+function applyFrame(payload) {
+  if (payload && Array.isArray(payload.cardDefinitions)) {
+    if (!NS.initialPayload && payload.cardDefinitions.length > 0) {
+      NS.initialPayload = payload;
+    }
+    const summary = payload.statusSnapshot && payload.statusSnapshot.summary;
+    if (summary) {
+      NS.statusSummary = summary;
+      NS.statusGeneration += 1;
+    }
+    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;
+  }
+
+  if (payload && payload.kind === 'notification-batch' && Array.isArray(payload.notifications)) {
+    for (const n of payload.notifications) {
+      const summary = n && n.kind === 'status' && n.status && n.status.summary;
+      if (summary) {
+        NS.statusSummary = summary;
+        NS.statusGeneration += 1;
+      }
+      if (n && n.kind === 'computed_values' && n.cardId) {
+        NS.computedValues[n.cardId] = n.values;
+      }
+    }
+  }
+}
+
+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}`));
+      }
+    }, 150);
+  });
+}
+
+const waitForInitialPayload = (ms = 15_000) =>
+  waitUntil(() => NS.initialPayload || false, ms, 'initial SSE payload');
+
+const waitForAllCompleted = (ms = 60_000, label = 'all completed') =>
+  waitUntil(() => {
+    const s = NS.statusSummary;
+    if (s && s.card_count > 0 && s.completed === s.card_count) return s;
+    return false;
+  }, ms, label);
+
+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 httpJson(method, url, payload) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const data = payload != null ? JSON.stringify(payload) : null;
+    const opts = {
+      hostname: u.hostname,
+      port: u.port,
+      path: u.pathname,
+      method,
+      headers: data ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } : {},
+    };
+    const req = http.request(opts, (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 }); }
+      });
+    });
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+function startServer(port) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, [SERVER_SCRIPT, '--cards-pattern', CARD_PATTERN], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      env: { ...process.env, DEMO_SERVER_PORT: String(port), DEMO_SETUP_DIR: SETUP_DIR },
+    });
+    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);
+  });
+}
+
+console.log('\n=== board HTTP+SSE smoke test ===');
+console.log(`target: ${BASE}`);
+console.log(`card pattern: ${CARD_PATTERN}`);
+
+const serverProc = await startServer(PORT);
+let sseWorker = null;
+
+try {
+  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');
+
+  console.log('\n=== Step 2: start SSE 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] ${msg.message}`);
+  });
+  sseWorker.on('error', (err) => console.error(`[sse-worker] uncaught: ${err.message}`));
+
+  const initialPayload = await waitForInitialPayload();
+  const cardCount = Array.isArray(initialPayload.cardDefinitions) ? initialPayload.cardDefinitions.length : 0;
+  assert(cardCount > 0, 'initial SSE payload must include cardDefinitions');
+  console.log(`[step2] SSE initial payload received (${cardCount} cards)`);
+
+  console.log('\n=== Step 3: wait for completion ===');
+  const summary = await waitForAllCompleted(20_000, 'initial board completion');
+  assert(summary.failed === 0, `expected failed=0, got ${summary.failed}`);
+  console.log(`[step3] completed summary: ${JSON.stringify(summary)}`);
+
+  console.log('\n=== Step 4: board-status cross-check ===');
+  const statusRes = await httpGet(`${BASE}/board-status`);
+  assert(statusRes.status === 200, `board-status returned ${statusRes.status}`);
+  const httpSummary = statusRes.data && statusRes.data.statusSnapshot && statusRes.data.statusSnapshot.summary;
+  assert(httpSummary, 'statusSnapshot.summary missing from board-status');
+  console.log(`[step4] board-status summary: ${JSON.stringify(httpSummary)}`);
+
+  // ── T1: PATCH holdings (+1 row) and verify recomputation ──
+  console.log('\n=== T1: patch holdings (+1 row) ===');
+
+  // Read current holdings from card store via GET /cards/:id
+  const portfolioCardRes = await httpGet(`${BASE}/cards/card-portfolio`);
+  assert(portfolioCardRes.status === 200, `GET card-portfolio returned ${portfolioCardRes.status}`);
+  const existingHoldings = (portfolioCardRes.data.card_data || {}).holdings;
+  assert(Array.isArray(existingHoldings), 'card-portfolio.card_data.holdings missing');
+  const t0HoldingsCount = existingHoldings.length;
+
+  // Read current positions count from computed_values captured via SSE
+  const t0Positions = (NS.computedValues['card-portfolio-value'] || {}).positions;
+  const t0PositionsCount = Array.isArray(t0Positions) ? t0Positions.length : 0;
+
+  // Pick a ticker not already in holdings
+  const candidates = ['AAPL', 'MSFT', 'AMZN', 'TSLA', 'META', 'GOOG', 'NVDA', 'NFLX', 'INTC', 'AMD',
+    'IBM', 'ORCL', 'ADBE', 'CRM', 'QCOM'];
+  const existingTickers = new Set(existingHoldings.map(r => r.ticker));
+  const available = candidates.filter(t => !existingTickers.has(t));
+  assert(available.length > 0, 'No available ticker to add');
+  const newTicker = available[0];
+
+  const newHoldings = [...existingHoldings, { ticker: newTicker, quantity: 1, cost_basis: 100 }];
+  const patchRes = await httpJson('PATCH', `${BASE}/cards/card-portfolio`, { card_data: { holdings: newHoldings } });
+  assert(patchRes.status === 200, `PATCH card-portfolio returned ${patchRes.status}`);
+
+  // Wait for re-completion
+  NS.statusSummary = null;
+  await new Promise(r => setTimeout(r, 4000));
+  const t1Summary = await waitForAllCompleted(30_000, 'T1 holdings patch');
+  assert(t1Summary.failed === 0, `T1 failed=${t1Summary.failed}`);
+
+  // Verify holdings +1 from card store
+  const t1PortfolioRes = await httpGet(`${BASE}/cards/card-portfolio`);
+  assert(t1PortfolioRes.status === 200, `GET card-portfolio after patch returned ${t1PortfolioRes.status}`);
+  const afterHoldings = (t1PortfolioRes.data.card_data || {}).holdings;
+  const afterHoldingsCount = Array.isArray(afterHoldings) ? afterHoldings.length : 0;
+
+  // Verify positions +1 from computed_values captured via SSE
+  const afterPositions = (NS.computedValues['card-portfolio-value'] || {}).positions;
+  const afterPositionsCount = Array.isArray(afterPositions) ? afterPositions.length : 0;
+
+  assert(afterHoldingsCount === t0HoldingsCount + 1,
+    `Expected holdings rows +1 (before=${t0HoldingsCount}, after=${afterHoldingsCount})`);
+  assert(afterPositionsCount === t0PositionsCount + 1,
+    `Expected portfolio value rows +1 (before=${t0PositionsCount}, after=${afterPositionsCount})`);
+
+  console.log(`[T1] ok: holdings ${t0HoldingsCount}->${afterHoldingsCount}, ` +
+    `positions ${t0PositionsCount}->${afterPositionsCount}, added=${newTicker}`);
+
+  console.log('\n=== All smoke checks passed ===\n');
+} finally {
+  // Kill server first so the SSE connection closes, then await worker termination.
+  // (Terminating the worker while the SSE socket is still open leaves dangling handles.)
+  serverProc.kill();
+  await new Promise((r) => serverProc.on('exit', r));
+  if (sseWorker) await sseWorker.terminate();
+  console.log('[demo-http-test] server stopped');
+}

package/examples/{example-board → board-local}/demo-shell-localstorage.html

@@ -4,15 +4,15 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Example Board Demo (LocalStorage Runtime)</title>
-  <link rel="icon" type="image/svg+xml" href="favicon.svg" />
+  <link rel="icon" type="image/svg+xml" href="../../browser/favicon.svg" />
   <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/compute-jsonata.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.0/browser/compute-jsonata.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/leader-line/leader-line.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@7.1.0/browser/board-livecards-localstorage.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.0/browser/board-livecards-localstorage.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/{browser/boards/portfolio-tracker → portfolio-tracker/handlers}/portfolio-tracker-fetch-prices.js

@@ -22,7 +22,7 @@
  */
 
 import fs from 'node:fs';
-import { parseRef, blobStorageForRef, reportComplete, reportFailed } from 'yaml-flow/storage-refs';
+import { parseRef, blobStorageForRef, reportComplete, reportFailed } from 'yaml-flow/board-worker-adapter';
 
 // ---------------------------------------------------------------------------
 // validate-source-def — structural validation of a source definition

package/examples/{browser/boards/portfolio-tracker/portfolio-tracker-public.js → portfolio-tracker/portfolio-tracker.js}

@@ -16,14 +16,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
 import net from 'node:net';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const _REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
-
-// ── Library imports ────────────────────────────────────────────────────────────
-const _adapterPath = path.join(_REPO_ROOT, 'dist', 'cli', 'node', 'fs-board-adapter.js');
-const {
+import { fileURLToPath } from 'node:url';
+import {
   createBoardLiveCardsPublic,
   createBoardLiveCardsNonCorePublic,
   createFsBoardPlatformAdapter,
@@ -32,9 +26,12 @@ const {
   createCardStore,
   parseRef,
   serializeRef,
-} = await import(pathToFileURL(_adapterPath).href);
+} from 'yaml-flow/board-live-cards-node';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const _REPO_ROOT = path.resolve(__dirname, '..', '..');
 
-const FETCH_PRICES_JS = path.join(__dirname, 'portfolio-tracker-fetch-prices.js');
+const FETCH_PRICES_JS = path.join(__dirname, 'handlers', 'portfolio-tracker-fetch-prices.js');
 
 // ── Runtime directories ────────────────────────────────────────────────────────
 const _TMP_BASE       = path.join(os.tmpdir(), 'experiment-js');
@@ -134,7 +131,7 @@ function assert(condition, message) {
 
 function makeBoard() {
   const br = parseRef(BOARDRUNTIME_REF);
-  return createBoardLiveCardsPublic(br, createFsBoardPlatformAdapter(br, _REPO_ROOT, {
+  return createBoardLiveCardsPublic(br, createFsBoardPlatformAdapter(br, {
     onWarn: console.warn,
     notifyChannel: NOTIFY_CHANNEL,
   }));
@@ -142,12 +139,12 @@ function makeBoard() {
 
 function makeNonCoreBoard() {
   const br = parseRef(BOARDRUNTIME_REF);
-  return createBoardLiveCardsNonCorePublic(br, createFsBoardNonCorePlatformAdapter(br, _REPO_ROOT, { onWarn: console.warn }));
+  return createBoardLiveCardsNonCorePublic(br, createFsBoardNonCorePlatformAdapter(br, { onWarn: console.warn }));
 }
 
 function makeCardStore() {
   const ref = parseRef(CARDSTORE_REF);
-  const adapter = createFsBoardPlatformAdapter(ref, _REPO_ROOT, { onWarn: console.warn });
+  const adapter = createFsBoardPlatformAdapter(ref, { onWarn: console.warn });
   const kv = adapter.kvStorageForRef(CARDSTORE_REF);
   const cardAdapterObj = {
     readIndex: () => kv.read('_index'),
@@ -424,7 +421,7 @@ for (const card of [
   CARD_HOLDINGS_TABLE,
   CARD_PORTFOLIO_VALUE,
 ]) {
-  const vr = makeNonCoreBoard().validateTmpCard({ body: card });
+  const vr = makeNonCoreBoard().validateCardPreflight({ body: card });
   if (!vr.data?.isValid) {
     console.error(`[VALIDATE FAILED] card ${card.id}:`, JSON.stringify(vr.data?.issues ?? vr.error));
     process.exit(1);

package/examples/{browser/boards/portfolio-tracker → portfolio-tracker/test}/portfolio-t4.js

@@ -2,23 +2,15 @@
 /**
  * portfolio-t4.js — T4 rapid-fire test only.
  *
- * Runs T0 (init, card setup) then fires 5 portfolio-form upserts
- * back-to-back (no delay) and waits for the board to converge.
- * Asserts final prices contain the iter-5 tickers only (AAPL/MSFT/GOOG/TSLA)
- * and AMZN is absent.
+ * Public-examples variant. Runs T0 init, then fires 5 portfolio-form upserts
+ * back-to-back and waits for convergence.
  */
 
 import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const _REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
-
-// ── Library imports ────────────────────────────────────────────────────────────
-const _adapterPath = path.join(_REPO_ROOT, 'dist', 'cli', 'node', 'fs-board-adapter.js');
-const {
+import { fileURLToPath } from 'node:url';
+import {
   createBoardLiveCardsPublic,
   createBoardLiveCardsNonCorePublic,
   createFsBoardPlatformAdapter,
@@ -27,27 +19,28 @@ const {
   createCardStore,
   parseRef,
   serializeRef,
-} = await import(pathToFileURL(_adapterPath).href);
+} from 'yaml-flow/board-live-cards-node';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const _REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
 
-const FETCH_PRICES_JS = path.join(__dirname, 'portfolio-tracker-fetch-prices.js');
+const FETCH_PRICES_JS = path.join(__dirname, '..', 'handlers', 'portfolio-tracker-fetch-prices.js');
 
-// ── Runtime directories ────────────────────────────────────────────────────────
-const _TMP_BASE        = path.join(os.tmpdir(), 'experiment-js-t4');
-const CARDSTORE_DIR    = path.join(_TMP_BASE, 'cardstore');
+const _TMP_BASE = path.join(os.tmpdir(), 'experiment-js-t4');
+const CARDSTORE_DIR = path.join(_TMP_BASE, 'cardstore');
 const BOARDRUNTIME_DIR = path.join(_TMP_BASE, 'boardruntime');
-const OUTPUTS_DIR      = path.join(_TMP_BASE, 'outputs');
+const OUTPUTS_DIR = path.join(_TMP_BASE, 'outputs');
 
-const CARDSTORE_REF    = serializeRef({ kind: 'fs-path', value: CARDSTORE_DIR });
+const CARDSTORE_REF = serializeRef({ kind: 'fs-path', value: CARDSTORE_DIR });
 const BOARDRUNTIME_REF = serializeRef({ kind: 'fs-path', value: BOARDRUNTIME_DIR });
-const OUTPUTS_REF      = serializeRef({ kind: 'fs-path', value: OUTPUTS_DIR });
+const OUTPUTS_REF = serializeRef({ kind: 'fs-path', value: OUTPUTS_DIR });
 
-// ── Card definitions ───────────────────────────────────────────────────────────
 const CARD_PORTFOLIO_FORM = {
   id: 'portfolio-form',
   meta: { title: 'Portfolio Holdings Form' },
   provides: [{ bindTo: 'holdings', ref: 'card_data.holdings' }],
   card_data: { holdings: [] },
-  view: { elements: [{ kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } }] }
+  view: { elements: [{ kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } }] },
 };
 
 const CARD_PRICE_FETCH = {
@@ -58,9 +51,9 @@ const CARD_PRICE_FETCH = {
   card_data: {},
   compute: [{
     bindTo: 'prices',
-    expr: '$merge($map(requires.holdings, function($h){ { $h.symbol: 100 } }))'
+    expr: '$merge($map(requires.holdings, function($h){ { $h.symbol: 100 } }))',
   }],
-  view: { elements: [{ kind: 'table', label: 'Market Prices', data: { bind: 'computed_values.prices' } }] }
+  view: { elements: [{ kind: 'table', label: 'Market Prices', data: { bind: 'computed_values.prices' } }] },
 };
 
 const CARD_HOLDINGS_TABLE = {
@@ -71,9 +64,9 @@ const CARD_HOLDINGS_TABLE = {
   card_data: {},
   compute: [{
     bindTo: 'table',
-    expr: '{ "rows": $map(requires.holdings, function($h) { { "symbol": $h.symbol, "qty": $h.qty, "price": $lookup(requires.prices, $h.symbol), "value": $h.qty * $lookup(requires.prices, $h.symbol) } }) }'
+    expr: '{ "rows": $map(requires.holdings, function($h) { { "symbol": $h.symbol, "qty": $h.qty, "price": $lookup(requires.prices, $h.symbol), "value": $h.qty * $lookup(requires.prices, $h.symbol) } }) }',
   }],
-  view: { elements: [{ kind: 'table', label: 'Portfolio Positions', data: { bind: 'computed_values.table.rows', columns: ['symbol', 'qty', 'price', 'value'] } }] }
+  view: { elements: [{ kind: 'table', label: 'Portfolio Positions', data: { bind: 'computed_values.table.rows', columns: ['symbol', 'qty', 'price', 'value'] } }] },
 };
 
 const CARD_PORTFOLIO_VALUE = {
@@ -83,10 +76,9 @@ const CARD_PORTFOLIO_VALUE = {
   provides: [{ bindTo: 'totalValue', ref: 'computed_values.totalValue' }],
   card_data: {},
   compute: [{ bindTo: 'totalValue', expr: '$sum(requires.table.rows.value)' }],
-  view: { elements: [{ kind: 'metric', label: 'Total Portfolio Value', data: { bind: 'computed_values.totalValue' } }] }
+  view: { elements: [{ kind: 'metric', label: 'Total Portfolio Value', data: { bind: 'computed_values.totalValue' } }] },
 };
 
-// ── Helpers ────────────────────────────────────────────────────────────────────
 function setHoldings(card, holdings) {
   return { ...card, card_data: { ...card.card_data, holdings: Object.entries(holdings).map(([symbol, qty]) => ({ symbol, qty })) } };
 }
@@ -101,17 +93,17 @@ function readJson(filePath) {
 
 function makeBoard() {
   const br = parseRef(BOARDRUNTIME_REF);
-  return createBoardLiveCardsPublic(br, createFsBoardPlatformAdapter(br, _REPO_ROOT, { onWarn: console.warn }));
+  return createBoardLiveCardsPublic(br, createFsBoardPlatformAdapter(br, { onWarn: console.warn }));
 }
 
 function makeNonCoreBoard() {
   const br = parseRef(BOARDRUNTIME_REF);
-  return createBoardLiveCardsNonCorePublic(br, createFsBoardNonCorePlatformAdapter(br, _REPO_ROOT, { onWarn: console.warn }));
+  return createBoardLiveCardsNonCorePublic(br, createFsBoardNonCorePlatformAdapter(br, { onWarn: console.warn }));
 }
 
 function makeCardStore() {
   const ref = parseRef(CARDSTORE_REF);
-  const adapter = createFsBoardPlatformAdapter(ref, _REPO_ROOT, { onWarn: console.warn });
+  const adapter = createFsBoardPlatformAdapter(ref, { onWarn: console.warn });
   const kv = adapter.kvStorageForRef(CARDSTORE_REF);
   const cardAdapterObj = {
     readIndex: () => kv.read('_index'),
@@ -125,7 +117,7 @@ function makeCardStore() {
 }
 
 function checkResult(result, label) {
-  if (result.status !== 'success') { console.error(`[ERROR] ${label}: ${result.status} — ${result.error}`); process.exit(1); }
+  if (result.status !== 'success') { console.error(`[ERROR] ${label}: ${result.status} - ${result.error}`); process.exit(1); }
   return result.data;
 }
 
@@ -154,7 +146,6 @@ async function waitForCompleted(label, timeoutMs = 90_000, pollMs = 500) {
 
 const T = () => Date.now();
 
-// ── T0 — Init ─────────────────────────────────────────────────────────────────
 console.log('\n=== T0: Init ===');
 if (fs.existsSync(_TMP_BASE)) fs.rmSync(_TMP_BASE, { recursive: true, force: true });
 for (const d of [CARDSTORE_DIR, BOARDRUNTIME_DIR, OUTPUTS_DIR]) fs.mkdirSync(d, { recursive: true });
@@ -165,7 +156,7 @@ checkResult(
     params: { cardStoreRef: CARDSTORE_REF, outputsStoreRef: OUTPUTS_REF },
     body: { 'task-executor-ref': { meta: 'task-executor', howToRun: 'local-node', whatToRun: serializeRef({ kind: 'fs-path', value: FETCH_PRICES_JS }) } },
   }),
-  'init'
+  'init',
 );
 console.log(`  [${T()}] init done`);
 
@@ -176,8 +167,8 @@ for (const card of [
   CARD_HOLDINGS_TABLE,
   CARD_PORTFOLIO_VALUE,
 ]) {
-  const vr = makeNonCoreBoard().validateTmpCard({ body: card });
-  console.log(`  [${T()}] validateTmpCard ${card.id} done`);
+  const vr = makeNonCoreBoard().validateCardPreflight({ body: card });
+  console.log(`  [${T()}] validateCardPreflight ${card.id} done`);
   if (!vr.data?.isValid) { console.error(`[VALIDATE FAILED] ${card.id}:`, JSON.stringify(vr.data?.issues ?? vr.error)); process.exit(1); }
   checkResult(cardStore.set({ body: card }), `card-store set ${card.id}`);
   console.log(`  [${T()}] cardStore.set ${card.id} done`);
@@ -191,7 +182,6 @@ for (const cardId of ['portfolio-form', 'price-fetch', 'holdings-table', 'portfo
 await waitForCompleted('T0-settle');
 console.log(`[${T()}] [T0] board settled with initial holdings.`);
 
-// ── T4 — Rapid 5× portfolio-form updates (no delay) ───────────────────────────
 console.log('\n=== T4: Rapid 5x portfolio-form updates (no delay) ===');
 
 const T4_ITERS = [
@@ -202,7 +192,6 @@ const T4_ITERS = [
   { AAPL: 45, MSFT: 30, GOOG: 110, AMZN: 140, TSLA: 60 },
 ];
 
-// Expected final state: iter 5 holdings (AMZN present in iter 5 but test verifies what actually wins)
 const T4_EXPECTED_FINAL = { AAPL: 45, MSFT: 30, GOOG: 110, AMZN: 140, TSLA: 60 };
 
 for (let i = 0; i < T4_ITERS.length; i++) {
@@ -212,14 +201,12 @@ for (let i = 0; i < T4_ITERS.length; i++) {
   console.log(`  [${T()}] iter ${i + 1} cardStore.set done`);
   checkResult(makeBoard().upsertCard({ params: { cardId: 'portfolio-form', restart: 'true' } }), `iter${i + 1} upsert`);
   console.log(`  [${T()}] iter ${i + 1} upsertCard done`);
-  // await waitForCompleted(`T4-iter${i + 1}`);  // commented out: rapid-fire, no waits
 }
 
-console.log(`\n[${T()}] [T4] all 5 upserts fired — waiting for board to converge...`);
+console.log(`\n[${T()}] [T4] all 5 upserts fired - waiting for board to converge...`);
 const t4Final = await waitForCompleted('T4');
 console.log(`[${T()}] [T4] waitForCompleted done`);
 
-// ── Assertions ────────────────────────────────────────────────────────────────
 const holdingsPath = path.join(OUTPUTS_DIR, 'data-objects', 'holdings.json');
 const holdings = readJson(holdingsPath);
 console.log('\n[T4] holdings.json (data-object output):', JSON.stringify(holdings, null, 2));
@@ -227,7 +214,6 @@ console.log('\n[T4] holdings.json (data-object output):', JSON.stringify(holding
 const finalCard = readJson(path.join(CARDSTORE_DIR, 'portfolio-form.json'));
 console.log('[T4] cardstore portfolio-form holdings:', JSON.stringify(finalCard.card_data?.holdings, null, 2));
 
-// Assert final holdings match iter-5
 const holdingsBySymbol = Object.fromEntries(holdings.map(h => [h.symbol, h.qty]));
 const expectedSymbols = Object.keys(T4_EXPECTED_FINAL).sort();
 const actualSymbols = Object.keys(holdingsBySymbol).sort();
@@ -239,7 +225,6 @@ for (const [sym, qty] of Object.entries(T4_EXPECTED_FINAL)) {
 }
 console.log('[T4] holdings assertions passed: iter-5 symbols and quantities match.');
 
-// Assert prices contain exactly the iter-5 tickers
 const pricesPath = path.join(OUTPUTS_DIR, 'data-objects', 'prices.json');
 const prices = readJson(pricesPath);
 const priceKeys = Object.keys(prices).sort();
@@ -249,7 +234,6 @@ assert(Object.values(prices).every(v => typeof v === 'number'),
   'T4: all price values must be numbers');
 console.log('[T4] prices assertions passed:', JSON.stringify(prices));
 
-// Assert holdings-table rows match
 const htCvPath = path.join(OUTPUTS_DIR, 'cards', 'holdings-table', 'computed_values.json');
 const htCv = readJson(htCvPath);
 const rowsBySymbol = Object.fromEntries([].concat(htCv.table.rows).map(r => [r.symbol, r]));
@@ -260,20 +244,18 @@ for (const [sym, qty] of Object.entries(T4_EXPECTED_FINAL)) {
   assert(Math.round(rowsBySymbol[sym]?.value * 100) === Math.round(expectedValue * 100),
     `T4: holdings-table expected ${sym} value=${expectedValue}, got ${rowsBySymbol[sym]?.value}`);
 }
-console.log('[T4] holdings-table assertions passed: rows match holdings × prices.');
+console.log('[T4] holdings-table assertions passed: rows match holdings x prices.');
 
-// Assert portfolio-value totalValue = sum(holdings × prices)
 const pvCv = readJson(path.join(OUTPUTS_DIR, 'cards', 'portfolio-value', 'computed_values.json'));
 const expectedTotal = Object.entries(T4_EXPECTED_FINAL).reduce(
-  (sum, [sym, qty]) => sum + qty * prices[sym], 0
+  (sum, [sym, qty]) => sum + qty * prices[sym], 0,
 );
 assert(Math.round(pvCv.totalValue * 100) === Math.round(expectedTotal * 100),
   `T4: expected totalValue=${Math.round(expectedTotal * 100) / 100}, got ${pvCv.totalValue}`);
-console.log(`[T4] portfolio-value assertion passed: totalValue=${pvCv.totalValue} matches sum(holdings × prices).`);
+console.log(`[T4] portfolio-value assertion passed: totalValue=${pvCv.totalValue} matches sum(holdings x prices).`);
 
-// Assert cardstore portfolio-form holdings match iter-5
 const cardstoreHoldings = Object.fromEntries(
-  (finalCard.card_data?.holdings ?? []).map(h => [h.symbol, h.qty])
+  (finalCard.card_data?.holdings ?? []).map(h => [h.symbol, h.qty]),
 );
 for (const [sym, qty] of Object.entries(T4_EXPECTED_FINAL)) {
   assert(cardstoreHoldings[sym] === qty,