yaml-flow 8.0.1 → 8.0.4

package/cli/{types-C2YQXFwo.d.ts → types-D2XnLbBj.d.ts}

@@ -277,6 +277,21 @@ interface BoardNonCorePlatformAdapter extends BoardPlatformAdapter {
     makeTempFilePath(label: string, ext?: string): string;
     /** Absolute-path blob I/O for temp files and card file references. */
     absoluteBlob: BlobStorage;
+    /**
+     * Default timeouts (ms) for synchronous executor invocations.
+     * Each field can also be overridden per-source via source_def.timeout.
+     *
+     *   validationMs — validate-source-def, validate-card-preflight (structural, fast). Default: 10_000.
+     *   preflightMs  — probe-source-preflight (runs a real source fetch). Default: 60_000.
+     *   probeMs      — run-source-fetch in probe/simulation paths. Default: 60_000.
+     *   describeMs   — describe-capabilities introspection. Default: 10_000.
+     */
+    executorTimeouts?: {
+        validationMs?: number;
+        preflightMs?: number;
+        probeMs?: number;
+        describeMs?: number;
+    };
 }
 interface BoardLiveCardsNonCorePublic {
     /** params: cardId? or all?; returns array even for single card */

package/examples/ARCHITECTURE.md

@@ -0,0 +1,188 @@
+# yaml-flow — Architecture & Reuse Guide
+
+A quick reference for anyone integrating yaml-flow into their own stack,
+or adapting it to different infrastructure.
+
+---
+
+## Package exports — layered architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  YOUR HOST SHIM  (thin, you write — a few dozen lines)           │
+│  Adapt your platform's request/response → RuntimeRequest/        │
+│  RuntimeResponse. Wire SSE streaming. Construct adapters.        │
+├──────────────────────────────────────────────────────────────────┤
+│  PLATFORM ADAPTER  →  board-live-cards-node                      │
+│  FS + local-process reference implementation.                    │
+│  Replace this layer for different storage/invocation infra.      │
+│  Implement: BoardPlatformAdapter, CardStore, ArtifactsStore, ... │
+├──────────────────────────────────────────────────────────────────┤
+│  SERVER ORCHESTRATION  →  board-live-cards-server-runtime        │
+│  Routes, board lifecycle, chat/file orchestration.               │
+│  Platform-free — all I/O injected via adapters.                  │
+│  Works on Node HTTP, Azure Functions, Cloudflare Workers, etc.   │
+├──────────────────────────────────────────────────────────────────┤
+│  STORAGE CONTRACTS  →  card-store-public, artifacts-store-public │
+│  Interfaces only. No implementations. Code against these.        │
+├──────────────────────────────────────────────────────────────────┤
+│  CORE LOGIC  →  . / board-live-cards-public, step-machine-public │
+│  Pure computation — card graph, event engine, step machine.      │
+│  No FS, no Node, no HTTP. Works anywhere (browser included).     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**Reuse everything except the platform adapter layer.**
+To move from Node+FS to Azure Functions+Cosmos DB:
+- Implement your own `BoardPlatformAdapter` backed by Cosmos/Azure Blob
+- Write a thin host shim that maps Azure `HttpRequest` → `RuntimeRequest`
+- Extend ref dispatch for new `howToRun` kinds via `createExecutionRefInvoker({ transports, syncTransports })` — no layer replacement needed
+- Everything else — server runtime, core logic, client bundles — is unchanged
+
+---
+
+## Worker side — board-worker-adapter
+
+Used by any **external process** the board dispatches work to:
+task executors, chat handlers, inference workers, etc.
+
+Provides the full worker contract in a single zero-dependency file:
+- `parseRef` / `serializeRef` — wire-format ref decoding
+- `blobStorageForRef` — resolve a ref to its storage backend (`read`/`write`)
+- `reportComplete` / `reportFailed` — call back to the board on completion
+- `ExecutionRef`, `TaskCallback`, `BlobStorage` — the stable protocol types
+
+**Adapting to different infrastructure:**
+
+| What changes | What to do |
+|---|---|
+| Storage backend (Cosmos, Azure Blob, S3) | Add a new `case` in `blobStorageForRef()` for the new `KindValueRef.kind` |
+| Callback transport (Service Bus, queue) | Add a new `case` in `reportComplete`/`reportFailed` for the new `howToRun` value |
+| Worker hosting (Azure Functions, Lambda) | Nothing here — the worker reads its inRef and calls `reportComplete`; hosting is transparent |
+
+Tip: copy this file into your worker project and extend locally.
+The interfaces are the stable contract; backends are just switch cases.
+
+---
+
+## Browser bundles
+
+All browser bundles are standalone IIFE files — no bundler required.
+Include them with a `<script>` tag. Each sets a global on `window`.
+
+### compute-jsonata.js → `window.jsonataSync`
+
+Vendored jsonata engine for in-browser card computation.
+**Must be loaded before** `board-livecards-localstorage.js`.
+
+```html
+<script src="compute-jsonata.js"></script>
+```
+
+No public API — just sets `window.jsonataSync` for the other bundles to pick up.
+
+---
+
+### board-livecards-localstorage.js → `window.BoardLiveCardsLocalStorage`
+
+**Drop-in full board engine for the browser** — no server required.
+
+Bundles: board engine + card computation + localStorage adapter.
+Ideal for demos, offline use, or prototyping before wiring up a server.
+
+```html
+<script src="compute-jsonata.js"></script>
+<script src="board-livecards-localstorage.js"></script>
+<script>
+  const app = BoardLiveCardsLocalStorage.create('my-board', {
+    cards: [ /* card JSON objects */ ],
+    taskExecutor: async (ref, args) => { /* your async task handler */ },
+  });
+  await app.bootstrap();
+  const state = app.getState();
+  // → feed to live-cards.js via LiveCard.init(...)
+</script>
+```
+
+Key exports: `create()`, `selectLiveCardModel()`, `selectAllLiveCardModels()`
+
+---
+
+### board-livecards-client.js → `window.BoardLiveCardsClient`
+
+**Client for a yaml-flow HTTP/SSE server.** Two modes in one bundle:
+
+1. **SSE/HTTP mode** — connects to a `board-live-cards-server-runtime` host:
+```html
+<script src="board-livecards-client.js"></script>
+<script>
+  const client = BoardLiveCardsClient.createBoardRuntimeClient({
+    fetchServer,
+    boardPaths: BoardLiveCardsClient.defaultBoardPaths('my-board'),
+    getServerOrigin,
+  });
+  await client.bootstrapBoard({ boardId: 'my-board', rootElement: el });
+</script>
+```
+
+2. **Custom transport mode** — use the platform-free state layer with Firebase,
+   WebSocket, or any other transport. Import `buildBoardState`, `applyNotification`,
+   `selectAllLiveCardModels` and drive them yourself.
+
+Key exports: `createBoardRuntimeClient`, `defaultBoardPaths`, `singleBoardPaths`,
+`buildBoardState`, `applyNotification`, `selectLiveCardModel`, `selectAllLiveCardModels`
+
+---
+
+### live-cards.js → `window.LiveCard`
+
+**UI rendering engine** — turns board state (card models) into interactive HTML.
+
+Renders card view definitions (tables, metrics, charts, markdown, forms, badges, etc.)
+into DOM elements. Handles card-to-card `requires`/`provides` token wiring,
+action buttons, chat panels, file attachments, and editable fields.
+
+```html
+<script src="live-cards.js"></script>
+<script>
+  const engine = LiveCard.init({
+    resolve,          // (nodeId) → card model
+    onPatch,          // called when user edits a field
+    onAction,         // called on action button click
+    getChatMessages,  // () → messages for chat panel
+    markdown,         // optional: (text) → html  (e.g. marked.parse)
+    sanitize,         // optional: (html) → safe html  (e.g. DOMPurify.sanitize)
+    chartLib,         // optional: Chart.js constructor
+  });
+</script>
+```
+
+**Optional external JS** — all injected, none bundled:
+
+| Library | Purpose | Inject via |
+|---|---|---|
+| [Bootstrap 5](https://getbootstrap.com/) | Layout, forms, badges | `<link>` + `<script>` (CSS + JS) |
+| [Chart.js](https://www.chartjs.org/) | Chart rendering in cards | `chartLib` config param |
+| [marked](https://marked.js.org/) | Markdown → HTML | `markdown` config param |
+| [DOMPurify](https://github.com/cure53/DOMPurify) | Sanitize markdown output | `sanitize` config param |
+
+Bootstrap CSS is required for layout. Everything else is optional — if not provided,
+charts fall back to tables and markdown renders as escaped plain text.
+
+---
+
+## Typical script load order (full browser setup)
+
+```html
+<!-- 1. Optional external libs -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5/dist/css/bootstrap.min.css">
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5/dist/js/bootstrap.bundle.min.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>
+
+<!-- 2. yaml-flow bundles — order matters -->
+<script src="compute-jsonata.js"></script>        <!-- sets window.jsonataSync -->
+<script src="board-livecards-localstorage.js"></script>  <!-- or board-livecards-client.js -->
+<script src="live-cards.js"></script>             <!-- sets window.LiveCard -->
+```

package/examples/board/demo-shell-with-server.html

@@ -19,8 +19,8 @@
   <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@8.0.1/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.1/browser/board-livecards-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.4/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.4/browser/board-livecards-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/board/demo-task-executor.js

@@ -7,24 +7,23 @@
  *   run-source-fetch        — fetch data for one source entry
  *   describe-capabilities   — print supported source kinds + schemas to stdout (JSON)
  *
- * CLI args:
- *   --in    <source.json>   Required. Path to a temp JSON file containing the source definition.
- *   --out   <result.json>   Required. Path where this executor must write its JSON result.
- *   --err   <error.txt>     Optional. Path where this executor writes an error message on failure.
- *   --extra <base64json>    Optional. Base64-encoded JSON with board topology context
- *                           (baked into .task-executor at board init time, passed blindly by the CLI).
+ * Subcommand CLI args:
  *
- * --in payload (source definition):
- *   {
- *     "bindTo":  "token_name",
- *     "outputFile": "relative/path.json",
- *     "cwd":     "<card directory>",           // injected by CLI
- *     "boardDir":"<board runtime directory>",   // injected by CLI
- *     "_projections":   { "refKey": <resolvedValue> }, // named projections from card_data/requires,
- *                                               // declared in source_defs[].projections and resolved
- *                                               // by the engine before invoking the executor
- *     // ...plus any custom fields authored on the source entry (bindTo, outputFile, projections, etc.)
- *   }
+ *   run-source-fetch
+ *     --in-ref  <b64ref>     Required. Ref to a temp JSON envelope: { source_def, callback? }
+ *     --out-ref <b64ref>     Required. Ref where this executor writes its JSON result.
+ *     --err-ref <b64ref>     Optional. Ref where this executor writes an error message on failure.
+ *     --extra   <base64json> Optional. Base64-encoded JSON with board topology context.
+ *
+ *   validate-source-def     — source def JSON on stdin; stdout: { ok, errors[] }
+ *   validate-card-preflight — card JSON on stdin; stdout: { ok, errors[] }
+ *   probe-source-preflight  — source def JSON (with _projections) on stdin;
+ *                             stdout: { ok, reachable, latencyMs, error? }
+ *   describe-capabilities   — no stdin; stdout: capability manifest JSON
+ *
+ * run-source-fetch --in-ref envelope payload:
+ *   { "source_def": { ... }, "callback": { ... } }
+ *   or legacy: raw source_def object (no callback field)
  *
  * --extra (decoded):
  *   {
@@ -506,27 +505,25 @@ async function probeSourcePreflightSubcommand(argv) {
 }
 
 // ---------------------------------------------------------------------------
-// validate-source-def — structural validation of a source definition
+// validate-source-def — structural validation of a source definition.
+// Source def JSON arrives on stdin (board-live-cards-public sends it via input:).
 // ---------------------------------------------------------------------------
-function validateSourceDefSubcommand(argv) {
-  const inIdx = argv.indexOf('--in');
-  const inFile = inIdx !== -1 ? argv[inIdx + 1] : undefined;
-
-  if (!inFile) {
-    console.error('[demo-task-executor] Usage: validate-source-def --in <source.json>');
-    process.exit(1);
-  }
-
-  if (!fs.existsSync(inFile)) {
-    console.log(JSON.stringify({ ok: false, errors: [`Input file not found: ${inFile}`] }));
+async function validateSourceDefSubcommand() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const raw = Buffer.concat(chunks).toString('utf-8').trim();
+  if (!raw) {
+    console.log(JSON.stringify({ ok: false, errors: ['No input provided on stdin'] }));
     process.exit(1);
   }
 
   let sourceDef;
   try {
-    sourceDef = readJson(inFile);
+    sourceDef = JSON.parse(raw);
   } catch (err) {
-    console.log(JSON.stringify({ ok: false, errors: [`Cannot parse source file: ${err && err.message || err}`] }));
+    console.log(JSON.stringify({ ok: false, errors: [`Cannot parse input: ${err && err.message || err}`] }));
     process.exit(1);
   }
 
@@ -710,7 +707,7 @@ async function main() {
     return;
   }
   if (sub === 'validate-source-def') {
-    validateSourceDefSubcommand(process.argv.slice(3));
+    await validateSourceDefSubcommand();
     return;
   }
 

package/examples/board-local/demo-shell-localstorage.html

@@ -6,13 +6,13 @@
   <title>Example Board Demo (LocalStorage Runtime)</title>
   <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@8.0.1/browser/compute-jsonata.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.4/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@8.0.1/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.1/browser/board-livecards-localstorage.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.4/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.0.4/browser/board-livecards-localstorage.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/step-machine-cli/json/double-handler.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Ref handler: reads JSON from stdin, doubles the "sum" field, writes JSON to stdout.
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    const sum = Number(input.sum);
+    if (!Number.isFinite(sum)) {
+      process.stderr.write('double-handler requires numeric sum\n');
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ doubled: sum * 2 }));
+  } catch (err) {
+    process.stderr.write(String(err) + '\n');
+    process.exit(1);
+  }
+});

package/examples/step-machine-cli/json/mixed-handlers.flow.json

@@ -0,0 +1,118 @@
+{
+  "id": "mixed-handlers-demo",
+  "settings": {
+    "start_step": "step1_compute",
+    "max_total_steps": 15,
+    "timeout_ms": 15000
+  },
+  "steps": {
+    "step1_compute": {
+      "description": "Inline compute — adds two numbers using JSONata",
+      "expects_data": ["a", "b"],
+      "produces_data": ["sum"],
+      "input_validations": [
+        "$type(a) = \"number\"",
+        "$type(b) = \"number\""
+      ],
+      "handler": {
+        "type": "compute-jsonata",
+        "expr": [
+          "data.sum = expects_data.a + expects_data.b",
+          "result = \"success\""
+        ]
+      },
+      "transitions": {
+        "success": "step2_ref",
+        "failure": "failed_state"
+      }
+    },
+    "step2_ref": {
+      "description": "Ref handler — doubles the sum via an external Node script",
+      "expects_data": ["sum"],
+      "produces_data": ["doubled"],
+      "handler": {
+        "type": "ref",
+        "howToRun": "local-node",
+        "whatToRun": { "kind": "fs-path", "value": "./double-handler.js" }
+      },
+      "transitions": {
+        "success": "step3_scale_each",
+        "failure": "failed_state"
+      }
+    },
+    "step3_scale_each": {
+      "description": "forEach + compute-jsonata — scale doubled value by each multiplier",
+      "expects_data": ["doubled", "multipliers"],
+      "produces_data": ["scaled_values"],
+      "forEach": {
+        "items": "multipliers",
+        "as": "multiplier",
+        "concurrency": 3,
+        "collectAs": "scaled_values"
+      },
+      "handler": {
+        "type": "compute-jsonata",
+        "expr": [
+          "data.value = expects_data.doubled * expects_data.multiplier",
+          "result = \"success\""
+        ]
+      },
+      "transitions": {
+        "success": "step4_ref_each",
+        "failure": "failed_state"
+      }
+    },
+    "step4_ref_each": {
+      "description": "forEach + ref — re-scale each value via an external Node script",
+      "expects_data": ["scaled_values"],
+      "produces_data": ["final_values"],
+      "forEach": {
+        "items": "scaled_values",
+        "as": "item",
+        "concurrency": 3,
+        "collectAs": "final_values"
+      },
+      "handler": {
+        "type": "ref",
+        "howToRun": "local-node",
+        "whatToRun": { "kind": "fs-path", "value": "./scale-handler.js" },
+        "argsMassaging": {
+          "cmdTemplate": [
+            "$string(item.value)",
+            "'2'"
+          ]
+        }
+      },
+      "transitions": {
+        "success": "step5_grade",
+        "failure": "failed_state"
+      }
+    },
+    "step5_grade": {
+      "description": "Inline compute — classifies whether any final value exceeds 200",
+      "expects_data": ["final_values"],
+      "produces_data": ["grade"],
+      "handler": {
+        "type": "compute-jsonata",
+        "expr": [
+          "data.grade = $max(expects_data.final_values.scaled) >= 200 ? \"large\" : \"small\"",
+          "result = \"success\""
+        ]
+      },
+      "transitions": {
+        "success": "success_state",
+        "failure": "failed_state"
+      }
+    }
+  },
+  "terminal_states": {
+    "success_state": {
+      "return_intent": "success",
+      "return_artifacts": ["a", "b", "sum", "doubled", "scaled_values", "final_values", "grade"]
+    },
+    "failed_state": {
+      "return_intent": "failure",
+      "return_artifacts": ["error"]
+    }
+  }
+}

package/examples/step-machine-cli/json/mixed-handlers.input.json

@@ -0,0 +1,5 @@
+{
+  "a": 25,
+  "b": 30,
+  "multipliers": [1, 2, 3]
+}

package/examples/step-machine-cli/json/scale-handler.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Ref handler: takes value and multiplier as CLI args, writes JSON to stdout.
+// Usage: node scale-handler.js <value> <multiplier>
+
+const value = Number(process.argv[2]);
+const multiplier = Number(process.argv[3]);
+
+if (!Number.isFinite(value) || !Number.isFinite(multiplier)) {
+  process.stderr.write('scale-handler requires numeric value and multiplier as CLI args\n');
+  process.exit(1);
+}
+
+process.stdout.write(JSON.stringify({ scaled: value * multiplier }));

package/examples/step-machine-cli/yaml/double-handler.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Ref handler: reads JSON from stdin, doubles the "sum" field, writes JSON to stdout.
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    const sum = Number(input.sum);
+    if (!Number.isFinite(sum)) {
+      process.stderr.write('double-handler requires numeric sum\n');
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ doubled: sum * 2 }));
+  } catch (err) {
+    process.stderr.write(String(err) + '\n');
+    process.exit(1);
+  }
+});

