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

yaml-flow 8.6.4 → 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 (146) 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-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 +50 -3
package/lib/board-live-cards-mcp.d.ts +50 -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-KXWT3CY6.cjs +0 -8
package/lib/chunk-MLVTJASJ.js +0 -2
package/lib/chunk-OJLA6NLU.js +0 -8
package/lib/chunk-R5L5WUKN.js +0 -2
package/lib/chunk-WOALA3V5.cjs +0 -2
package/lib/chunk-YEB5QHGE.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.4/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.6.4/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.4/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@8.6.4/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-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": "*"
+  }
+}

package/examples/board-firestore/server/adapters/firestore-archive-factory.js ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * firestore-archive-factory.js
+ *
+ * AsyncArchiveFactory backed by Firestore.
+ * Each named stream is a subcollection: boards/{boardId}/archive-stream-{name}
+ * Each named blob collection: boards/{boardId}/archive-blob-{name}
+ *
+ * NOTE: listStreams / listBlobs use Admin SDK's listCollections() — not available
+ * in the browser Firestore JS SDK. In the browser, skip or maintain an index manually.
+ *
+ * @param {import('@google-cloud/firestore').Firestore} db
+ * @param {string} boardId
+ * @returns {import('yaml-flow/cloud-storage').AsyncArchiveFactory}
+ */
+import { createFirestoreJournalStorage } from './firestore-journal-storage.js';
+import { createFirestoreBlobStorage } from './firestore-blob-storage.js';
+export function createFirestoreArchiveFactory(db, boardId) {
+  const boardDoc = db.collection('boards').doc(boardId);
+  return {
+    stream(name) {
+      return createFirestoreJournalStorage(boardDoc.collection(`archive-stream-${name}`));
+    },
+    blob(name) {
+      return createFirestoreBlobStorage(boardDoc.collection(`archive-blob-${name}`));
+    },
+    async listStreams(prefix = '') {
+      const cols = await boardDoc.listCollections();
+      const tag = `archive-stream-${prefix}`;
+      return cols
+        .map((c) => c.id)
+        .filter((id) => id.startsWith(tag))
+        .map((id) => id.slice('archive-stream-'.length));
+    },
+    async listBlobs(prefix = '') {
+      const cols = await boardDoc.listCollections();
+      const tag = `archive-blob-${prefix}`;
+      return cols
+        .map((c) => c.id)
+        .filter((id) => id.startsWith(tag))
+        .map((id) => id.slice('archive-blob-'.length));
+    },
+    config: {
+      async get(k) {
+        const snap = await boardDoc.collection('archive-config').doc('main').get();
+        return snap.data()?.[k] ?? null;
+      },
+      async set(k, v) {
+        await boardDoc.collection('archive-config').doc('main').set({ [k]: v }, { merge: true });
+      },
+    },
+  };
+}

package/examples/board-firestore/server/adapters/firestore-blob-storage.js ADDED Viewed

@@ -0,0 +1,82 @@
+/**
+ * firestore-blob-storage.js
+ *
+ * AsyncBlobStorage backed by Firestore for text/small blobs.
+ * Document shape: { k, content, contentType?, bytesBase64? }
+ *
+ * Binary blobs (readBytes/writeBytes) are stored as base64-encoded strings.
+ * For production use with files > 1 MB, replace writeBytes/readBytes with
+ * Firebase Storage (Cloud Storage for Firebase) and store the GCS path here.
+ *
+ * @param {import('@google-cloud/firestore').CollectionReference} col
+ * @returns {import('yaml-flow/cloud-storage').AsyncBlobStorage}
+ */
+function encodeDocId(key) {
+  return Buffer.from(key).toString('base64url');
+}
+function decodeDocId(docId) {
+  return Buffer.from(docId, 'base64url').toString();
+}
+export function createFirestoreBlobStorage(col) {
+  return {
+    async read(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      return snap.data()?.content ?? null;
+    },
+    async write(key, content) {
+      await col.doc(encodeDocId(key)).set({ k: key, content });
+    },
+    async exists(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      return snap.exists;
+    },
+    async remove(key) {
+      await col.doc(encodeDocId(key)).delete();
+    },
+    async readBytes(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      const data = snap.data();
+      if (data?.bytesBase64) return Buffer.from(data.bytesBase64, 'base64');
+      if (data?.content) return Buffer.from(data.content);
+      return null;
+    },
+    async writeBytes(key, bytes) {
+      // NOTE: Firestore 1 MB doc limit. For larger files use Firebase Storage.
+      const bytesBase64 = Buffer.from(bytes).toString('base64');
+      await col.doc(encodeDocId(key)).set({ k: key, bytesBase64 });
+    },
+    async listKeys(prefix = '') {
+      let q = col;
+      if (prefix) {
+        q = col.where('k', '>=', prefix).where('k', '<', prefix + '\uf8ff');
+      }
+      const snap = await q.orderBy('k').get();
+      return snap.docs.map((d) => d.data().k ?? decodeDocId(d.id));
+    },
+    async stat(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      const data = snap.data();
+      const size = data?.bytesBase64
+        ? Math.floor((data.bytesBase64.length * 3) / 4)
+        : (data?.content?.length ?? 0);
+      return { key, size, contentType: data?.contentType ?? 'application/octet-stream' };
+    },
+    keyRef(key) {
+      return { kind: 'firestore-blob', value: `${col.path}/${encodeDocId(key)}` };
+    },
+  };
+}