yaml-flow 2.8.0 → 3.1.0

package/dist/continuous-event-graph/index.cjs

@@ -1,5 +1,10 @@
 'use strict';
 
+var fs = require('fs');
+var crypto = require('crypto');
+var child_process = require('child_process');
+require('ajv-formats');
+
 // src/event-graph/constants.ts
 var TASK_STATUS = {
   NOT_STARTED: "not-started",
@@ -27,15 +32,11 @@ function isNonActiveTask(taskState) {
   if (!taskState) return false;
   return taskState.status === TASK_STATUS.FAILED || taskState.status === TASK_STATUS.INACTIVATED;
 }
-function isRepeatableTask(taskConfig) {
-  return taskConfig.repeatable === true || typeof taskConfig.repeatable === "object" && taskConfig.repeatable !== null;
+function getRefreshStrategy(taskConfig, graphSettings) {
+  return taskConfig.refreshStrategy ?? graphSettings?.refreshStrategy ?? "data-changed";
 }
-function getRepeatableMax(taskConfig) {
-  if (taskConfig.repeatable === true) return void 0;
-  if (typeof taskConfig.repeatable === "object" && taskConfig.repeatable !== null) {
-    return taskConfig.repeatable.max;
-  }
-  return void 0;
+function getMaxExecutions(taskConfig) {
+  return taskConfig.maxExecutions;
 }
 function computeAvailableOutputs(graph, taskStates) {
   const outputs = /* @__PURE__ */ new Set();
@@ -68,7 +69,7 @@ function groupTasksByProvides(candidateTaskNames, tasks) {
 
 // src/event-graph/task-transitions.ts
 function applyTaskStart(state, taskName) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
   const updatedTask = {
     ...existingTask,
     status: "running",
@@ -83,8 +84,8 @@ function applyTaskStart(state, taskName) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function applyTaskCompletion(state, graph, taskName, result) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState();
+function applyTaskCompletion(state, graph, taskName, result, dataHash, data) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
   const taskConfig = graph.tasks[taskName];
   if (!taskConfig) {
     throw new Error(`Task "${taskName}" not found in graph`);
@@ -95,6 +96,19 @@ function applyTaskCompletion(state, graph, taskName, result) {
   } else {
     outputTokens = getProvides(taskConfig);
   }
+  const lastConsumedHashes = { ...existingTask.lastConsumedHashes };
+  const requires = taskConfig.requires ?? [];
+  for (const token of requires) {
+    for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
+      if (getProvides(otherConfig).includes(token)) {
+        const otherState = state.tasks[otherName];
+        if (otherState?.lastDataHash) {
+          lastConsumedHashes[token] = otherState.lastDataHash;
+        }
+        break;
+      }
+    }
+  }
   const updatedTask = {
     ...existingTask,
     status: "completed",
@@ -102,11 +116,11 @@ function applyTaskCompletion(state, graph, taskName, result) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
     executionCount: existingTask.executionCount + 1,
     lastEpoch: existingTask.executionCount + 1,
+    lastDataHash: dataHash,
+    data,
+    lastConsumedHashes,
     error: void 0
   };
-  if (isRepeatableTask(taskConfig)) {
-    updatedTask.status = "not-started";
-  }
   const newOutputs = [.../* @__PURE__ */ new Set([...state.availableOutputs, ...outputTokens])];
   return {
     ...state,
@@ -116,7 +130,7 @@ function applyTaskCompletion(state, graph, taskName, result) {
   };
 }
 function applyTaskFailure(state, graph, taskName, error) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
   const taskConfig = graph.tasks[taskName];
   if (taskConfig?.retry) {
     const retryCount = existingTask.retryCount + 1;
@@ -159,7 +173,7 @@ function applyTaskFailure(state, graph, taskName, error) {
   };
 }
 function applyTaskProgress(state, taskName, message, progress) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
   const updatedTask = {
     ...existingTask,
     progress: typeof progress === "number" ? progress : existingTask.progress,
@@ -175,7 +189,27 @@ function applyTaskProgress(state, taskName, message, progress) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function createDefaultTaskState() {
+function applyTaskRestart(state, taskName) {
+  const existingTask = state.tasks[taskName];
+  if (!existingTask) return state;
+  const updatedTask = {
+    ...existingTask,
+    status: "not-started",
+    startedAt: void 0,
+    completedAt: void 0,
+    failedAt: void 0,
+    error: void 0,
+    data: void 0,
+    progress: null,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createDefaultGraphEngineStore() {
   return {
     status: "not-started",
     executionCount: 0,
@@ -191,7 +225,7 @@ function createLiveGraph(config, executionId) {
   const id = executionId ?? `live-${Date.now()}`;
   const tasks = {};
   for (const taskName of Object.keys(config.tasks)) {
-    tasks[taskName] = createDefaultTaskState2();
+    tasks[taskName] = createDefaultGraphEngineStore2();
   }
   const state = {
     status: "running",
@@ -219,7 +253,7 @@ function applyEvent(live, event) {
       newState = applyTaskStart(state, event.taskName);
       break;
     case "task-completed":
-      newState = applyTaskCompletion(state, config, event.taskName, event.result);
+      newState = applyTaskCompletion(state, config, event.taskName, event.result, event.dataHash, event.data);
       break;
     case "task-failed":
       newState = applyTaskFailure(state, config, event.taskName, event.error);
@@ -227,6 +261,9 @@ function applyEvent(live, event) {
     case "task-progress":
       newState = applyTaskProgress(state, event.taskName, event.message, event.progress);
       break;
+    case "task-restart":
+      newState = applyTaskRestart(state, event.taskName);
+      break;
     case "inject-tokens":
       newState = {
         ...state,
@@ -242,6 +279,9 @@ function applyEvent(live, event) {
   }
   return { config, state: newState };
 }
+function applyEvents(live, events) {
+  return events.reduce((current, event) => applyEvent(current, event), live);
+}
 function addNode(live, name, taskConfig) {
   if (live.config.tasks[name]) return live;
   return {
@@ -251,7 +291,7 @@ function addNode(live, name, taskConfig) {
     },
     state: {
       ...live.state,
-      tasks: { ...live.state.tasks, [name]: createDefaultTaskState2() },
+      tasks: { ...live.state.tasks, [name]: createDefaultGraphEngineStore2() },
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
     }
   };
@@ -368,7 +408,7 @@ function resetNode(live, name) {
       ...live.state,
       tasks: {
         ...live.state.tasks,
-        [name]: createDefaultTaskState2()
+        [name]: createDefaultGraphEngineStore2()
       },
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
     }
@@ -407,7 +447,7 @@ function enableNode(live, name) {
 function getNode(live, name) {
   const config = live.config.tasks[name];
   if (!config) return void 0;
-  const state = live.state.tasks[name] ?? createDefaultTaskState2();
+  const state = live.state.tasks[name] ?? createDefaultGraphEngineStore2();
   return { name, config, state };
 }
 function snapshot(live) {
@@ -445,7 +485,7 @@ function restore(data) {
   }
   return { config, state };
 }
-function createDefaultTaskState2() {
+function createDefaultGraphEngineStore2() {
   return {
     status: "not-started",
     executionCount: 0,
@@ -486,38 +526,84 @@ function schedule(live) {
   const blocked = [];
   for (const [taskName, taskConfig] of Object.entries(graphTasks)) {
     const taskState = state.tasks[taskName];
-    if (!isRepeatableTask(taskConfig)) {
-      if (taskState?.status === TASK_STATUS.COMPLETED || taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-    } else {
-      if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-      const maxExec = getRepeatableMax(taskConfig);
-      if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
-        continue;
-      }
-      if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
-        continue;
-      }
-      if (taskState?.status === TASK_STATUS.COMPLETED) {
-        const requires2 = getRequires(taskConfig);
-        if (requires2.length > 0) {
-          const hasRefreshed = requires2.some((req) => {
-            for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
-              if (getProvides(otherConfig).includes(req)) {
-                const otherState = state.tasks[otherName];
-                if (otherState && otherState.executionCount > taskState.lastEpoch) return true;
+    const strategy = getRefreshStrategy(taskConfig, config.settings);
+    const rerunnable = strategy !== "once";
+    if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
+      continue;
+    }
+    const maxExec = getMaxExecutions(taskConfig);
+    if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
+      continue;
+    }
+    if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
+      continue;
+    }
+    if (!rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      continue;
+    }
+    if (rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      const requires2 = getRequires(taskConfig);
+      let shouldSkip = false;
+      switch (strategy) {
+        case "data-changed": {
+          if (requires2.length > 0) {
+            const hasChangedData = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (!otherState) continue;
+                  const consumed = taskState.lastConsumedHashes?.[req];
+                  if (otherState.lastDataHash == null) {
+                    return otherState.executionCount > taskState.lastEpoch;
+                  }
+                  return otherState.lastDataHash !== consumed;
+                }
               }
-            }
-            return false;
-          });
-          if (!hasRefreshed) continue;
-        } else {
-          continue;
+              return false;
+            });
+            if (!hasChangedData) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "epoch-changed": {
+          if (requires2.length > 0) {
+            const hasRefreshed = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (otherState && otherState.executionCount > taskState.lastEpoch) return true;
+                }
+              }
+              return false;
+            });
+            if (!hasRefreshed) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "time-based": {
+          const interval = taskConfig.refreshInterval ?? 0;
+          if (interval <= 0) {
+            shouldSkip = true;
+            break;
+          }
+          const completedAt = taskState.completedAt;
+          if (!completedAt) {
+            shouldSkip = true;
+            break;
+          }
+          const elapsedSec = (Date.now() - Date.parse(completedAt)) / 1e3;
+          if (elapsedSec < interval) shouldSkip = true;
+          break;
         }
+        case "manual":
+          shouldSkip = true;
+          break;
       }
+      if (shouldSkip) continue;
     }
     const requires = getRequires(taskConfig);
     if (requires.length === 0) {
@@ -912,12 +998,1258 @@ function getDownstream(live, nodeName) {
   }));
   return { nodeName, nodes, tokens: [...tokenSet] };
 }
+var MemoryJournal = class {
+  buffer = [];
+  append(event) {
+    this.buffer.push(event);
+  }
+  drain() {
+    const events = this.buffer;
+    this.buffer = [];
+    return events;
+  }
+  get size() {
+    return this.buffer.length;
+  }
+};
+var FileJournal = class {
+  constructor(path) {
+    this.path = path;
+    if (!fs.existsSync(path)) {
+      fs.writeFileSync(path, "", "utf-8");
+    }
+  }
+  path;
+  pending = 0;
+  append(event) {
+    fs.appendFileSync(this.path, JSON.stringify(event) + "\n", "utf-8");
+    this.pending++;
+  }
+  drain() {
+    const content = fs.readFileSync(this.path, "utf-8").trim();
+    fs.writeFileSync(this.path, "", "utf-8");
+    this.pending = 0;
+    if (!content) return [];
+    return content.split("\n").map((line) => JSON.parse(line));
+  }
+  get size() {
+    try {
+      const content = fs.readFileSync(this.path, "utf-8").trim();
+      if (!content) return 0;
+      return content.split("\n").length;
+    } catch {
+      return this.pending;
+    }
+  }
+};
+function computeDataHash(data) {
+  const json = stableStringify(data);
+  return crypto.createHash("sha256").update(json).digest("hex").slice(0, 16);
+}
+function stableStringify(value) {
+  if (value === null || value === void 0 || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+function encodeCallbackToken(taskName) {
+  const payload = JSON.stringify({ t: taskName, n: Date.now().toString(36) + Math.random().toString(36).slice(2, 6) });
+  return Buffer.from(payload).toString("base64url");
+}
+function decodeCallbackToken(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token, "base64url").toString());
+    if (typeof payload?.t === "string") return { taskName: payload.t };
+    return null;
+  } catch {
+    return null;
+  }
+}
+function createReactiveGraph(config, options, executionId) {
+  const {
+    handlers: initialHandlers,
+    journal = new MemoryJournal(),
+    onDrain
+  } = options;
+  let live = createLiveGraph(config, executionId);
+  let disposed = false;
+  const handlers = new Map(Object.entries(initialHandlers));
+  let draining = false;
+  let drainQueued = false;
+  function drain() {
+    if (disposed) return;
+    if (draining) {
+      drainQueued = true;
+      return;
+    }
+    draining = true;
+    try {
+      do {
+        drainQueued = false;
+        drainOnce();
+      } while (drainQueued);
+    } finally {
+      draining = false;
+    }
+  }
+  function drainOnce() {
+    const events = journal.drain();
+    if (events.length > 0) {
+      live = applyEvents(live, events);
+    }
+    const result = schedule(live);
+    if (events.length > 0) {
+      onDrain?.(events, live, result);
+    }
+    for (const taskName of result.eligible) {
+      dispatchTask(taskName);
+    }
+  }
+  function resolveUpstreamState(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const requires = taskConfig.requires ?? [];
+    const tokenToTask = /* @__PURE__ */ new Map();
+    for (const [name, cfg] of Object.entries(live.config.tasks)) {
+      for (const token of cfg.provides ?? []) {
+        tokenToTask.set(token, name);
+      }
+    }
+    const state = {};
+    for (const token of requires) {
+      const producerTask = tokenToTask.get(token);
+      if (producerTask) {
+        state[token] = live.state.tasks[producerTask]?.data;
+      } else {
+        state[token] = void 0;
+      }
+    }
+    return state;
+  }
+  async function runPipeline(taskName, callbackToken) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig.taskHandlers ?? [];
+    const upstreamState = resolveUpstreamState(taskName);
+    for (const handlerName of handlerNames) {
+      const handler = handlers.get(handlerName);
+      if (!handler) {
+        throw new Error(`Handler '${handlerName}' not found in registry (task '${taskName}')`);
+      }
+      const input = {
+        nodeId: taskName,
+        state: upstreamState,
+        taskState: live.state.tasks[taskName],
+        config: taskConfig,
+        callbackToken
+      };
+      const status = await handler(input);
+      if (status === "task-initiate-failure") {
+        throw new Error(`Handler '${handlerName}' returned task-initiate-failure (task '${taskName}')`);
+      }
+    }
+  }
+  function dispatchTask(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig?.taskHandlers;
+    if (!handlerNames || handlerNames.length === 0) {
+      return;
+    }
+    journal.append({
+      type: "task-started",
+      taskName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const callbackToken = encodeCallbackToken(taskName);
+    runPipeline(taskName, callbackToken).catch((error) => {
+      if (disposed) return;
+      journal.append({
+        type: "task-failed",
+        taskName,
+        error: error.message ?? String(error),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
+    });
+  }
+  return {
+    push(event) {
+      if (disposed) return;
+      if (event.type === "task-completed" && event.data && !event.dataHash) {
+        event = { ...event, dataHash: computeDataHash(event.data) };
+      }
+      journal.append(event);
+      drain();
+    },
+    pushAll(events) {
+      if (disposed) return;
+      for (const event of events) {
+        if (event.type === "task-completed" && event.data && !event.dataHash) {
+          journal.append({ ...event, dataHash: computeDataHash(event.data) });
+        } else {
+          journal.append(event);
+        }
+      }
+      drain();
+    },
+    resolveCallback(callbackToken, data, errors) {
+      if (disposed) return;
+      const decoded = decodeCallbackToken(callbackToken);
+      if (!decoded) return;
+      const { taskName } = decoded;
+      if (!live.config.tasks[taskName]) return;
+      if (errors && errors.length > 0) {
+        journal.append({
+          type: "task-failed",
+          taskName,
+          error: errors.join("; "),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } else {
+        const dataHash = data && Object.keys(data).length > 0 ? computeDataHash(data) : void 0;
+        journal.append({
+          type: "task-completed",
+          taskName,
+          data,
+          dataHash,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    addNode(name, taskConfig) {
+      if (disposed) return;
+      live = addNode(live, name, taskConfig);
+      drain();
+    },
+    removeNode(name) {
+      if (disposed) return;
+      live = removeNode(live, name);
+    },
+    addRequires(nodeName, tokens) {
+      if (disposed) return;
+      live = addRequires(live, nodeName, tokens);
+      drain();
+    },
+    removeRequires(nodeName, tokens) {
+      if (disposed) return;
+      live = removeRequires(live, nodeName, tokens);
+      drain();
+    },
+    addProvides(nodeName, tokens) {
+      if (disposed) return;
+      live = addProvides(live, nodeName, tokens);
+      drain();
+    },
+    removeProvides(nodeName, tokens) {
+      if (disposed) return;
+      live = removeProvides(live, nodeName, tokens);
+    },
+    registerHandler(name, fn) {
+      handlers.set(name, fn);
+    },
+    unregisterHandler(name) {
+      handlers.delete(name);
+    },
+    retrigger(taskName) {
+      if (disposed) return;
+      if (!live.config.tasks[taskName]) return;
+      journal.append({
+        type: "task-restart",
+        taskName,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
+    },
+    retriggerAll(taskNames) {
+      if (disposed) return;
+      for (const name of taskNames) {
+        if (!live.config.tasks[name]) continue;
+        journal.append({
+          type: "task-restart",
+          taskName: name,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    getState() {
+      return live;
+    },
+    getSchedule() {
+      return schedule(live);
+    },
+    dispose() {
+      disposed = true;
+    }
+  };
+}
+
+// src/continuous-event-graph/validate.ts
+function validateLiveGraph(live) {
+  const issues = [];
+  const { config, state } = live;
+  const tasks = getAllTasks(config);
+  const taskNames = Object.keys(tasks);
+  for (const name of taskNames) {
+    if (!state.tasks[name]) {
+      issues.push({
+        severity: "error",
+        code: "MISSING_STATE",
+        message: `Task "${name}" exists in config but has no state entry`,
+        tasks: [name]
+      });
+    }
+  }
+  for (const name of Object.keys(state.tasks)) {
+    if (!tasks[name]) {
+      issues.push({
+        severity: "warning",
+        code: "ORPHAN_STATE",
+        message: `State entry "${name}" has no corresponding task config`,
+        tasks: [name]
+      });
+    }
+  }
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (!ts) continue;
+    if (ts.status === TASK_STATUS.RUNNING && !ts.startedAt) {
+      issues.push({
+        severity: "warning",
+        code: "RUNNING_WITHOUT_START",
+        message: `Task "${name}" is running but has no startedAt timestamp`,
+        tasks: [name]
+      });
+    }
+    if (ts.status === TASK_STATUS.COMPLETED && !ts.completedAt) {
+      issues.push({
+        severity: "warning",
+        code: "COMPLETED_WITHOUT_TIMESTAMP",
+        message: `Task "${name}" is completed but has no completedAt timestamp`,
+        tasks: [name]
+      });
+    }
+    if (ts.status === TASK_STATUS.FAILED) {
+      if (!ts.failedAt) {
+        issues.push({
+          severity: "warning",
+          code: "FAILED_WITHOUT_INFO",
+          message: `Task "${name}" is failed but has no failedAt timestamp`,
+          tasks: [name]
+        });
+      }
+      if (!ts.error) {
+        issues.push({
+          severity: "info",
+          code: "FAILED_WITHOUT_INFO",
+          message: `Task "${name}" is failed but has no error message`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  const expectedOutputs = /* @__PURE__ */ new Set();
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (ts?.status === TASK_STATUS.COMPLETED) {
+      for (const token of getProvides(tasks[name])) {
+        expectedOutputs.add(token);
+      }
+    }
+  }
+  const actualOutputs = new Set(state.availableOutputs);
+  const allProducible = /* @__PURE__ */ new Set();
+  for (const taskConfig of Object.values(tasks)) {
+    for (const t of getProvides(taskConfig)) allProducible.add(t);
+    if (taskConfig.on) {
+      for (const tokens of Object.values(taskConfig.on)) {
+        for (const t of tokens) allProducible.add(t);
+      }
+    }
+    if (taskConfig.on_failure) {
+      for (const t of taskConfig.on_failure) allProducible.add(t);
+    }
+  }
+  for (const token of actualOutputs) {
+    if (!expectedOutputs.has(token) && !allProducible.has(token)) {
+      issues.push({
+        severity: "info",
+        code: "INJECTED_TOKEN",
+        message: `Token "${token}" is available but no task in the graph can produce it (likely injected)`,
+        tokens: [token]
+      });
+    }
+  }
+  for (const token of expectedOutputs) {
+    if (!actualOutputs.has(token)) {
+      issues.push({
+        severity: "warning",
+        code: "MISSING_OUTPUT",
+        message: `Token "${token}" should be available (its producer completed) but is not in availableOutputs`,
+        tokens: [token]
+      });
+    }
+  }
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (!ts) continue;
+    if (ts.executionCount < 0) {
+      issues.push({
+        severity: "error",
+        code: "INVALID_EXECUTION_COUNT",
+        message: `Task "${name}" has negative execution count: ${ts.executionCount}`,
+        tasks: [name]
+      });
+    }
+    const maxExec = tasks[name].maxExecutions;
+    if (maxExec !== void 0 && ts.executionCount > maxExec) {
+      issues.push({
+        severity: "error",
+        code: "EXCEEDED_MAX_EXECUTIONS",
+        message: `Task "${name}" executed ${ts.executionCount} times, exceeding maxExecutions of ${maxExec}`,
+        tasks: [name]
+      });
+    }
+  }
+  return buildResult(issues);
+}
+function validateReactiveGraph(input) {
+  const { graph, handlers } = input;
+  const live = graph.getState();
+  const issues = [];
+  const tasks = getAllTasks(live.config);
+  const taskNames = Object.keys(tasks);
+  const handlerNames = new Set(Object.keys(handlers));
+  const referencedHandlers = /* @__PURE__ */ new Set();
+  for (const name of taskNames) {
+    const taskHandlers = tasks[name].taskHandlers;
+    if (taskHandlers) {
+      for (const h of taskHandlers) {
+        referencedHandlers.add(h);
+      }
+    }
+  }
+  for (const name of taskNames) {
+    const taskHandlers = tasks[name].taskHandlers;
+    if (!taskHandlers) continue;
+    for (const h of taskHandlers) {
+      if (!handlers[h]) {
+        issues.push({
+          severity: "error",
+          code: "MISSING_HANDLER",
+          message: `Task "${name}" references handler "${h}" but it is not in the registry`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  for (const name of handlerNames) {
+    if (!referencedHandlers.has(name)) {
+      issues.push({
+        severity: "warning",
+        code: "ORPHAN_HANDLER",
+        message: `Handler "${name}" is registered but not referenced by any task's taskHandlers`,
+        tasks: [name]
+      });
+    }
+  }
+  const liveResult = validateLiveGraph(live);
+  issues.push(...liveResult.issues);
+  return buildResult(issues);
+}
+function buildResult(issues) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  return {
+    valid: errors.length === 0,
+    issues,
+    errors,
+    warnings
+  };
+}
+
+// src/continuous-event-graph/mutate.ts
+function mutateGraph(live, mutations) {
+  let current = live;
+  for (const mutation of mutations) {
+    current = applySingleMutation(current, mutation);
+  }
+  return current;
+}
+function applySingleMutation(live, mutation) {
+  switch (mutation.type) {
+    case "add-node":
+      return addNode(live, mutation.name, mutation.config);
+    case "remove-node":
+      return removeNode(live, mutation.name);
+    case "add-requires":
+      return addRequires(live, mutation.taskName, mutation.tokens);
+    case "remove-requires":
+      return removeRequires(live, mutation.taskName, mutation.tokens);
+    case "add-provides":
+      return addProvides(live, mutation.taskName, mutation.tokens);
+    case "remove-provides":
+      return removeProvides(live, mutation.taskName, mutation.tokens);
+    case "inject-tokens":
+      return injectTokens(live, mutation.tokens);
+    case "drain-tokens":
+      return drainTokens(live, mutation.tokens);
+    case "reset-node":
+      return resetNode(live, mutation.name);
+    case "disable-node":
+      return disableNode(live, mutation.name);
+    case "enable-node":
+      return enableNode(live, mutation.name);
+    case "apply-events":
+      return applyEvents(live, mutation.events);
+    default:
+      throw new Error(`Unknown mutation type: ${mutation.type}`);
+  }
+}
+function createCallbackHandler(fn, getResolve) {
+  return async (input) => {
+    const { callbackToken } = input;
+    Promise.resolve(fn(input)).then((data) => getResolve()(callbackToken, data)).catch((err) => getResolve()(callbackToken, {}, [err instanceof Error ? err.message : String(err)]));
+    return "task-initiated";
+  };
+}
+function createFireAndForgetHandler(fn, getResolve) {
+  return async (input) => {
+    const { callbackToken } = input;
+    Promise.resolve(fn(input)).then(() => getResolve()(callbackToken, {})).catch(() => getResolve()(callbackToken, {}));
+    return "task-initiated";
+  };
+}
+function createShellHandler(options) {
+  const {
+    command: commandTemplate,
+    cwd,
+    env,
+    timeoutMs = 3e4,
+    exitCodeMap,
+    captureOutput = false,
+    getResolve
+  } = options;
+  return async (input) => {
+    const { callbackToken, nodeId } = input;
+    const command = commandTemplate.replace(/\$\{taskName\}/g, nodeId);
+    child_process.exec(
+      command,
+      {
+        cwd,
+        env: env ? { ...process.env, ...env } : void 0,
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024
+        // 10MB
+      },
+      (error, stdout, stderr) => {
+        const exitCode = error?.code ?? (error ? 1 : 0);
+        if (exitCode !== 0 && !exitCodeMap?.[exitCode]) {
+          getResolve()(callbackToken, {}, [`Command exited with code ${exitCode}: ${stderr || error?.message}`]);
+          return;
+        }
+        const data = {};
+        if (captureOutput) {
+          data.stdout = stdout;
+          data.stderr = stderr;
+          data.exitCode = exitCode;
+        }
+        getResolve()(callbackToken, data);
+      }
+    );
+    return "task-initiated";
+  };
+}
+function detectRuntime(scriptPath) {
+  if (scriptPath.endsWith(".js") || scriptPath.endsWith(".mjs") || scriptPath.endsWith(".ts")) return "node";
+  if (scriptPath.endsWith(".py")) return "python3";
+  if (scriptPath.endsWith(".sh")) return "bash";
+  return "bash";
+}
+function createScriptHandler(options) {
+  const {
+    scriptPath,
+    runtime,
+    args = [],
+    cwd,
+    timeoutMs = 6e4,
+    captureOutput = false,
+    getResolve
+  } = options;
+  const resolvedRuntime = runtime ?? detectRuntime(scriptPath);
+  const shellArgs = [ctx_taskName_placeholder, ...args].join(" ");
+  const command = `${resolvedRuntime} ${scriptPath} ${shellArgs}`;
+  return createShellHandler({
+    command: command.replace(ctx_taskName_placeholder, "${taskName}"),
+    cwd,
+    timeoutMs,
+    captureOutput,
+    getResolve
+  });
+}
+var ctx_taskName_placeholder = "__TASK_NAME__";
+function createWebhookHandler(options) {
+  const {
+    url: urlTemplate,
+    method = "POST",
+    headers = {},
+    timeoutMs = 3e4,
+    failOnNon2xx = true,
+    getResolve
+  } = options;
+  return async (input) => {
+    const { callbackToken, nodeId, config } = input;
+    const url = urlTemplate.replace(/\$\{taskName\}/g, nodeId);
+    const body = JSON.stringify({
+      taskName: nodeId,
+      callbackToken,
+      config
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    fetch(url, {
+      method,
+      headers: { "Content-Type": "application/json", ...headers },
+      body,
+      signal: controller.signal
+    }).then(async (response) => {
+      clearTimeout(timer);
+      if (failOnNon2xx && !response.ok) {
+        const text = await response.text().catch(() => "");
+        getResolve()(callbackToken, {}, [`HTTP ${response.status}: ${text}`]);
+        return;
+      }
+      const data = await response.json().catch(() => ({}));
+      getResolve()(callbackToken, data);
+    }).catch((err) => {
+      clearTimeout(timer);
+      getResolve()(callbackToken, {}, [err instanceof Error ? err.message : String(err)]);
+    });
+    return "task-initiated";
+  };
+}
+function createNoopHandler(getResolve, staticData) {
+  return async (input) => {
+    getResolve()(input.callbackToken, staticData ?? {});
+    return "task-initiated";
+  };
+}
+
+// src/card-compute/index.ts
+function deepGet(obj, path) {
+  if (!path || !obj) return void 0;
+  const parts = path.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length; i++) {
+    if (cur == null) return void 0;
+    cur = cur[parts[i]];
+  }
+  return cur;
+}
+function deepSet(obj, path, value) {
+  const parts = path.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] == null || typeof cur[parts[i]] !== "object") cur[parts[i]] = {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+var _fns = {};
+_fns.sum = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input : [];
+  return opts.field ? a.reduce((s, r) => s + (Number(r[opts.field]) || 0), 0) : a.reduce((s, v) => s + (Number(v) || 0), 0);
+};
+_fns.avg = (input, _e, opts) => {
+  const s = _fns.sum(input, _e, opts);
+  const n = Array.isArray(input) ? input.length : 1;
+  return n ? s / n : 0;
+};
+_fns.min = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input : [];
+  const vals = opts.field ? a.map((r) => Number(r[opts.field])) : a.map(Number);
+  return vals.length ? Math.min(...vals) : 0;
+};
+_fns.max = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input : [];
+  const vals = opts.field ? a.map((r) => Number(r[opts.field])) : a.map(Number);
+  return vals.length ? Math.max(...vals) : 0;
+};
+_fns.count = (input) => Array.isArray(input) ? input.length : input != null ? 1 : 0;
+_fns.first = (input) => Array.isArray(input) ? input[0] : input;
+_fns.last = (input) => Array.isArray(input) ? input[input.length - 1] : input;
+_fns.add = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.reduce((s, v) => s + Number(v), 0);
+};
+_fns.sub = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 ? Number(a[0]) - Number(a[1]) : 0;
+};
+_fns.mul = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.reduce((s, v) => s * Number(v), 1);
+};
+_fns.div = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && Number(a[1]) !== 0 ? Number(a[0]) / Number(a[1]) : 0;
+};
+_fns.round = (input, _e, opts) => {
+  const decimals = opts.decimals != null ? opts.decimals : 0;
+  const factor = Math.pow(10, decimals);
+  return Math.round(Number(input) * factor) / factor;
+};
+_fns.abs = (input) => Math.abs(Number(input));
+_fns.mod = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 ? Number(a[0]) % Number(a[1]) : 0;
+};
+_fns.gt = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && Number(a[0]) > Number(a[1]);
+};
+_fns.gte = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && Number(a[0]) >= Number(a[1]);
+};
+_fns.lt = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && Number(a[0]) < Number(a[1]);
+};
+_fns.lte = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && Number(a[0]) <= Number(a[1]);
+};
+_fns.eq = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && a[0] === a[1];
+};
+_fns.neq = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 && a[0] !== a[1];
+};
+_fns.and = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.every(Boolean);
+};
+_fns.or = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.some(Boolean);
+};
+_fns.not = (input) => !input;
+_fns.concat = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.map((v) => v != null ? String(v) : "").join("");
+};
+_fns.upper = (input) => String(input || "").toUpperCase();
+_fns.lower = (input) => String(input || "").toLowerCase();
+_fns.template = (input, _e, opts) => {
+  let t = String(opts.format || "");
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    for (const k of Object.keys(input)) {
+      const v = input[k];
+      t = t.split("{{" + k + "}}").join(v != null ? String(v) : "");
+    }
+  }
+  return t;
+};
+_fns.join = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input : [];
+  const sep = opts.separator != null ? String(opts.separator) : ", ";
+  return a.map((v) => v != null ? String(v) : "").join(sep);
+};
+_fns.split = (input, _e, opts) => {
+  const sep = opts.separator != null ? String(opts.separator) : ",";
+  return String(input || "").split(sep).map((s) => s.trim());
+};
+_fns.trim = (input) => String(input || "").trim();
+_fns.pluck = (input, _e, opts) => Array.isArray(input) ? input.map((r) => r[opts.field]) : [];
+_fns.filter = (input, _e, opts) => {
+  if (!Array.isArray(input)) return [];
+  if (opts.field) return input.filter((r) => !!r[opts.field]);
+  return input.filter(Boolean);
+};
+_fns.map = (input) => Array.isArray(input) ? input.slice() : [];
+_fns.sort = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input.slice() : [];
+  const f = opts.field;
+  const dir = opts.direction === "desc" ? -1 : 1;
+  if (f) return a.sort((x, y) => x[f] > y[f] ? dir : x[f] < y[f] ? -dir : 0);
+  return a.sort((x, y) => x > y ? dir : x < y ? -dir : 0);
+};
+_fns.slice = (input, _e, opts) => Array.isArray(input) ? input.slice(opts.start || 0, opts.end) : input;
+_fns.flat = (input, _e, opts) => {
+  const depth = opts.depth != null ? opts.depth : 1;
+  return Array.isArray(input) ? input.flat(depth) : [input];
+};
+_fns.unique = (input) => {
+  if (!Array.isArray(input)) return [input];
+  const seen = /* @__PURE__ */ new Set();
+  return input.filter((v) => {
+    const key = typeof v === "object" ? JSON.stringify(v) : v;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+_fns.group = (input, _e, opts) => {
+  const a = Array.isArray(input) ? input : [];
+  const g = {};
+  a.forEach((r) => {
+    const k = String(r[opts.field] || "");
+    if (!g[k]) g[k] = [];
+    g[k].push(r);
+  });
+  return g;
+};
+_fns.flatten_keys = (input) => {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return [];
+  const result = [];
+  for (const k of Object.keys(input)) {
+    const vals = Array.isArray(input[k]) ? input[k] : [input[k]];
+    vals.forEach((v) => result.push({ key: k, value: v }));
+  }
+  return result;
+};
+_fns.entries = (input) => {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return [];
+  return Object.keys(input).map((k) => ({ key: k, value: input[k] }));
+};
+_fns.from_entries = (input) => {
+  if (!Array.isArray(input)) return {};
+  const obj = {};
+  input.forEach((item) => {
+    if (item.key != null) obj[item.key] = item.value;
+  });
+  return obj;
+};
+_fns.length = (input) => {
+  if (Array.isArray(input)) return input.length;
+  if (typeof input === "string") return input.length;
+  if (input && typeof input === "object") return Object.keys(input).length;
+  return 0;
+};
+_fns.get = (input, _e, opts) => deepGet(input, opts.field || opts.path || "");
+_fns.default = (input, _e, opts) => input != null ? input : opts.value;
+_fns.coalesce = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] != null) return a[i];
+  }
+  return null;
+};
+_fns.now = () => (/* @__PURE__ */ new Date()).toISOString();
+_fns.diff_days = (input) => {
+  const a = Array.isArray(input) ? input : [];
+  return a.length >= 2 ? Math.floor((new Date(a[0]).getTime() - new Date(a[1]).getTime()) / 864e5) : 0;
+};
+_fns.format_date = (input, _e, opts) => {
+  try {
+    const d = new Date(input);
+    if (opts.format === "iso") return d.toISOString();
+    if (opts.format === "date") return d.toLocaleDateString();
+    if (opts.format === "time") return d.toLocaleTimeString();
+    return d.toLocaleDateString();
+  } catch {
+    return String(input);
+  }
+};
+_fns.parse_date = (input) => {
+  try {
+    return new Date(input).toISOString();
+  } catch {
+    return null;
+  }
+};
+_fns.to_number = (input) => Number(input) || 0;
+_fns.to_string = (input) => input != null ? String(input) : "";
+_fns.to_bool = (input) => !!input;
+_fns.type_of = (input) => Array.isArray(input) ? "array" : typeof input;
+_fns.is_null = (input) => input == null;
+_fns.is_empty = (input) => {
+  if (input == null) return true;
+  if (Array.isArray(input)) return input.length === 0;
+  if (typeof input === "string") return input.length === 0;
+  if (typeof input === "object") return Object.keys(input).length === 0;
+  return false;
+};
+var _customFns = {};
+function evalExpr(expr, node) {
+  if (expr == null) return expr;
+  if (typeof expr !== "object" || Array.isArray(expr)) return expr;
+  const e = expr;
+  if (!e.fn) return expr;
+  let input = e.input;
+  if (typeof input === "string" && input.startsWith("state.")) {
+    input = deepGet(node, input);
+  } else if (Array.isArray(input)) {
+    input = input.map((v) => {
+      if (typeof v === "string" && v.startsWith("state.")) return deepGet(node, v);
+      if (v && typeof v === "object" && v.fn) return evalExpr(v, node);
+      return v;
+    });
+  } else if (input && typeof input === "object" && input.fn) {
+    input = evalExpr(input, node);
+  }
+  if (e.fn === "if") {
+    const cond = evalExpr(e.cond, node);
+    if (cond) {
+      return e.then && typeof e.then === "object" && e.then.fn ? evalExpr(e.then, node) : e.then;
+    } else {
+      return e.else && typeof e.else === "object" && e.else.fn ? evalExpr(e.else, node) : e.else;
+    }
+  }
+  if (e.fn === "filter" && Array.isArray(input) && e.where) {
+    return input.filter((item) => {
+      const tmp = { state: { ...node.state, $: item } };
+      return evalExpr(e.where, tmp);
+    });
+  }
+  if (e.fn === "map" && Array.isArray(input) && e.apply) {
+    return input.map((item) => {
+      const tmp = { state: { ...node.state, $: item } };
+      return evalExpr(e.apply, tmp);
+    });
+  }
+  const fn = _customFns[e.fn] || _fns[e.fn];
+  if (!fn) {
+    console.warn('CardCompute: unknown function "' + e.fn + '"');
+    return void 0;
+  }
+  return fn(input, evalExpr, e);
+}
+function run(node) {
+  if (!node || !node.compute) return node;
+  if (!node.state) node.state = {};
+  for (const key of Object.keys(node.compute)) {
+    try {
+      const val = evalExpr(node.compute[key], node);
+      deepSet(node.state, key, val);
+    } catch (err) {
+      console.error(`CardCompute.run error on "${node.id || "?"}.${key}":`, err);
+    }
+  }
+  return node;
+}
+function resolve(node, path) {
+  return deepGet(node, path);
+}
+function registerFunction(name, fn) {
+  _customFns[name] = fn;
+}
+var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
+  "metric",
+  "table",
+  "chart",
+  "form",
+  "filter",
+  "list",
+  "notes",
+  "todo",
+  "alert",
+  "narrative",
+  "badge",
+  "text",
+  "markdown",
+  "custom"
+]);
+var VALID_SOURCE_KINDS = /* @__PURE__ */ new Set(["api", "websocket", "static", "llm"]);
+var VALID_STATUSES = /* @__PURE__ */ new Set(["fresh", "stale", "loading", "error"]);
+var CARD_ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "type", "meta", "data", "view", "state", "compute"]);
+var SOURCE_ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "type", "meta", "data", "source", "state", "compute"]);
+function validateNode(node) {
+  const errors = [];
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return { ok: false, errors: ["Node must be a non-null object"] };
+  }
+  const n = node;
+  if (typeof n.id !== "string" || !n.id) {
+    errors.push("id: required, must be a non-empty string");
+  }
+  if (n.type !== "card" && n.type !== "source") {
+    errors.push('type: must be "card" or "source"');
+    return { ok: false, errors };
+  }
+  const allowed = n.type === "card" ? CARD_ALLOWED_KEYS : SOURCE_ALLOWED_KEYS;
+  for (const key of Object.keys(n)) {
+    if (!allowed.has(key)) errors.push(`Unknown top-level key: "${key}"`);
+  }
+  if (n.state == null || typeof n.state !== "object" || Array.isArray(n.state)) {
+    errors.push("state: required, must be an object");
+  } else {
+    const state = n.state;
+    if (state.status != null && !VALID_STATUSES.has(state.status)) {
+      errors.push(`state.status: must be one of: ${[...VALID_STATUSES].join(", ")}`);
+    }
+  }
+  if (n.meta != null) {
+    if (typeof n.meta !== "object" || Array.isArray(n.meta)) {
+      errors.push("meta: must be an object");
+    } else {
+      const meta = n.meta;
+      if (meta.title != null && typeof meta.title !== "string") errors.push("meta.title: must be a string");
+      if (meta.tags != null && !Array.isArray(meta.tags)) errors.push("meta.tags: must be an array");
+    }
+  }
+  if (n.data != null) {
+    if (typeof n.data !== "object" || Array.isArray(n.data)) {
+      errors.push("data: must be an object");
+    } else {
+      const data = n.data;
+      if (data.requires != null && !Array.isArray(data.requires)) errors.push("data.requires: must be an array of strings");
+      if (data.provides != null && (typeof data.provides !== "object" || Array.isArray(data.provides))) errors.push("data.provides: must be an object");
+    }
+  }
+  if (n.compute != null) {
+    if (typeof n.compute !== "object" || Array.isArray(n.compute)) {
+      errors.push("compute: must be an object");
+    } else {
+      for (const [key, expr] of Object.entries(n.compute)) {
+        if (!expr || typeof expr !== "object" || Array.isArray(expr)) {
+          errors.push(`compute.${key}: must be a compute expression object`);
+        } else if (!expr.fn) {
+          errors.push(`compute.${key}: missing required "fn" property`);
+        } else {
+          const fn = expr.fn;
+          if (!_fns[fn] && !_customFns[fn]) {
+            errors.push(`compute.${key}: unknown function "${fn}"`);
+          }
+        }
+      }
+    }
+  }
+  if (n.type === "card") {
+    if (n.source != null) errors.push('Card nodes must not have "source" \u2014 use type "source" instead');
+    if (n.view == null || typeof n.view !== "object" || Array.isArray(n.view)) {
+      errors.push("view: required for card nodes, must be an object");
+    } else {
+      const view = n.view;
+      if (!Array.isArray(view.elements) || view.elements.length === 0) {
+        errors.push("view.elements: required, must be a non-empty array");
+      } else {
+        view.elements.forEach((elem, i) => {
+          if (!elem || typeof elem !== "object") {
+            errors.push(`view.elements[${i}]: must be an object`);
+            return;
+          }
+          if (!elem.kind || typeof elem.kind !== "string") {
+            errors.push(`view.elements[${i}].kind: required, must be a string`);
+          } else if (!VALID_ELEMENT_KINDS.has(elem.kind)) {
+            errors.push(`view.elements[${i}].kind: unknown kind "${elem.kind}". Valid: ${[...VALID_ELEMENT_KINDS].join(", ")}`);
+          }
+          if (elem.data != null && (typeof elem.data !== "object" || Array.isArray(elem.data))) {
+            errors.push(`view.elements[${i}].data: must be an object`);
+          }
+        });
+      }
+      if (view.layout != null && (typeof view.layout !== "object" || Array.isArray(view.layout))) {
+        errors.push("view.layout: must be an object");
+      }
+      if (view.features != null && (typeof view.features !== "object" || Array.isArray(view.features))) {
+        errors.push("view.features: must be an object");
+      }
+    }
+  }
+  if (n.type === "source") {
+    if (n.view != null) errors.push('Source nodes must not have "view" \u2014 use type "card" instead');
+    if (n.source == null || typeof n.source !== "object" || Array.isArray(n.source)) {
+      errors.push("source: required for source nodes, must be an object");
+    } else {
+      const src = n.source;
+      if (!src.kind || !VALID_SOURCE_KINDS.has(src.kind)) {
+        errors.push(`source.kind: required, must be one of: ${[...VALID_SOURCE_KINDS].join(", ")}`);
+      }
+      if (typeof src.bindTo !== "string" || !src.bindTo) {
+        errors.push("source.bindTo: required, must be a state path string");
+      } else if (!src.bindTo.startsWith("state.")) {
+        errors.push('source.bindTo: must start with "state."');
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+var CardCompute = {
+  run,
+  eval: evalExpr,
+  resolve,
+  validate: validateNode,
+  registerFunction,
+  get functions() {
+    const all = {};
+    for (const k of Object.keys(_fns)) all[k] = _fns[k];
+    for (const k of Object.keys(_customFns)) all[k] = _customFns[k];
+    return all;
+  }
+};
+
+// src/continuous-event-graph/live-cards-bridge.ts
+function liveCardsToReactiveGraph(input, options = {}) {
+  let cards;
+  let boardSettings = {};
+  let boardId;
+  if (!Array.isArray(input) && "nodes" in input) {
+    const board = input;
+    cards = board.nodes;
+    boardId = board.id;
+    boardSettings = board.settings ?? {};
+  } else {
+    cards = input;
+  }
+  const {
+    sourceHandlers = {},
+    defaultSourceHandler,
+    cardHandlers = {},
+    reactiveOptions = {},
+    graphSettings = {},
+    executionId
+  } = options;
+  const cardMap = /* @__PURE__ */ new Map();
+  for (const card of cards) {
+    if (cardMap.has(card.id)) {
+      throw new Error(`Duplicate card ID: "${card.id}"`);
+    }
+    cardMap.set(card.id, card);
+  }
+  const sharedState = options.sharedState ?? /* @__PURE__ */ new Map();
+  const tasks = {};
+  for (const card of cards) {
+    const requires = card.data?.requires ?? [];
+    for (const req of requires) {
+      if (!cardMap.has(req)) {
+        throw new Error(`Card "${card.id}" requires "${req}" but no card with that ID exists`);
+      }
+    }
+    tasks[card.id] = {
+      requires: requires.length > 0 ? requires : void 0,
+      provides: [card.id],
+      taskHandlers: [card.id],
+      // each card has a named handler matching its ID
+      description: card.meta?.title ?? `${card.type}: ${card.id}`
+    };
+  }
+  const config = {
+    id: boardId ?? `live-cards-${Date.now()}`,
+    settings: {
+      completion: "manual",
+      execution_mode: "eligibility-mode",
+      ...boardSettings,
+      ...graphSettings
+    },
+    tasks
+  };
+  const handlers = {};
+  let graphRef = null;
+  const getResolve = () => (token, data, errors) => {
+    graphRef.resolveCallback(token, data, errors);
+  };
+  for (const card of cards) {
+    if (card.type === "source") {
+      handlers[card.id] = buildSourceHandler(card, sourceHandlers, defaultSourceHandler, sharedState, getResolve);
+    } else {
+      handlers[card.id] = buildCardHandler(card, cardHandlers, sharedState, cardMap, getResolve);
+    }
+  }
+  const graph = createReactiveGraph(
+    config,
+    {
+      ...reactiveOptions,
+      handlers
+    },
+    executionId
+  );
+  graphRef = graph;
+  return { graph, config, handlers, cards: cardMap, sharedState };
+}
+function buildSourceHandler(card, sourceHandlers, defaultSourceHandler, sharedState, getResolve) {
+  if (sourceHandlers[card.id]) {
+    const userHandler = sourceHandlers[card.id];
+    return async (input) => {
+      return userHandler(input);
+    };
+  }
+  if (defaultSourceHandler) {
+    const factoryHandler = defaultSourceHandler(card);
+    return async (input) => {
+      return factoryHandler(input);
+    };
+  }
+  return async (input) => {
+    const state = { ...card.state };
+    sharedState.set(card.id, state);
+    getResolve()(input.callbackToken, state);
+    return "task-initiated";
+  };
+}
+function buildCardHandler(card, cardHandlers, sharedState, cardMap, getResolve) {
+  if (cardHandlers[card.id]) {
+    const userHandler = cardHandlers[card.id];
+    return async (input) => {
+      return userHandler(input);
+    };
+  }
+  return async (input) => {
+    const computeNode = {
+      id: card.id,
+      state: { ...card.state },
+      compute: card.compute
+    };
+    const requires = card.data?.requires ?? [];
+    for (const upstreamId of requires) {
+      const upstreamState = sharedState.get(upstreamId);
+      if (upstreamState) {
+        computeNode.state[upstreamId] = upstreamState;
+      }
+      const upstreamCard = cardMap.get(upstreamId);
+      if (upstreamCard?.data?.provides && upstreamState) {
+        for (const [key, bindRef] of Object.entries(upstreamCard.data.provides)) {
+          if (typeof bindRef === "string" && bindRef.startsWith("state.")) {
+            const path = bindRef.slice(6);
+            const value = deepGet2(upstreamState, path);
+            if (value !== void 0) {
+              computeNode.state[key] = value;
+            }
+          }
+        }
+      }
+    }
+    CardCompute.run(computeNode);
+    const resultState = { ...computeNode.state };
+    sharedState.set(card.id, resultState);
+    getResolve()(input.callbackToken, resultState);
+    return "task-initiated";
+  };
+}
+function deepGet2(obj, path) {
+  if (!path || !obj) return void 0;
+  const parts = path.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (cur == null) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
 
+exports.FileJournal = FileJournal;
+exports.MemoryJournal = MemoryJournal;
 exports.addNode = addNode;
 exports.addProvides = addProvides;
 exports.addRequires = addRequires;
 exports.applyEvent = applyEvent;
+exports.applyEvents = applyEvents;
+exports.computeDataHash = computeDataHash;
+exports.createCallbackHandler = createCallbackHandler;
+exports.createFireAndForgetHandler = createFireAndForgetHandler;
 exports.createLiveGraph = createLiveGraph;
+exports.createNoopHandler = createNoopHandler;
+exports.createReactiveGraph = createReactiveGraph;
+exports.createScriptHandler = createScriptHandler;
+exports.createShellHandler = createShellHandler;
+exports.createWebhookHandler = createWebhookHandler;
 exports.disableNode = disableNode;
 exports.drainTokens = drainTokens;
 exports.enableNode = enableNode;
@@ -928,6 +2260,8 @@ exports.getUnreachableTokens = getUnreachableTokens;
 exports.getUpstream = getUpstream;
 exports.injectTokens = injectTokens;
 exports.inspect = inspect;
+exports.liveCardsToReactiveGraph = liveCardsToReactiveGraph;
+exports.mutateGraph = mutateGraph;
 exports.removeNode = removeNode;
 exports.removeProvides = removeProvides;
 exports.removeRequires = removeRequires;
@@ -935,5 +2269,7 @@ exports.resetNode = resetNode;
 exports.restore = restore;
 exports.schedule = schedule;
 exports.snapshot = snapshot;
+exports.validateLiveGraph = validateLiveGraph;
+exports.validateReactiveGraph = validateReactiveGraph;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map