package/examples/step-machine-cli/yaml/mixed-handlers.flow.yaml

@@ -0,0 +1,94 @@
+id: mixed-handlers-demo
+settings:
+  start_step: step1_compute
+  max_total_steps: 15
+  timeout_ms: 15000
+
+steps:
+  step1_compute:
+    description: Inline compute — adds two numbers using JSONata
+    expects_data: [a, b]
+    produces_data: [sum]
+    input_validations:
+      - $type(a) = "number"
+      - $type(b) = "number"
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.sum = expects_data.a + expects_data.b
+        - result = "success"
+    transitions:
+      success: step2_ref
+      failure: failed_state
+
+  step2_ref:
+    description: Ref handler — doubles the sum via an external Node script
+    expects_data: [sum]
+    produces_data: [doubled]
+    handler:
+      type: ref
+      howToRun: local-node
+      whatToRun: {kind: fs-path, value: ./double-handler.js}
+    transitions:
+      success: step3_scale_each
+      failure: failed_state
+
+  step3_scale_each:
+    description: forEach + compute-jsonata — scale doubled value by each multiplier
+    expects_data: [doubled, multipliers]
+    produces_data: [scaled_values]
+    forEach:
+      items: multipliers
+      as: multiplier
+      concurrency: 3
+      collectAs: scaled_values
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.value = expects_data.doubled * expects_data.multiplier
+        - result = "success"
+    transitions:
+      success: step4_ref_each
+      failure: failed_state
+
+  step4_ref_each:
+    description: forEach + ref — re-scale each value via an external Node script
+    expects_data: [scaled_values]
+    produces_data: [final_values]
+    forEach:
+      items: scaled_values
+      as: item
+      concurrency: 3
+      collectAs: final_values
+    handler:
+      type: ref
+      howToRun: local-node
+      whatToRun: {kind: fs-path, value: ./scale-handler.js}
+      argsMassaging:
+        cmdTemplate:
+          - "$string(item.value)"
+          - "'2'"
+    transitions:
+      success: step5_grade
+      failure: failed_state
+
+  step5_grade:
+    description: Inline compute — classifies whether any final value exceeds 200
+    expects_data: [final_values]
+    produces_data: [grade]
+    handler:
+      type: compute-jsonata
+      expr:
+        - 'data.grade = $max(expects_data.final_values.scaled) >= 200 ? "large" : "small"'
+        - result = "success"
+    transitions:
+      success: success_state
+      failure: failed_state
+
+terminal_states:
+  success_state:
+    return_intent: success
+    return_artifacts: [a, b, sum, doubled, scaled_values, final_values, grade]
+  failed_state:
+    return_intent: failure
+    return_artifacts: [error]

