npm - yaml-flow - Versions diffs - 8.6.3 → 8.7.0 - Mend

yaml-flow 8.6.3 → 8.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (148) hide show

package/browser/adapters/firebase-storage.js +3 -0
package/browser/adapters/firestore-storage.js +3 -0
package/browser/adapters/localstorage-storage.js +4 -0
package/browser/asset-integrity.json +20 -4
package/browser/server-runtime-controlface.js +8 -0
package/examples/ARCHITECTURE.md +5 -32
package/examples/board/demo-shell-with-server.html +2 -2
package/examples/board/doc.html +2 -2
package/examples/board/server/board-server.js +4 -2
package/examples/board/server/chat-flow/flow-steps.json +10 -5
package/examples/board/test/server-http-test.js +93 -0
package/examples/board-firestore/README.md +81 -0
package/examples/board-firestore/browser/board-runtime.js +263 -0
package/examples/board-firestore/firestore.indexes.json +29 -0
package/examples/board-firestore/package.json +14 -0
package/examples/board-firestore/server/adapters/firestore-archive-factory.js +59 -0
package/examples/board-firestore/server/adapters/firestore-blob-storage.js +82 -0
package/examples/board-firestore/server/adapters/firestore-board-adapter.js +127 -0
package/examples/board-firestore/server/adapters/firestore-journal-storage.js +54 -0
package/examples/board-firestore/server/adapters/firestore-kv-storage.js +47 -0
package/examples/board-firestore/server/adapters/firestore-lock.js +62 -0
package/examples/board-firestore/server/adapters/firestore-queue-storage.js +186 -0
package/examples/board-firestore/server/adapters/firestore-scratch-storage.js +50 -0
package/examples/board-firestore/server/worker.js +146 -0
package/lib/{artifacts-store-lib-BR-Samty.d.cts → artifacts-store-lib-D9nMkVcE.d.cts} +1 -1
package/lib/{artifacts-store-lib-DT7XlWUL.d.ts → artifacts-store-lib-DSSMqVL2.d.ts} +1 -1
package/lib/artifacts-store-public.d.cts +2 -2
package/lib/artifacts-store-public.d.ts +2 -2
package/lib/board-live-cards-mcp.cjs +1 -1
package/lib/board-live-cards-mcp.d.cts +51 -3
package/lib/board-live-cards-mcp.d.ts +51 -3
package/lib/board-live-cards-mcp.js +1 -1
package/lib/board-live-cards-node.cjs +8 -8
package/lib/board-live-cards-node.d.cts +13 -9
package/lib/board-live-cards-node.d.ts +13 -9
package/lib/board-live-cards-node.js +8 -8
package/lib/{board-live-cards-public-BMUIPOrc.d.ts → board-live-cards-public-D-DJek3X.d.ts} +1 -1
package/lib/{board-live-cards-public-wkNmBIRC.d.cts → board-live-cards-public-DQzPe7A9.d.cts} +1 -1
package/lib/board-live-cards-public-async-3hUuHxDx.d.ts +55 -0
package/lib/board-live-cards-public-async-CgMCYYft.d.cts +55 -0
package/lib/board-live-cards-public.d.cts +1 -1
package/lib/board-live-cards-public.d.ts +1 -1
package/lib/board-live-cards-server-runtime.cjs +1 -1
package/lib/board-live-cards-server-runtime.d.cts +10 -6
package/lib/board-live-cards-server-runtime.d.ts +10 -6
package/lib/board-live-cards-server-runtime.js +1 -1
package/lib/board-platform-adapter-async-DOfEq_HC.d.cts +129 -0
package/lib/board-platform-adapter-async-JZPCzZnH.d.ts +129 -0
package/lib/board-worker-adapter.cjs +3 -3
package/lib/board-worker-adapter.js +3 -3
package/lib/card-store-public.d.cts +1 -1
package/lib/card-store-public.d.ts +1 -1
package/lib/{chat-storage-lib-BIUbE-fM.d.cts → chat-storage-lib-B9Q34Dyv.d.cts} +1 -1
package/lib/{chat-storage-lib-BlG-sobS.d.ts → chat-storage-lib-DB9iSai2.d.ts} +1 -1
package/lib/chat-store-public.d.cts +2 -2
package/lib/chat-store-public.d.ts +2 -2
package/lib/chunk-272IYUKT.cjs +2 -0
package/lib/chunk-5XHOHTLZ.cjs +2 -0
package/lib/chunk-6APH25VI.js +2 -0
package/lib/chunk-7FGPOGRV.cjs +2 -0
package/lib/chunk-7ICPAABP.cjs +7 -0
package/lib/chunk-CPAXTVBQ.cjs +2 -0
package/lib/chunk-DDYSXP2A.cjs +3 -0
package/lib/chunk-EGRHWZRV.js +2 -0
package/lib/chunk-GL2OHR2E.cjs +2 -0
package/lib/chunk-IPLSRN6P.cjs +4 -0
package/lib/chunk-J5J6BG7B.js +2 -0
package/lib/chunk-KAWQPLIE.cjs +2 -0
package/lib/chunk-LPXVVMQT.cjs +2 -0
package/lib/chunk-M3OU6IS5.cjs +2 -0
package/lib/chunk-M6STQR5F.cjs +2 -0
package/lib/chunk-NJJ7WEDT.cjs +2 -0
package/lib/chunk-NKIQRCOM.cjs +2 -0
package/lib/chunk-NM6O35RY.cjs +2 -0
package/lib/chunk-NTICU4OK.js +2 -0
package/lib/chunk-O7NOHKVR.js +2 -0
package/lib/chunk-PRHQBGPT.js +2 -0
package/lib/chunk-S44QZUDX.js +2 -0
package/lib/chunk-SGV7PU4H.js +2 -0
package/lib/chunk-TSN3RTXT.js +4 -0
package/lib/chunk-VXJHBWK3.js +2 -0
package/lib/chunk-WHDEBJLT.js +7 -0
package/lib/chunk-XYN5D3GL.js +2 -0
package/lib/chunk-YGALANRO.js +2 -0
package/lib/chunk-ZJ5M5COT.js +2 -0
package/lib/chunk-ZXQR7GHT.js +3 -0
package/lib/cloud-storage.cjs +1 -1
package/lib/cloud-storage.d.cts +5 -3
package/lib/cloud-storage.d.ts +5 -3
package/lib/cloud-storage.js +1 -1
package/lib/firebase-storage/index.cjs +3 -0
package/lib/firebase-storage/index.d.cts +57 -0
package/lib/firebase-storage/index.d.ts +57 -0
package/lib/firebase-storage/index.js +3 -0
package/lib/firestore-storage/index.cjs +3 -0
package/lib/firestore-storage/index.d.cts +98 -0
package/lib/firestore-storage/index.d.ts +98 -0
package/lib/firestore-storage/index.js +3 -0
package/lib/localstorage-storage/index.cjs +2 -0
package/lib/localstorage-storage/index.d.cts +39 -0
package/lib/localstorage-storage/index.d.ts +39 -0
package/lib/localstorage-storage/index.js +2 -0
package/lib/mcp-tool-registries-BBObLYga.d.ts +41 -0
package/lib/mcp-tool-registries-W3TRj6O5.d.cts +41 -0
package/lib/queue-lane-registry-PaZuFpwp.d.cts +30 -0
package/lib/queue-lane-registry-PaZuFpwp.d.ts +30 -0
package/lib/server-jobs-queue-runner/index.cjs +2 -0
package/lib/server-jobs-queue-runner/index.d.cts +22 -0
package/lib/server-jobs-queue-runner/index.d.ts +22 -0
package/lib/server-jobs-queue-runner/index.js +2 -0
package/lib/server-runtime/index.cjs +1 -1
package/lib/server-runtime/index.d.cts +11 -17
package/lib/server-runtime/index.d.ts +11 -17
package/lib/server-runtime/index.js +1 -1
package/lib/server-runtime-agentface/index.cjs +2 -0
package/lib/server-runtime-agentface/index.d.cts +53 -0
package/lib/server-runtime-agentface/index.d.ts +53 -0
package/lib/server-runtime-agentface/index.js +2 -0
package/lib/server-runtime-controlface/index.cjs +2 -0
package/lib/server-runtime-controlface/index.d.cts +80 -0
package/lib/server-runtime-controlface/index.d.ts +80 -0
package/lib/server-runtime-controlface/index.js +2 -0
package/lib/server-runtime-core/index.cjs +2 -0
package/lib/server-runtime-core/index.d.cts +376 -0
package/lib/server-runtime-core/index.d.ts +376 -0
package/lib/server-runtime-core/index.js +2 -0
package/lib/server-runtime-watchers/index.cjs +2 -0
package/lib/server-runtime-watchers/index.d.cts +127 -0
package/lib/server-runtime-watchers/index.d.ts +127 -0
package/lib/server-runtime-watchers/index.js +2 -0
package/lib/server-runtime-webhooks/index.cjs +2 -0
package/lib/server-runtime-webhooks/index.d.cts +34 -0
package/lib/server-runtime-webhooks/index.d.ts +34 -0
package/lib/server-runtime-webhooks/index.js +2 -0
package/lib/storage-async-interface-BRR4eBjx.d.cts +81 -0
package/lib/storage-async-interface-DhlOVPSp.d.ts +81 -0
package/lib/{queue-lane-registry-BPKWWgd4.d.cts → types-BzQY45dH.d.cts} +8 -34
package/lib/{queue-lane-registry-Be6c0ftj.d.ts → types-CF2xUcZW.d.ts} +8 -34
package/package.json +46 -2
package/examples/board-local/demo-shell-localstorage.html +0 -843
package/lib/board-live-cards-public-async-DKZqbJVU.d.ts +0 -256
package/lib/board-live-cards-public-async-dMWNbWq6.d.cts +0 -256
package/lib/chunk-GJJMEAVN.cjs +0 -2
package/lib/chunk-GLIX37VG.cjs +0 -8
package/lib/chunk-LRVAVWAG.js +0 -8
package/lib/chunk-MLVTJASJ.js +0 -2
package/lib/chunk-SCWHDI3I.js +0 -2
package/lib/chunk-WOALA3V5.cjs +0 -2