package/examples/step-machine-cli/yaml/mixed-handlers.input.json

@@ -0,0 +1,5 @@
+{
+  "a": 25,
+  "b": 30,
+  "multipliers": [1, 2, 3]
+}

package/examples/step-machine-cli/yaml/scale-handler.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Ref handler: takes value and multiplier as CLI args, writes JSON to stdout.
+// Usage: node scale-handler.js <value> <multiplier>
+
+const value = Number(process.argv[2]);
+const multiplier = Number(process.argv[3]);
+
+if (!Number.isFinite(value) || !Number.isFinite(multiplier)) {
+  process.stderr.write('scale-handler requires numeric value and multiplier as CLI args\n');
+  process.exit(1);
+}
+
+process.stdout.write(JSON.stringify({ scaled: value * multiplier }));

package/lib/{artifacts-store-lib-public-BABrgFkV.d.ts → artifacts-store-lib-public-BWC3YuLa.d.ts}

@@ -1,4 +1,4 @@
-import { C as CommandInput, a as CommandResult } from './board-live-cards-public-CsmYrvpd.js';
+import { C as CommandInput, a as CommandResult } from './board-live-cards-public-dJAl5IL-.js';
 import { B as BlobStorage } from './storage-interface-BhAON-gW.js';
 
 /**

package/lib/{artifacts-store-lib-public-DGa8BpJT.d.cts → artifacts-store-lib-public-DBICnGL6.d.cts}

@@ -1,4 +1,4 @@
-import { C as CommandInput, a as CommandResult } from './board-live-cards-public-BnmRAbQV.cjs';
+import { C as CommandInput, a as CommandResult } from './board-live-cards-public-BF9FP0mL.cjs';
 import { B as BlobStorage } from './storage-interface-BhAON-gW.cjs';
 
 /**

package/lib/artifacts-store-public.d.cts

@@ -1,5 +1,5 @@
-import './board-live-cards-public-BnmRAbQV.cjs';
-export { A as ArtifactsStorePublic, a as createArtifactsStorePublic } from './artifacts-store-lib-public-DGa8BpJT.cjs';
+import './board-live-cards-public-BF9FP0mL.cjs';
+export { A as ArtifactsStorePublic, a as createArtifactsStorePublic } from './artifacts-store-lib-public-DBICnGL6.cjs';
 import './storage-interface-BhAON-gW.cjs';
 import './execution-refs.cjs';
 import './types-BBhqYGhE.cjs';

package/lib/artifacts-store-public.d.ts

@@ -1,5 +1,5 @@
-import './board-live-cards-public-CsmYrvpd.js';
-export { A as ArtifactsStorePublic, a as createArtifactsStorePublic } from './artifacts-store-lib-public-BABrgFkV.js';
+import './board-live-cards-public-dJAl5IL-.js';
+export { A as ArtifactsStorePublic, a as createArtifactsStorePublic } from './artifacts-store-lib-public-BWC3YuLa.js';
 import './storage-interface-BhAON-gW.js';
 import './execution-refs.js';
 import './types-BBhqYGhE.js';