package/examples/ARCHITECTURE.md CHANGED Viewed

@@ -72,39 +72,13 @@ 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`.
+Vendored jsonata engine for browser bundles that need in-browser card computation.
 ```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()`
+No public API — just sets `window.jsonataSync` for other bundles to pick up.
 ---
@@ -181,8 +155,7 @@ charts fall back to tables and markdown renders as escaped plain text.
 <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 -->
+<!-- 2. yaml-flow bundles -->
+<script src="board-livecards-client.js"></script>
+<script src="live-cards.js"></script>
 ```

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

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

package/examples/board/doc.html CHANGED Viewed

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

package/examples/board/server/board-server.js CHANGED Viewed

@@ -11,8 +11,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   createMultiBoardServerRuntime,
   createSingleBoardServerRuntime,
+} from 'yaml-flow/server-runtime-controlface';
+import {
   createHostedBoardQueueLaneRegistry,
-} from 'yaml-flow/board-live-cards-server-runtime';
+} from 'yaml-flow/server-jobs-queue-runner';
 import {
   createHostedAsyncBoardPlatformAdapter,
 } from 'yaml-flow/cloud-storage';
@@ -316,7 +318,7 @@ function makeBoardWorkerCallbackTransport(serverUrl, boardApiBasePath, transport
   const normalizedServerUrl = typeof serverUrl === 'string' ? serverUrl.trim().replace(/\/+$/, '') : '';
   const normalizedApiBasePath = typeof boardApiBasePath === 'string' ? boardApiBasePath.trim().replace(/\/+$/, '') : '';
   if (!normalizedServerUrl || !normalizedApiBasePath) return undefined;
-  return createHttpBoardCallbackTransport(`${normalizedServerUrl}${normalizedApiBasePath}/callback/board-worker`);
+  return createHttpBoardCallbackTransport(`${normalizedServerUrl}${normalizedApiBasePath}/mcp-webhooks`);
 }
 async function readJsonRequest(req) {

package/examples/board/server/chat-flow/flow-steps.json CHANGED Viewed

@@ -39,7 +39,7 @@
     },
     "open_turn": {
       "description": "Resolve the current user turn from flow-provided chat messages and parse any chat envelope options",
-      "produces_data": ["boardId", "cardId", "boardSetupRoot", "boardBaseRef", "boardRuntimeDir", "runtimeStatusDir", "cardsDir", "projectRoot", "chatFlowRoot", "chatMessages", "userText", "lastChatEntryId", "turnId", "probe", "chatHandlerMode", "chatCopilotTimeoutMs", "probeAttachmentFileIdx", "serverUrl"],
+      "produces_data": ["boardId", "cardId", "boardSetupRoot", "boardBaseRef", "boardRuntimeDir", "runtimeStatusDir", "cardsDir", "projectRoot", "chatFlowRoot", "chatMessages", "userText", "lastChatEntryId", "turnId", "probe", "chatHandlerMode", "chatCopilotTimeoutMs", "probeAttachmentFileIdx", "probeGenerateAttachment", "replyFiles", "serverUrl"],
       "input_validations": [
         "$type(cardId) = \"string\" and $length(cardId) > 0",
         "$type(chatMessages) = \"array\"",
@@ -72,6 +72,10 @@
           "data._legacyEnvelope = data._hasLegacyEnvelope ? $eval(data._rawMessageText) : null",
           "data._legacyPrompt = ($type(data._legacyEnvelope.prompt) = \"string\" and $length($trim(data._legacyEnvelope.prompt)) > 0) ? data._legacyEnvelope.prompt : (($type(data._legacyEnvelope.text) = \"string\" and $length($trim(data._legacyEnvelope.text)) > 0) ? data._legacyEnvelope.text : (($type(data._legacyEnvelope.userText) = \"string\" and $length($trim(data._legacyEnvelope.userText)) > 0) ? data._legacyEnvelope.userText : (($type(data._legacyEnvelope.query) = \"string\" and $length($trim(data._legacyEnvelope.query)) > 0) ? data._legacyEnvelope.query : null)))",
           "data.userText = data._isEchoProbe ? $trim($substring(data._rawMessageText, data._markerLen, $length(data._rawMessageText) - (data._markerLen * 2))) : (($type(data._legacyPrompt) = \"string\" and $length($trim(data._legacyPrompt)) > 0) ? $trim(data._legacyPrompt) : data._rawMessageText)",
+          "data._attachMarker = \"[attach]\"",
+          "data.probeGenerateAttachment = $lowercase($substring(data.userText, 0, $length(data._attachMarker))) = data._attachMarker",
+          "data.userText = data.probeGenerateAttachment ? $trim($substring(data.userText, $length(data._attachMarker))) : data.userText",
+          "data.replyFiles = []",
           "data.probe = data._isEchoProbe ? true : (data._legacyEnvelope.probe = true or data._legacyEnvelope.probe = 1 or ($type(data._legacyEnvelope.probe) = \"string\" and $count($filter([\"1\", \"true\", \"yes\", \"on\"], function($value) { $value = $lowercase($trim(data._legacyEnvelope.probe)) })) > 0))",
           "data.chatHandlerMode = data._isEchoProbe ? \"echo-probe\" : (($type(data._legacyEnvelope.chatHandlerMode) = \"string\" and $length($trim(data._legacyEnvelope.chatHandlerMode)) > 0) ? $lowercase($trim(data._legacyEnvelope.chatHandlerMode)) : (data.probe ? \"probe\" : \"copilot\"))",
           "data.chatCopilotTimeoutMs = ($parsePositiveInt := function($value) { ($type($value) = \"number\" and $value > 0) ? $floor($value) : (($type($value) = \"string\" and $count($match($trim($value), /^[0-9]+$/)) > 0 and $number($trim($value)) > 0) ? $floor($number($trim($value))) : null) }; $legacyTimeout := $parsePositiveInt(data._legacyEnvelope.chatTimeoutMs); $legacyCopilotTimeout := $parsePositiveInt(data._legacyEnvelope.chatCopilotTimeoutMs); $fallbackTimeout := $parsePositiveInt(expects_data.chatCopilotTimeoutMs); $legacyTimeout ? $legacyTimeout : ($legacyCopilotTimeout ? $legacyCopilotTimeout : ($fallbackTimeout ? $fallbackTimeout : 300000)))",
@@ -208,8 +212,8 @@
     },
     "probe_assistant": {
       "description": "Compute the deterministic echo assistant reply for echo-probe and test flows",
-      "expects_data": ["userText"],
-      "produces_data": ["replyText"],
+      "expects_data": ["userText", "probeGenerateAttachment"],
+      "produces_data": ["replyText", "replyFiles"],
       "input_validations": [
         "$type(userText) = \"string\""
       ],
@@ -217,6 +221,7 @@
         "type": "compute-jsonata",
         "expr": [
           "data.replyText = \"Echo: \" & expects_data.userText",
+          "data.replyFiles = expects_data.probeGenerateAttachment ? [{ 'file_name': 'probe-generated.txt', 'content_type': 'text/plain', 'text': data.replyText }] : []",
           "result = $contains($lowercase(expects_data.userText), \"simulate-failure\") ? \"failure\" : \"success\""
         ]
       },
@@ -228,7 +233,7 @@
     },
     "write_reply": {
       "description": "Append the assistant reply via MCP stage-ai-response-and-any-attachments",
-      "expects_data": ["serverUrl", "boardId", "cardId", "replyText", "turnId"],
+      "expects_data": ["serverUrl", "boardId", "cardId", "replyText", "replyFiles", "turnId"],
       "produces_data": ["replyId"],
       "input_validations": [
         "$type(serverUrl) = \"string\" and $length(serverUrl) > 0",
@@ -246,7 +251,7 @@
         "meta": "chat-handler",
         "argsMassaging": {
           "urlTemplate": "serverUrl & '/api/boards/' & boardId & '/mcp'",
-          "bodyTemplate": "{ 'tool': 'stage-ai-response-and-any-attachments', 'args': { 'card_id': cardId, 'text': replyText, 'turn_id': turnId } }"
+          "bodyTemplate": "{ 'tool': 'stage-ai-response-and-any-attachments', 'args': { 'card_id': cardId, 'text': replyText, 'turn_id': turnId, 'files': ($type(replyFiles) = 'array' ? replyFiles : []) } }"
         },
         "outputTransforms": {
           "dataTemplate": "{ 'replyId': output.data.id }"

package/examples/board/test/server-http-test.js CHANGED Viewed

@@ -45,6 +45,7 @@ function isCopilotAvailable() {
 const skipT3a = cliArgs.includes('--skip-t3a') || !isCopilotAvailable();
 const skipT3b = cliArgs.includes('--skip-t3b');
+const skipT3d = cliArgs.includes('--skip-t3d');
 const RUN_ID = `run-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
 const BOARD_ID = 'live';
@@ -952,6 +953,98 @@ try {
     console.log('[T3b] ok: upload protocol and ordered probe lifecycle observed with attachment-derived assistant reply');
   }
+  // ── T3d: probe-echo chat with one AI-generated attachment ──
+  if (skipT3d) {
+    console.log('\n=== T3d: skipped (--skip-t3d) ===');
+  } else {
+    console.log('\n=== T3d: probe-echo chat with AI-generated attachment ===');
+    // Ensure chat SSE subscription is active (T3 may have been skipped)
+    let t3dOwnedSseClient = false;
+    if (!chatSseClient) {
+      chatSseClientId = `chat-proto-t3d-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      chatSseClient = startSseClient(`${BASE}/sse?clientId=${encodeURIComponent(chatSseClientId)}`, (payload) => {
+        captureChatEvents(payload, CHAT_CARD_ID);
+      });
+      await new Promise((r) => setTimeout(r, 400));
+      const t3dSubRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/chats/subscribe-sse`, { clientId: chatSseClientId });
+      assert(t3dSubRes.status === 200, `T3d chat subscribe returned ${t3dSubRes.status}`);
+      t3dOwnedSseClient = true;
+    }
+    const t2dBeforeChats = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    assert(t2dBeforeChats.status === 200, `T3d pre chats returned ${t2dBeforeChats.status}`);
+    const t2dBeforeMessages = Array.isArray(t2dBeforeChats.data?.messages) ? t2dBeforeChats.data.messages : [];
+    const t2dBeforeCount = t2dBeforeMessages.length;
+    const t2dBeforeCard = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}`);
+    assert(t2dBeforeCard.status === 200, `T3d pre card returned ${t2dBeforeCard.status}`);
+    const t2dBeforeFiles = Array.isArray(t2dBeforeCard.data?.card_data?.files)
+      ? t2dBeforeCard.data.card_data.files
+      : [];
+    const t3dTurnId = randomTurnId();
+    const t2dPrompt = `probe generated attachment validation ${Date.now()}`;
+    const t2dEventStart = NS.chatEvents.length;
+    const t2dSendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
+      actionType: 'chat-send',
+      payload: {
+        text: `${ECHO_PROBE_MARKER}[attach] ${t2dPrompt}${ECHO_PROBE_MARKER}`,
+        'turn-id': t3dTurnId,
+      },
+    });
+    assert(t2dSendRes.status === 200, `T3d chat-send returned ${t2dSendRes.status}`);
+    const t2dLifecycle = await waitForChatPredicate((events) => {
+      return matchOrderedProbeLifecycle(events.slice(t2dEventStart), {
+        beforeCount: t2dBeforeCount,
+        beforeProcessing: false,
+        prompt: t2dPrompt,
+        assistantText: `Echo: ${t2dPrompt}`,
+        inProgressText: PROBE_IN_PROGRESS_TEXT,
+      });
+    }, 60_000, 'T3d ordered lifecycle');
+    assert(!!t2dLifecycle, 'T3d ordered lifecycle not observed');
+    const t2dAfter = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    assert(t2dAfter.status === 200, `T3d post chats returned ${t2dAfter.status}`);
+    const t2dAfterMessages = Array.isArray(t2dAfter.data?.messages) ? t2dAfter.data.messages : [];
+    const t2dNewMessages = t2dAfterMessages.slice(t2dBeforeCount);
+    assert(t2dNewMessages.length >= 4, `T3d expected at least 4 chat messages after send, got ${t2dNewMessages.length}`);
+    const t2dUser = t2dNewMessages.find((m) => m?.role === 'user');
+    const t2dInProgress = t2dNewMessages.find((m) => m?.role === 'system' && String(m?.text || '').trim().toLowerCase() === PROBE_IN_PROGRESS_TEXT);
+    const t2dAiGenerated = t2dNewMessages.find((m) => m?.role === 'system' && /^AI generated:/i.test(String(m?.text || '')));
+    const t2dAssistantMsg = t2dNewMessages.find((m) => m?.role === 'assistant');
+    assert(!!t2dUser && typeof t2dUser.id === 'string', 'T3d missing user chat message');
+    assert(!!t2dInProgress && typeof t2dInProgress.id === 'string', 'T3d missing in-progress system chat message');
+    assert(!!t2dAiGenerated && typeof t2dAiGenerated.id === 'string', 'T3d missing AI-generated attachment system chat message');
+    assert(/#\d+\s*$/.test(String(t2dAiGenerated?.text || '')), 'T3d AI-generated system message should include merged file index');
+    assert(String(t2dAiGenerated?.turn || '') === t3dTurnId, 'T3d AI-generated system turn id mismatch');
+    assert(!!t2dAssistantMsg && typeof t2dAssistantMsg.id === 'string', 'T3d missing assistant chat message');
+    assert(String(t2dAssistantMsg?.text || '').includes(`Echo: ${t2dPrompt}`), 'T3d assistant content mismatch');
+    assert(String(t2dAssistantMsg?.turn || '') === t3dTurnId, 'T3d assistant turn id mismatch');
+    const t2dFileIndexMatch = /#(\d+)\s*$/.exec(String(t2dAiGenerated?.text || ''));
+    assert(!!t2dFileIndexMatch, 'T3d AI-generated message missing file index');
+    const t2dFileIndex = Number.parseInt(t2dFileIndexMatch[1], 10);
+    assert(Number.isInteger(t2dFileIndex) && t2dFileIndex >= 0, 'T3d AI-generated message file index should be non-negative');
+    const t2dAfterCard = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}`);
+    assert(t2dAfterCard.status === 200, `T3d post card returned ${t2dAfterCard.status}`);
+    const t2dAfterFiles = Array.isArray(t2dAfterCard.data?.card_data?.files)
+      ? t2dAfterCard.data.card_data.files
+      : [];
+    assert(t2dAfterFiles.length === t2dBeforeFiles.length + 1, `T3d expected exactly one new stored file, got ${t2dAfterFiles.length - t2dBeforeFiles.length}`);
+    const t2dStoredFile = t2dAfterFiles[t2dFileIndex];
+    assert(!!t2dStoredFile, `T3d stored file missing at merged index ${t2dFileIndex}`);
+    assert(t2dStoredFile?.chat === true, 'T3d generated file should be marked as chat-origin');
+    assert(String(t2dStoredFile?.stored_name || '').length > 0, 'T3d generated file stored_name missing');
+    assert(!Object.prototype.hasOwnProperty.call(t2dStoredFile || {}, 'path'), 'T3d stored file metadata should not expose path');
+    console.log('[T3d] ok: probe staged one AI-generated attachment and appended the final reply through the shared flow');
+  }
   if (skipT4) {
     console.log('\n=== T4: skipped (--skip-t4) ===');
   } else {

package/examples/board-firestore/README.md ADDED Viewed

@@ -0,0 +1,81 @@
+# board-firestore
+Example of a [yaml-flow](https://www.npmjs.com/package/yaml-flow) board backed by **Cloud Firestore** (Firebase).
+## Architecture
+```
+Browser SPA                     Node.js Worker (server/worker.js)
+──────────────                  ──────────────────────────────────
+Firebase JS SDK ──> Firestore <── Firebase Admin SDK
+                        │
+                   board cards,
+                   queue messages,
+                   blob storage
+```
+- **Worker** — runs queue lanes (board-worker, chat-agent, process-accumulated) and exposes an HTTP control-plane on port 7900 for the browser SPA.
+- **Browser** — uses the `ServerRuntimeControlface` IIFE (`browser/server-runtime-controlface.js`) with a Firestore JS SDK adapter to read card state and trigger board operations.
+## Firestore data layout
+All data lives under `boards/{boardId}/`:
+| Subcollection | Purpose |
+|---|---|
+| `kv-{namespace}/` | `AsyncKVStorage` (card state, config, etc.) |
+| `cards/` | Card store (KV, keyed by card ID) |
+| `runtime-out/` | Computed outputs store |
+| `journal/` | Append-only board journal |
+| `worker-queue/` | Board worker task queue |
+| `chat-queue/` | Chat agent dispatch queue |
+| `process-queue/` | processAccumulated trigger queue |
+| `blobs-{namespace}/` | Blob/artifact storage |
+| `scratch/` | Ephemeral scratch storage |
+| `archive-stream-{name}/` | Named archive streams |
+| `archive-blob-{name}/` | Named archive blob collections |
+| `locks/board-lock` | Distributed lock document |
+> **Required Firestore composite index** for each queue collection:
+> Fields: `dead` (ASC), `visibleAfter` (ASC)
+## Setup
+1. Create a Firebase project and enable Firestore.
+2. Generate a service account key and save it as `server/service-account.json` (or set `GOOGLE_APPLICATION_CREDENTIALS` env var).
+3. Install dependencies:
+```bash
+npm install
+```
+4. Start the worker:
+```bash
+FIREBASE_PROJECT_ID=your-project npm run worker
+```
+The worker listens on `http://localhost:7900` by default.
+## Browser usage
+Include the IIFE bundle in your HTML:
+```html
+<script src="/browser/server-runtime-controlface.js"></script>
+```
+Then use `browser/board-runtime.js` as a reference for constructing the runtime with the Firebase JS SDK.
+## Firestore security rules (development)
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /boards/{boardId}/{document=**} {
+      allow read, write: if request.auth != null;
+    }
+  }
+}
+```

package/examples/board-firestore/browser/board-runtime.js ADDED Viewed

@@ -0,0 +1,263 @@
+/**
+ * board-firestore/browser/board-runtime.js
+ *
+ * Shows how to instantiate the ServerRuntimeControlface IIFE in a browser
+ * backed by the Firebase JS SDK (v9 modular) instead of the Admin SDK.
+ *
+ * This file is NOT bundled — it is a plain ES module that your build tool
+ * (Vite, webpack, etc.) would process. Import it from your SPA's main entry.
+ *
+ * Architecture:
+ *   Browser <──Firestore JS SDK──> Cloud Firestore
+ *       │                                │
+ *       │  ServerRuntimeControlface      │
+ *       └── createSingleBoardServerRuntime() reads/writes Firestore directly
+ *
+ * The worker (server/worker.js) runs the queue lanes and can process AI card
+ * requests without exposing any service account credentials to the browser.
+ */
+import { initializeApp } from 'firebase/app';
+import {
+  getFirestore,
+  doc,
+  getDoc,
+  setDoc,
+  deleteDoc,
+  collection,
+  query,
+  where,
+  orderBy,
+  getDocs,
+} from 'firebase/firestore';
+// ── IMPORTANT: ServerRuntimeControlface is loaded as a browser IIFE ───────────
+// Add this to your HTML: <script src="/browser/server-runtime-controlface.js"></script>
+// Then window.ServerRuntimeControlface is available.
+const { createSingleBoardServerRuntime } = window.ServerRuntimeControlface;
+// ── Firebase config — replace with your project values ────────────────────────
+const firebaseConfig = {
+  apiKey: 'YOUR_API_KEY',
+  authDomain: 'YOUR_PROJECT.firebaseapp.com',
+  projectId: 'YOUR_PROJECT_ID',
+  storageBucket: 'YOUR_PROJECT.appspot.com',
+  appId: 'YOUR_APP_ID',
+};
+const app = initializeApp(firebaseConfig);
+const db = getFirestore(app);
+const BOARD_ID = 'default';
+// ── Browser-compatible base64url helpers ───────────────────────────────────────
+function encodeDocId(key) {
+  return btoa(encodeURIComponent(key).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16))))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function makeRef(kind, value) {
+  const json = JSON.stringify({ kind, value });
+  const b64 = btoa(unescape(encodeURIComponent(json)))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return `b64:${b64}`;
+}
+// ── Minimal Firestore KV adapter for the browser (Firebase JS SDK) ─────────────
+function createBrowserKvStorage(colRef) {
+  return {
+    async read(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      if (!snap.exists()) return null;
+      return snap.data()?.value ?? null;
+    },
+    async write(key, value) {
+      await setDoc(doc(colRef, encodeDocId(key)), { k: key, value });
+    },
+    async delete(key) {
+      await deleteDoc(doc(colRef, encodeDocId(key)));
+    },
+    async listKeys(prefix = '') {
+      let q = colRef;
+      if (prefix) {
+        q = query(colRef, where('k', '>=', prefix), where('k', '<', prefix + '\uf8ff'), orderBy('k'));
+      } else {
+        q = query(colRef, orderBy('k'));
+      }
+      const snap = await getDocs(q);
+      return snap.docs.map((d) => d.data().k ?? d.id);
+    },
+  };
+}
+// ── Minimal Firestore blob adapter for the browser ────────────────────────────
+function createBrowserBlobStorage(colRef) {
+  return {
+    async read(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      if (!snap.exists()) return null;
+      return snap.data()?.content ?? null;
+    },
+    async write(key, content) {
+      await setDoc(doc(colRef, encodeDocId(key)), { k: key, content });
+    },
+    async exists(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      return snap.exists();
+    },
+    async remove(key) {
+      await deleteDoc(doc(colRef, encodeDocId(key)));
+    },
+    async listKeys(prefix = '') {
+      let q = prefix
+        ? query(colRef, where('k', '>=', prefix), where('k', '<', prefix + '\uf8ff'), orderBy('k'))
+        : query(colRef, orderBy('k'));
+      const snap = await getDocs(q);
+      return snap.docs.map((d) => d.data().k ?? d.id);
+    },
+  };
+}
+// ── Board platform adapter shim for browser use ────────────────────────────────
+// NOTE: The browser adapter is read-heavy (renders current card state) and
+// delegates writes to the worker. The runtime will route execution dispatch
+// to the worker via HTTP if you configure invocationAdapter with an http:post ref.
+function createBrowserFirestoreAdapter() {
+  const boardDoc = (name) => collection(db, 'boards', BOARD_ID, name);
+  return {
+    kvStorage: (namespace) => createBrowserKvStorage(boardDoc(`kv-${namespace || 'root'}`)),
+    kvStorageForRef: (ref) => createBrowserKvStorage(boardDoc('kv-root')),
+    blobStorage: (namespace) => createBrowserBlobStorage(boardDoc(`blobs-${namespace || 'root'}`)),
+    scratchStorage: () => ({
+      ...createBrowserBlobStorage(boardDoc('scratch')),
+      getUniqueKey: (prefix = 'scratch-') => `${prefix}${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      create: async (data, prefix = 'scratch-') => {
+        const key = `${prefix}${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        await createBrowserBlobStorage(boardDoc('scratch')).write(key, data);
+        return key;
+      },
+      keyRef: (key) => ({ kind: 'firestore-blob', value: key }),
+      config: {
+        get: async (k) => {
+          const v = await createBrowserBlobStorage(boardDoc('scratch')).read(`__config__/${k}`);
+          if (v == null) return null;
+          try { return JSON.parse(v); } catch { return v; }
+        },
+        set: async (k, v) =>
+          createBrowserBlobStorage(boardDoc('scratch')).write(`__config__/${k}`, JSON.stringify(v)),
+      },
+    }),
+    scratchStorageForRef: () => ({ read: async () => null, write: async () => {}, exists: async () => false, remove: async () => {}, listKeys: async () => [], getUniqueKey: () => `${Date.now()}`, create: async () => `${Date.now()}`, keyRef: () => ({ kind: 'unknown', value: '' }), config: { get: async () => null, set: async () => {} } }),
+    journalStorage: () => ({
+      append: async (payload) => {
+        const id = `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`;
+        await setDoc(doc(db, 'boards', BOARD_ID, 'journal', id), { id, createdAt: new Date().toISOString(), payload });
+        return { id, payload };
+      },
+      readAll: async () => {
+        const snap = await getDocs(query(collection(db, 'boards', BOARD_ID, 'journal'), orderBy('id')));
+        return snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+      },
+      readAfter: async (cursor) => {
+        let q = cursor
+          ? query(collection(db, 'boards', BOARD_ID, 'journal'), where('id', '>', cursor), orderBy('id'))
+          : query(collection(db, 'boards', BOARD_ID, 'journal'), orderBy('id'));
+        const snap = await getDocs(q);
+        const entries = snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+        return { entries, newCursor: entries.at(-1)?.id ?? cursor };
+      },
+    }),
+    archiveFactory: () => ({
+      stream: (name) => ({
+        append: async (payload) => {
+          const id = `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`;
+          await setDoc(doc(db, 'boards', BOARD_ID, `archive-stream-${name}`, id), { id, createdAt: new Date().toISOString(), payload });
+          return { id, payload };
+        },
+        readAll: async () => {
+          const snap = await getDocs(query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), orderBy('id')));
+          return snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+        },
+        readAfter: async (cursor) => {
+          const q = cursor
+            ? query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), where('id', '>', cursor), orderBy('id'))
+            : query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), orderBy('id'));
+          const snap = await getDocs(q);
+          const entries = snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+          return { entries, newCursor: entries.at(-1)?.id ?? cursor };
+        },
+      }),
+      blob: (name) => createBrowserBlobStorage(collection(db, 'boards', BOARD_ID, `archive-blob-${name}`)),
+      listStreams: async () => [],   // Not available in JS SDK — use Admin SDK or maintain an index
+      listBlobs: async () => [],
+      config: {
+        get: async (k) => { const s = await getDoc(doc(db, 'boards', BOARD_ID, 'archive-config', 'main')); return s.data()?.[k] ?? null; },
+        set: async (k, v) => setDoc(doc(db, 'boards', BOARD_ID, 'archive-config', 'main'), { [k]: v }, { merge: true }),
+      },
+    }),
+    archiveFactoryForRef: () => null,
+    // Queue storage: browser-side is read-only; the worker handles leasing
+    // Use null for browser-only apps; the worker processes queued tasks.
+    boardWorkerStore: () => null,
+    chatAgentStore: () => null,
+    processAccumulatedStore: () => null,
+    // Lock: no-op in browser (worker holds the real lock)
+    lock: { tryAcquire: async () => async () => {} },
+    hashFn: (value) => {
+      // Browser-safe hash (djb2 — for display only, not crypto security)
+      const str = JSON.stringify(value);
+      let hash = 5381;
+      for (let i = 0; i < str.length; i++) hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+      return (hash >>> 0).toString(16).padStart(8, '0');
+    },
+    genId: () => `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`,
+    dispatchExecution: async (_ref, _args) => ({ dispatched: false, error: 'browser-only' }),
+  };
+}
+// ── Bootstrap the in-browser runtime ──────────────────────────────────────────
+export function createBoardRuntime() {
+  const boardAdapter = createBrowserFirestoreAdapter();
+  const runtime = createSingleBoardServerRuntime({
+    boardId: BOARD_ID,
+    boards: [
+      {
+        label: `Board — ${BOARD_ID}`,
+        boardAdapter,
+        baseRef: { kind: 'firestore', value: `boards/${BOARD_ID}` },
+        cardStoreRef: makeRef('firestore', `boards/${BOARD_ID}/cards`),
+        outputsStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime-out`),
+      },
+    ],
+    invocationAdapter: {
+      // Dispatch executions to the worker via HTTP
+      async invoke(ref, args) {
+        const workerUrl = window.__BOARD_WORKER_URL__ ?? 'http://localhost:7900';
+        const res = await fetch(`${workerUrl}/api/board/invoke`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ref, args }),
+        });
+        if (!res.ok) return { dispatched: false, error: `worker HTTP ${res.status}` };
+        return res.json();
+      },
+    },
+  });
+  return runtime;
+}
+// ── Usage example ──────────────────────────────────────────────────────────────
+// const runtime = createBoardRuntime();
+// const boardStatus = await runtime.handleRuntimeApi(fakeReq, fakeRes, url);
+//
+// Or call runtime methods directly:
+// await runtime.processAccumulatedLane();   // trigger a card computation pass
+// const cards = await runtime.cardStore?.list();  // read current card state

package/examples/board-firestore/firestore.indexes.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "worker-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "chat-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "process-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}

package/examples/board-firestore/package.json ADDED Viewed

@@ -0,0 +1,14 @@
+{
+  "name": "board-firestore",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "worker": "node server/worker.js",
+    "agents": "node server/agents.js"
+  },
+  "dependencies": {
+    "firebase-admin": "^12.0.0",
+    "yaml-flow": "*"
+  }
+}