@cadenza.io/core 1.0.1

package/dist/index.mjs

@@ -0,0 +1,2648 @@
+// src/engine/SignalBroker.ts
+var SignalBroker = class _SignalBroker {
+  // execId -> emitted signals
+  constructor() {
+    this.signalObservers = /* @__PURE__ */ new Map();
+    // For loop prevention: Per-execId recent emits (cleared post-run or TTL)
+    this.emitStacks = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Singleton instance for signal management.
+   * @returns The broker instance.
+   */
+  static get instance() {
+    if (!this.instance_) {
+      this.instance_ = new _SignalBroker();
+    }
+    return this.instance_;
+  }
+  /**
+   * Initializes with runners.
+   * @param runner Standard runner for user signals.
+   * @param metaRunner Meta runner for 'meta.' signals (suppresses further meta-emits).
+   */
+  init(runner, metaRunner) {
+    this.runner = runner;
+    this.metaRunner = metaRunner;
+  }
+  /**
+   * Observes a signal with a routine/task.
+   * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
+   * @param routineOrTask The observer.
+   * @edge Duplicates ignored; supports wildcards for broad listening.
+   */
+  observe(signal, routineOrTask) {
+    this.addSignal(signal);
+    this.signalObservers.get(signal).tasks.add(routineOrTask);
+  }
+  /**
+   * Unsubscribes a routine/task from a signal.
+   * @param signal The signal.
+   * @param routineOrTask The observer.
+   * @edge Removes all instances if duplicate; deletes if empty.
+   */
+  unsubscribe(signal, routineOrTask) {
+    const obs = this.signalObservers.get(signal);
+    if (obs) {
+      obs.tasks.delete(routineOrTask);
+      if (obs.tasks.size === 0) {
+        this.signalObservers.delete(signal);
+      }
+    }
+  }
+  /**
+   * Emits a signal and bubbles to matching wildcards/parents (e.g., 'a.b.action' triggers 'a.b.action', 'a.b.*', 'a.*').
+   * @param signal The signal name.
+   * @param context The payload.
+   * @edge Fire-and-forget; guards against loops per execId (from context.__graphExecId).
+   * @edge For distribution, SignalTask can prefix and proxy remote.
+   * @throws Error on detected loop.
+   */
+  emit(signal, context = {}) {
+    const execId = context.__graphExecId || "global";
+    if (!this.emitStacks.has(execId)) this.emitStacks.set(execId, /* @__PURE__ */ new Set());
+    const stack = this.emitStacks.get(execId);
+    if (stack.has(signal)) {
+      throw new Error(`Signal loop detected for ${signal} in exec ${execId}`);
+    }
+    stack.add(signal);
+    this.executeListener(signal, context);
+    try {
+      const parts = signal.slice(0, Math.max(signal.lastIndexOf(":"), signal.lastIndexOf("."))).split(".");
+      for (let i = parts.length; i > 0; i--) {
+        const parent = parts.slice(0, i).join(".");
+        this.executeListener(parent, context);
+        this.executeListener(parent + ".*", context);
+      }
+    } finally {
+      stack.delete(signal);
+    }
+  }
+  executeListener(signal, context) {
+    const obs = this.signalObservers.get(signal);
+    const runner = this.getRunner(signal);
+    if (obs && runner) {
+      obs.fn(runner, Array.from(obs.tasks), context);
+    }
+  }
+  addSignal(signal) {
+    if (!this.signalObservers.has(signal)) {
+      this.signalObservers.set(signal, {
+        fn: (runner, tasks, context) => runner.run(tasks, context),
+        tasks: /* @__PURE__ */ new Set()
+      });
+    }
+  }
+  /**
+   * Lists all observed signals.
+   * @returns Array of signals.
+   */
+  listObservedSignals() {
+    return Array.from(this.signalObservers.keys());
+  }
+  getRunner(signal) {
+    return signal.startsWith("meta") ? this.metaRunner : this.runner;
+  }
+  reset() {
+    this.emitStacks.clear();
+    this.signalObservers.clear();
+  }
+};
+
+// src/engine/GraphRunner.ts
+import { v4 as uuid6 } from "uuid";
+
+// src/engine/GraphRun.ts
+import { v4 as uuid } from "uuid";
+
+// src/utils/ColorRandomizer.ts
+var ColorRandomizer = class {
+  constructor(numberOfSteps = 200, spread = 30) {
+    this.stepCounter = 0;
+    this.numberOfSteps = numberOfSteps;
+    this.spread = spread;
+    this.range = Math.floor(numberOfSteps / this.spread);
+  }
+  rainbow(numOfSteps, step) {
+    let r, g, b;
+    const h = step / numOfSteps;
+    const i = ~~(h * 6);
+    const f = h * 6 - i;
+    const q = 1 - f;
+    switch (i % 6) {
+      case 0:
+        r = 1;
+        g = f;
+        b = 0;
+        break;
+      case 1:
+        r = q;
+        g = 1;
+        b = 0;
+        break;
+      case 2:
+        r = 0;
+        g = 1;
+        b = f;
+        break;
+      case 3:
+        r = 0;
+        g = q;
+        b = 1;
+        break;
+      case 4:
+        r = f;
+        g = 0;
+        b = 1;
+        break;
+      case 5:
+        r = 1;
+        g = 0;
+        b = q;
+        break;
+      default:
+        r = 0;
+        g = 0;
+        b = 0;
+        break;
+    }
+    const c = "#" + ("00" + (~~(r * 255)).toString(16)).slice(-2) + ("00" + (~~(g * 255)).toString(16)).slice(-2) + ("00" + (~~(b * 255)).toString(16)).slice(-2);
+    return c;
+  }
+  getRandomColor() {
+    this.stepCounter++;
+    if (this.stepCounter > this.numberOfSteps) {
+      this.stepCounter = 1;
+    }
+    const randomStep = this.stepCounter * this.range % this.numberOfSteps - this.range + Math.floor(this.stepCounter / this.spread);
+    return this.rainbow(this.numberOfSteps, randomStep);
+  }
+};
+
+// src/engine/exporters/vue-flow/VueFlowExportVisitor.ts
+var VueFlowExportVisitor = class {
+  constructor() {
+    this.nodeCount = 0;
+    this.elements = [];
+    this.index = 0;
+    this.numberOfLayerNodes = 0;
+    this.contextToColor = {};
+    this.colorRandomizer = new ColorRandomizer();
+  }
+  visitLayer(layer) {
+    const snapshot = layer.export();
+    this.numberOfLayerNodes = snapshot.__numberOfNodes;
+    this.index = 0;
+  }
+  visitNode(node) {
+    const snapshot = node.export();
+    if (!this.contextToColor[snapshot.__context.__id]) {
+      this.contextToColor[snapshot.__context.__id] = this.colorRandomizer.getRandomColor();
+    }
+    const color = this.contextToColor[snapshot.__context.__id];
+    this.elements.push({
+      id: snapshot.__id.slice(0, 8),
+      label: snapshot.__task.__name,
+      position: {
+        x: snapshot.__task.__layerIndex * 500,
+        y: -50 * this.numberOfLayerNodes * 0.5 + (this.index * 60 + 30)
+      },
+      sourcePosition: "right",
+      targetPosition: "left",
+      style: { backgroundColor: `${color}`, width: "180px" },
+      data: {
+        executionTime: snapshot.__executionTime,
+        executionStart: snapshot.__executionStart,
+        executionEnd: snapshot.__executionEnd,
+        description: snapshot.__task.__description,
+        functionString: snapshot.__task.__functionString,
+        context: snapshot.__context.__context,
+        layerIndex: snapshot.__task.__layerIndex
+      }
+    });
+    for (const [index, nextNodeId] of snapshot.__nextNodes.entries()) {
+      this.elements.push({
+        id: `${snapshot.__id.slice(0, 8)}-${index}`,
+        source: snapshot.__id.slice(0, 8),
+        target: nextNodeId.slice(0, 8)
+      });
+    }
+    this.index++;
+    this.nodeCount++;
+  }
+  visitTask(task) {
+    const snapshot = task.export();
+    this.elements.push({
+      id: snapshot.__id.slice(0, 8),
+      label: snapshot.__name,
+      position: { x: snapshot.__layerIndex * 300, y: this.index * 50 + 30 },
+      sourcePosition: "right",
+      targetPosition: "left",
+      data: {
+        description: snapshot.__description,
+        functionString: snapshot.__functionString,
+        layerIndex: snapshot.__layerIndex
+      }
+    });
+    for (const [index, nextTaskId] of snapshot.__nextTasks.entries()) {
+      this.elements.push({
+        id: `${snapshot.__id.slice(0, 8)}-${index}`,
+        source: snapshot.__id.slice(0, 8),
+        target: nextTaskId.slice(0, 8)
+      });
+    }
+    this.index++;
+    this.nodeCount++;
+  }
+  getElements() {
+    return this.elements;
+  }
+  getNodeCount() {
+    return this.nodeCount;
+  }
+};
+
+// src/engine/exporters/vue-flow/VueFlowExporter.ts
+var VueFlowExporter = class {
+  exportGraph(graph) {
+    const exporterVisitor = new VueFlowExportVisitor();
+    const layers = graph.getIterator();
+    while (layers.hasNext()) {
+      const layer = layers.next();
+      layer.accept(exporterVisitor);
+    }
+    return {
+      elements: exporterVisitor.getElements(),
+      numberOfNodes: exporterVisitor.getNodeCount()
+    };
+  }
+  exportStaticGraph(graph) {
+    const exporterVisitor = new VueFlowExportVisitor();
+    let prevTask = null;
+    for (const task of graph) {
+      if (task === prevTask) {
+        continue;
+      }
+      const tasks = task.getIterator();
+      const exportedTaskIds = [];
+      while (tasks.hasNext()) {
+        const task2 = tasks.next();
+        if (task2 && !exportedTaskIds.includes(task2.id)) {
+          exportedTaskIds.push(task2.id);
+          task2.accept(exporterVisitor);
+        }
+      }
+      prevTask = task;
+    }
+    return {
+      elements: exporterVisitor.getElements(),
+      numberOfNodes: exporterVisitor.getNodeCount()
+    };
+  }
+};
+
+// src/engine/GraphRun.ts
+var GraphRun = class {
+  constructor(strategy) {
+    this.id = uuid();
+    this.strategy = strategy;
+    this.strategy.setRunInstance(this);
+    this.exporter = new VueFlowExporter();
+  }
+  setGraph(graph) {
+    this.graph = graph;
+  }
+  addNode(node) {
+    this.strategy.addNode(node);
+  }
+  // Composite function / Command execution
+  run() {
+    return this.strategy.run();
+  }
+  // Composite function
+  destroy() {
+    var _a;
+    (_a = this.graph) == null ? void 0 : _a.destroy();
+    this.graph = void 0;
+    this.exporter = void 0;
+  }
+  // Composite function
+  log() {
+    var _a;
+    console.log("vvvvvvvvvvvvvvvvv");
+    console.log("GraphRun");
+    console.log("vvvvvvvvvvvvvvvvv");
+    (_a = this.graph) == null ? void 0 : _a.log();
+    console.log("=================");
+  }
+  // Memento
+  export() {
+    var _a, _b;
+    if (this.exporter && this.graph) {
+      const data = this.strategy.export();
+      return {
+        __id: this.id,
+        __label: (_a = data.__startTime) != null ? _a : this.id,
+        __graph: (_b = this.exporter) == null ? void 0 : _b.exportGraph(this.graph),
+        __data: data
+      };
+    }
+    return {
+      __id: this.id,
+      __label: this.id,
+      __graph: void 0,
+      __data: {}
+    };
+  }
+  // Export Strategy
+  setExporter(exporter) {
+    this.exporter = exporter;
+  }
+};
+
+// src/graph/execution/GraphNode.ts
+import { v4 as uuid3 } from "uuid";
+
+// src/graph/context/GraphContext.ts
+import { v4 as uuid2 } from "uuid";
+
+// src/utils/tools.ts
+function deepCloneFilter(input, filterOut = () => false) {
+  if (input === null || typeof input !== "object") {
+    return input;
+  }
+  const visited = /* @__PURE__ */ new WeakMap();
+  const stack = [];
+  const output = Array.isArray(input) ? [] : {};
+  stack.push({ source: input, target: output });
+  visited.set(input, output);
+  while (stack.length) {
+    const { source, target, key } = stack.pop();
+    const currentTarget = key !== void 0 ? target[key] : target;
+    for (const [k, value] of Object.entries(source)) {
+      if (filterOut(k)) continue;
+      if (value && typeof value === "object") {
+        if (visited.has(value)) {
+          currentTarget[k] = visited.get(value);
+          continue;
+        }
+        const clonedValue = Array.isArray(value) ? [] : {};
+        currentTarget[k] = clonedValue;
+        visited.set(value, clonedValue);
+        stack.push({ source: value, target: currentTarget, key: k });
+      } else {
+        currentTarget[k] = value;
+      }
+    }
+  }
+  return output;
+}
+
+// src/graph/context/GraphContext.ts
+var GraphContext = class _GraphContext {
+  // __keys, frozen
+  constructor(context) {
+    if (Array.isArray(context)) {
+      throw new Error("Array contexts not supported");
+    }
+    this.fullContext = context;
+    this.userData = Object.fromEntries(
+      Object.entries(this.fullContext).filter(([key]) => !key.startsWith("__"))
+    );
+    this.metaData = Object.fromEntries(
+      Object.entries(this.fullContext).filter(([key]) => key.startsWith("__"))
+    );
+    this.id = uuid2();
+  }
+  /**
+   * Gets frozen user data (read-only, no clone).
+   * @returns Frozen user context.
+   */
+  getContext() {
+    return this.userData;
+  }
+  getClonedContext() {
+    return deepCloneFilter(this.userData);
+  }
+  /**
+   * Gets full raw context (cloned for safety).
+   * @returns Cloned full context.
+   */
+  getFullContext() {
+    return this.fullContext;
+  }
+  /**
+   * Gets frozen metadata (read-only).
+   * @returns Frozen metadata object.
+   */
+  getMetaData() {
+    return this.metaData;
+  }
+  /**
+   * Clones this context (new instance).
+   * @returns New GraphContext.
+   */
+  clone() {
+    return this.mutate(this.fullContext);
+  }
+  /**
+   * Creates new context from data (via registry).
+   * @param context New data.
+   * @returns New GraphContext.
+   */
+  mutate(context) {
+    return new _GraphContext(context);
+  }
+  /**
+   * Combines with another for uniques (joins userData).
+   * @param otherContext The other.
+   * @returns New combined GraphContext.
+   * @edge Appends other.userData to joinedContexts in userData.
+   */
+  combine(otherContext) {
+    const newUser = { ...this.userData };
+    newUser.joinedContexts = this.userData.joinedContexts ? [...this.userData.joinedContexts] : [this.userData];
+    const otherUser = otherContext.userData;
+    if (Array.isArray(otherUser.joinedContexts)) {
+      newUser.joinedContexts.push(...otherUser.joinedContexts);
+    } else {
+      newUser.joinedContexts.push(otherUser);
+    }
+    const newFull = {
+      ...this.fullContext,
+      ...otherContext.fullContext,
+      ...newUser
+    };
+    return new _GraphContext(newFull);
+  }
+  /**
+   * Exports the context.
+   * @returns Exported object.
+   */
+  export() {
+    return {
+      __id: this.id,
+      __context: this.getFullContext()
+    };
+  }
+};
+
+// src/graph/iterators/GraphNodeIterator.ts
+var GraphNodeIterator = class {
+  constructor(node) {
+    this.currentLayer = [];
+    this.nextLayer = [];
+    this.index = 0;
+    this.currentNode = node;
+    this.currentLayer = [node];
+  }
+  hasNext() {
+    return !!this.currentNode;
+  }
+  next() {
+    const nextNode = this.currentNode;
+    if (!nextNode) {
+      return void 0;
+    }
+    this.nextLayer.push(...nextNode.mapNext((n) => n));
+    this.index++;
+    if (this.index === this.currentLayer.length) {
+      this.currentLayer = this.nextLayer;
+      this.nextLayer = [];
+      this.index = 0;
+    }
+    this.currentNode = this.currentLayer.length ? this.currentLayer[this.index] : void 0;
+    return nextNode;
+  }
+};
+
+// src/interfaces/SignalEmitter.ts
+var SignalEmitter = class {
+  /**
+   * Constructor for signal emitters.
+   * @param silent If true, suppresses all emissions (e.g., for meta-runners to avoid loops; affects all emits).
+   */
+  constructor(silent = false) {
+    this.silent = silent;
+  }
+  /**
+   * Emits a signal via the broker if not silent.
+   * @param signal The signal name.
+   * @param data Optional payload (defaults to empty object).
+   * @edge No emission if silent; for metrics in silent mode, consider override or separate method.
+   */
+  emit(signal, data = {}) {
+    if (this.silent) {
+      return;
+    }
+    Cadenza.broker.emit(signal, data);
+  }
+  /**
+   * Emits a signal via the broker even if silent.
+   * @param signal The signal name.
+   * @param data Optional payload (defaults to empty object).
+   */
+  emitMetric(signal, data = {}) {
+    Cadenza.broker.emit(signal, data);
+  }
+};
+
+// src/graph/execution/GraphNode.ts
+var GraphNode = class _GraphNode extends SignalEmitter {
+  constructor(task, context, routineExecId, prevNodes = []) {
+    super(task.isMeta);
+    this.divided = false;
+    this.splitGroupId = "";
+    this.processing = false;
+    this.subgraphComplete = false;
+    this.graphComplete = false;
+    this.previousNodes = [];
+    this.nextNodes = [];
+    this.executionTime = 0;
+    this.executionStart = 0;
+    this.failed = false;
+    this.errored = false;
+    this.destroyed = false;
+    this.task = task;
+    this.context = context;
+    this.previousNodes = prevNodes;
+    this.id = uuid3();
+    this.routineExecId = routineExecId;
+    this.splitGroupId = routineExecId;
+  }
+  isUnique() {
+    return this.task.isUnique;
+  }
+  isMeta() {
+    return this.task.isMeta;
+  }
+  isProcessed() {
+    return this.divided;
+  }
+  isProcessing() {
+    return this.processing;
+  }
+  subgraphDone() {
+    return this.subgraphComplete;
+  }
+  graphDone() {
+    return this.graphComplete;
+  }
+  isEqualTo(node) {
+    return this.sharesTaskWith(node) && this.sharesContextWith(node) && this.isPartOfSameGraph(node);
+  }
+  isPartOfSameGraph(node) {
+    return this.routineExecId === node.routineExecId;
+  }
+  sharesTaskWith(node) {
+    return this.task.id === node.task.id;
+  }
+  sharesContextWith(node) {
+    return this.context.id === node.context.id;
+  }
+  getLayerIndex() {
+    return this.task.layerIndex;
+  }
+  getConcurrency() {
+    return this.task.concurrency;
+  }
+  getTag() {
+    return this.task.getTag(this.context);
+  }
+  scheduleOn(layer) {
+    let shouldSchedule = true;
+    const nodes = layer.getNodesByRoutineExecId(this.routineExecId);
+    for (const node of nodes) {
+      if (node.isEqualTo(this)) {
+        shouldSchedule = false;
+        break;
+      }
+      if (node.sharesTaskWith(this) && node.isUnique()) {
+        node.consume(this);
+        shouldSchedule = false;
+        break;
+      }
+    }
+    if (shouldSchedule) {
+      this.layer = layer;
+      layer.add(this);
+      this.emit("meta.node.scheduled", {
+        ...this.lightExport(),
+        __scheduled: Date.now()
+      });
+    }
+  }
+  start() {
+    if (this.executionStart === 0) {
+      this.executionStart = Date.now();
+    }
+    const memento = this.lightExport();
+    if (this.previousNodes.length === 0) {
+      this.emit("meta.node.started_routine_execution", memento);
+    }
+    this.emit("meta.node.started", memento);
+    return this.executionStart;
+  }
+  end() {
+    if (this.executionStart === 0) {
+      return 0;
+    }
+    this.processing = false;
+    const end = Date.now();
+    this.executionTime = end - this.executionStart;
+    const memento = this.lightExport();
+    if (this.errored || this.failed) {
+      this.emit("meta.node.errored", memento);
+    }
+    this.emit("meta.node.ended", memento);
+    if (this.graphDone()) {
+      this.emit(
+        `meta.node.ended_routine_execution:${this.routineExecId}`,
+        memento
+      );
+    }
+    return end;
+  }
+  execute() {
+    if (!this.divided && !this.processing) {
+      this.start();
+      this.processing = true;
+      try {
+        this.result = this.work();
+      } catch (e) {
+        this.onError(e);
+      }
+      if (this.result instanceof Promise) {
+        return this.processAsync();
+      }
+      this.postProcess();
+    }
+    return this.nextNodes;
+  }
+  async processAsync() {
+    try {
+      this.result = await this.result;
+    } catch (e) {
+      this.onError(e);
+    }
+    this.postProcess();
+    return this.nextNodes;
+  }
+  work() {
+    return this.task.execute(this.context, this.onProgress.bind(this));
+  }
+  onProgress(progress) {
+    var _a, _b, _c;
+    progress = Math.min(Math.max(0, progress), 1);
+    this.emit(`meta.node.progress:${this.routineExecId}`, {
+      __nodeId: this.id,
+      __routineExecId: this.routineExecId,
+      __progress: progress,
+      __weight: this.task.progressWeight / ((_c = (_b = (_a = this.layer) == null ? void 0 : _a.getNodesByRoutineExecId(this.routineExecId)) == null ? void 0 : _b.length) != null ? _c : 1)
+    });
+  }
+  postProcess() {
+    if (typeof this.result === "string") {
+      this.onError(
+        `Returning strings is not allowed. Returned: ${this.result}`
+      );
+    }
+    if (Array.isArray(this.result)) {
+      this.onError(`Returning arrays is not allowed. Returned: ${this.result}`);
+    }
+    this.nextNodes = this.divide();
+    if (this.nextNodes.length === 0) {
+      this.completeSubgraph();
+    }
+    if (this.errored || this.failed) {
+      this.task.emitOnFailSignals(this.context);
+    } else {
+      this.task.emitSignals(this.context);
+    }
+    this.end();
+  }
+  onError(error) {
+    this.result = {
+      ...this.context.getFullContext(),
+      __error: `Node error: ${error}`,
+      error: `Node error: ${error}`,
+      returnedValue: this.result
+    };
+    this.migrate(this.result);
+    this.errored = true;
+  }
+  divide() {
+    var _a;
+    const newNodes = [];
+    if (((_a = this.result) == null ? void 0 : _a.next) && typeof this.result.next === "function") {
+      const generator = this.result;
+      let current = generator.next();
+      while (!current.done && current.value !== void 0) {
+        newNodes.push(...this.generateNewNodes(current.value));
+        current = generator.next();
+      }
+    } else if (this.result !== void 0 && !this.errored) {
+      newNodes.push(...this.generateNewNodes(this.result));
+      if (typeof this.result !== "boolean") {
+        this.migrate({ ...this.result, ...this.context.getMetaData() });
+      }
+    } else if (this.errored) {
+      newNodes.push(
+        ...this.task.mapNext(
+          (t) => this.clone().split(uuid3()).differentiate(t).migrate({ ...this.result }),
+          true
+        )
+      );
+    }
+    this.divided = true;
+    this.migrate({
+      ...this.context.getFullContext(),
+      __nextNodes: newNodes.map((n) => n.id)
+    });
+    return newNodes;
+  }
+  generateNewNodes(result) {
+    const groupId = uuid3();
+    const newNodes = [];
+    if (typeof result !== "boolean") {
+      const failed = result.failed !== void 0 && result.failed || result.error !== void 0;
+      newNodes.push(
+        ...this.task.mapNext((t) => {
+          const context = t.isUnique ? {
+            joinedContexts: [
+              { ...result, taskName: this.task.name, __nodeId: this.id }
+            ],
+            ...this.context.getMetaData()
+          } : { ...result, ...this.context.getMetaData() };
+          return this.clone().split(groupId).differentiate(t).migrate(context);
+        }, failed)
+      );
+      this.failed = failed;
+    } else {
+      const shouldContinue = result;
+      if (shouldContinue) {
+        newNodes.push(
+          ...this.task.mapNext((t) => {
+            const newNode = this.clone().split(groupId).differentiate(t);
+            if (t.isUnique) {
+              newNode.migrate({
+                joinedContexts: [
+                  {
+                    ...this.context.getContext(),
+                    taskName: this.task.name,
+                    __nodeId: this.id
+                  }
+                ],
+                ...this.context.getMetaData()
+              });
+            }
+            return newNode;
+          })
+        );
+      }
+    }
+    return newNodes;
+  }
+  differentiate(task) {
+    this.task = task;
+    return this;
+  }
+  migrate(ctx) {
+    this.context = new GraphContext(ctx);
+    return this;
+  }
+  split(id) {
+    this.splitGroupId = id;
+    return this;
+  }
+  clone() {
+    return new _GraphNode(this.task, this.context, this.routineExecId, [this]);
+  }
+  consume(node) {
+    this.context = this.context.combine(node.context);
+    this.previousNodes = this.previousNodes.concat(node.previousNodes);
+    node.completeSubgraph();
+    node.changeIdentity(this.id);
+    node.destroy();
+  }
+  changeIdentity(id) {
+    this.id = id;
+  }
+  completeSubgraph() {
+    for (const node of this.nextNodes) {
+      if (!node.subgraphDone()) {
+        return;
+      }
+    }
+    this.subgraphComplete = true;
+    if (this.previousNodes.length === 0) {
+      this.completeGraph();
+      return;
+    }
+    this.previousNodes.forEach((n) => n.completeSubgraph());
+  }
+  completeGraph() {
+    this.graphComplete = true;
+    this.nextNodes.forEach((n) => n.completeGraph());
+  }
+  destroy() {
+    this.context = null;
+    this.task = null;
+    this.nextNodes = [];
+    this.previousNodes.forEach(
+      (n) => n.nextNodes.splice(n.nextNodes.indexOf(this), 1)
+    );
+    this.previousNodes = [];
+    this.result = void 0;
+    this.layer = void 0;
+    this.destroyed = true;
+  }
+  getIterator() {
+    return new GraphNodeIterator(this);
+  }
+  mapNext(callback) {
+    return this.nextNodes.map(callback);
+  }
+  accept(visitor) {
+    visitor.visitNode(this);
+  }
+  export() {
+    return {
+      __id: this.id,
+      __task: this.task.export(),
+      __context: this.context.export(),
+      __result: this.result,
+      __executionTime: this.executionTime,
+      __executionStart: this.executionStart,
+      __executionEnd: this.executionStart + this.executionTime,
+      __nextNodes: this.nextNodes.map((node) => node.id),
+      __previousNodes: this.previousNodes.map((node) => node.id),
+      __routineExecId: this.routineExecId,
+      __isProcessing: this.processing,
+      __isMeta: this.isMeta(),
+      __graphComplete: this.graphComplete,
+      __failed: this.failed,
+      __errored: this.errored,
+      __isUnique: this.isUnique(),
+      __splitGroupId: this.splitGroupId,
+      __tag: this.getTag()
+    };
+  }
+  lightExport() {
+    return {
+      __id: this.id,
+      __task: {
+        __id: this.task.id,
+        __name: this.task.name
+      },
+      __context: this.context.export(),
+      __executionTime: this.executionTime,
+      __executionStart: this.executionStart,
+      __nextNodes: this.nextNodes.map((node) => node.id),
+      __previousNodes: this.previousNodes.map((node) => node.id),
+      __routineExecId: this.routineExecId,
+      __isProcessing: this.processing,
+      __graphComplete: this.graphComplete,
+      __isMeta: this.isMeta(),
+      __failed: this.failed,
+      __errored: this.errored,
+      __isUnique: this.isUnique(),
+      __splitGroupId: this.splitGroupId,
+      __tag: this.getTag()
+    };
+  }
+  log() {
+    console.log(this.task.name, this.context.getContext(), this.executionTime);
+  }
+};
+
+// src/graph/definition/GraphRoutine.ts
+import { v4 as uuid4 } from "uuid";
+
+// src/interfaces/SignalParticipant.ts
+var SignalParticipant = class extends SignalEmitter {
+  constructor() {
+    super(...arguments);
+    this.signalsToEmit = /* @__PURE__ */ new Set();
+    // Use Set to prevent duplicates
+    this.signalsToEmitOnFail = /* @__PURE__ */ new Set();
+    this.observedSignals = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Subscribes to signals (chainable).
+   * @param signals The signal names.
+   * @returns This for chaining.
+   * @edge Duplicates ignored; assumes broker.observe binds this as handler.
+   */
+  doOn(...signals) {
+    signals.forEach((signal) => {
+      if (this.observedSignals.has(signal)) return;
+      Cadenza.broker.observe(signal, this);
+      this.observedSignals.add(signal);
+    });
+    return this;
+  }
+  /**
+   * Sets signals to emit post-execution (chainable).
+   * @param signals The signal names.
+   * @returns This for chaining.
+   */
+  emits(...signals) {
+    signals.forEach((signal) => this.signalsToEmit.add(signal));
+    return this;
+  }
+  emitsOnFail(...signals) {
+    signals.forEach((signal) => this.signalsToEmitOnFail.add(signal));
+    return this;
+  }
+  /**
+   * Unsubscribes from all observed signals.
+   * @returns This for chaining.
+   */
+  unsubscribeAll() {
+    this.observedSignals.forEach(
+      (signal) => Cadenza.broker.unsubscribe(signal, this)
+    );
+    this.observedSignals.clear();
+    return this;
+  }
+  /**
+   * Unsubscribes from specific signals.
+   * @param signals The signals.
+   * @returns This for chaining.
+   * @edge No-op if not subscribed.
+   */
+  unsubscribe(...signals) {
+    signals.forEach((signal) => {
+      if (this.observedSignals.has(signal)) {
+        Cadenza.broker.unsubscribe(signal, this);
+        this.observedSignals.delete(signal);
+      }
+    });
+    return this;
+  }
+  /**
+   * Detaches specific emitted signals.
+   * @param signals The signals.
+   * @returns This for chaining.
+   */
+  detachSignals(...signals) {
+    signals.forEach((signal) => this.signalsToEmit.delete(signal));
+    return this;
+  }
+  /**
+   * Detaches all emitted signals.
+   * @returns This for chaining.
+   */
+  detachAllSignals() {
+    this.signalsToEmit.clear();
+    return this;
+  }
+  /**
+   * Emits attached signals.
+   * @param context The context for emission.
+   * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
+   */
+  emitSignals(context) {
+    this.signalsToEmit.forEach((signal) => {
+      this.emit(signal, context);
+    });
+  }
+  /**
+   * Emits attached fail signals.
+   * @param context The context for emission.
+   * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
+   */
+  emitOnFailSignals(context) {
+    this.signalsToEmitOnFail.forEach((signal) => {
+      this.emit(signal, context);
+    });
+  }
+  /**
+   * Destroys the participant (unsub/detach).
+   */
+  destroy() {
+    this.unsubscribeAll();
+    this.detachAllSignals();
+  }
+};
+
+// src/graph/definition/GraphRoutine.ts
+var GraphRoutine = class extends SignalParticipant {
+  constructor(name, tasks, description) {
+    super();
+    this.isMeta = false;
+    this.tasks = /* @__PURE__ */ new Set();
+    this.id = uuid4();
+    this.name = name;
+    this.description = description;
+    tasks.forEach((t) => this.tasks.add(t));
+    this.emit("meta.routine.created", { __routine: this });
+  }
+  /**
+   * Applies callback to starting tasks.
+   * @param callBack The callback.
+   * @returns Promise if async.
+   */
+  async forEachTask(callBack) {
+    const promises = [];
+    for (const task of this.tasks) {
+      const res = callBack(task);
+      if (res instanceof Promise) promises.push(res);
+    }
+    await Promise.all(promises);
+  }
+  /**
+   * Sets global ID.
+   * @param id The ID.
+   */
+  setGlobalId(id) {
+    const oldId = this.id;
+    this.id = id;
+    this.emit("meta.routine.global_id_set", { __id: this.id, __oldId: oldId });
+  }
+  // Removed emitsSignals per clarification (routines as listeners only)
+  /**
+   * Destroys the routine.
+   */
+  destroy() {
+    this.tasks.clear();
+    this.emit("meta.routine.destroyed", { __id: this.id });
+  }
+};
+
+// src/graph/definition/Task.ts
+import { v4 as uuid5 } from "uuid";
+
+// src/graph/iterators/TaskIterator.ts
+var TaskIterator = class {
+  constructor(task) {
+    this.currentLayer = /* @__PURE__ */ new Set();
+    this.nextLayer = /* @__PURE__ */ new Set();
+    this.iterator = this.currentLayer[Symbol.iterator]();
+    this.currentTask = task;
+    this.currentLayer.add(task);
+  }
+  hasNext() {
+    return !!this.currentTask;
+  }
+  next() {
+    const nextTask = this.currentTask;
+    if (!nextTask) {
+      return void 0;
+    }
+    nextTask.mapNext((t) => this.nextLayer.add(t));
+    let next = this.iterator.next();
+    if (next.value === void 0) {
+      this.currentLayer.clear();
+      this.currentLayer = this.nextLayer;
+      this.nextLayer = /* @__PURE__ */ new Set();
+      this.iterator = this.currentLayer[Symbol.iterator]();
+      next = this.iterator.next();
+    }
+    this.currentTask = next.value;
+    return nextTask;
+  }
+};
+
+// src/graph/definition/Task.ts
+var Task = class extends SignalParticipant {
+  /**
+   * Constructs a Task (static definition).
+   * @param name Name.
+   * @param task Function.
+   * @param description Description.
+   * @param concurrency Limit.
+   * @param timeout ms.
+   * @param register Register via signal (default true).
+   * @edge Emits 'meta.task.created' with { __task: this } for seed.
+   */
+  constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true) {
+    super();
+    this.isUnique = false;
+    this.throttled = false;
+    this.isSignal = false;
+    this.isMeta = false;
+    this.isDeputy = false;
+    this.isEphemeral = false;
+    this.layerIndex = 0;
+    this.progressWeight = 0;
+    this.nextTasks = /* @__PURE__ */ new Set();
+    this.onFailTasks = /* @__PURE__ */ new Set();
+    this.predecessorTasks = /* @__PURE__ */ new Set();
+    this.destroyed = false;
+    this.id = uuid5();
+    this.name = name;
+    this.taskFunction = task.bind(this);
+    this.description = description;
+    this.concurrency = concurrency;
+    this.timeout = timeout;
+    if (register) {
+      this.emit("meta.task.created", { __task: this });
+    }
+  }
+  getTag(context) {
+    return this.id;
+  }
+  setGlobalId(id) {
+    const oldId = this.id;
+    this.id = id;
+    this.emit("meta.task.global_id_set", { __id: this.id, __oldId: oldId });
+  }
+  setTimeout(timeout) {
+    this.timeout = timeout;
+  }
+  setConcurrency(concurrency) {
+    this.concurrency = concurrency;
+  }
+  setProgressWeight(weight) {
+    this.progressWeight = weight;
+  }
+  execute(context, progressCallback) {
+    return this.taskFunction(context.getClonedContext(), progressCallback);
+  }
+  doAfter(...tasks) {
+    for (const pred of tasks) {
+      if (this.predecessorTasks.has(pred)) continue;
+      pred.nextTasks.add(this);
+      this.predecessorTasks.add(pred);
+      this.updateLayerFromPredecessors();
+      if (this.hasCycle()) {
+        this.decouple(pred);
+        throw new Error(`Cycle adding pred ${pred.name} to ${this.name}`);
+      }
+    }
+    this.updateProgressWeights();
+    return this;
+  }
+  then(...tasks) {
+    for (const next of tasks) {
+      if (this.nextTasks.has(next)) continue;
+      this.nextTasks.add(next);
+      next.predecessorTasks.add(this);
+      next.updateLayerFromPredecessors();
+      if (next.hasCycle()) {
+        this.decouple(next);
+        throw new Error(`Cycle adding next ${next.name} to ${this.name}`);
+      }
+    }
+    this.updateProgressWeights();
+    return this;
+  }
+  decouple(task) {
+    if (task.nextTasks.has(this)) {
+      task.nextTasks.delete(this);
+      this.predecessorTasks.delete(task);
+    }
+    if (task.onFailTasks.has(this)) {
+      task.onFailTasks.delete(this);
+      this.predecessorTasks.delete(task);
+    }
+    this.updateLayerFromPredecessors();
+  }
+  doOnFail(...tasks) {
+    for (const task of tasks) {
+      if (this.onFailTasks.has(task)) continue;
+      this.onFailTasks.add(task);
+      task.predecessorTasks.add(this);
+      task.updateLayerFromPredecessors();
+      if (task.hasCycle()) {
+        this.decouple(task);
+        throw new Error(`Cycle adding onFail ${task.name} to ${this.name}`);
+      }
+    }
+    return this;
+  }
+  updateProgressWeights() {
+    const layers = this.getSubgraphLayers();
+    const numLayers = layers.size;
+    if (numLayers === 0) return;
+    const weightPerLayer = 1 / numLayers;
+    layers.forEach((tasksInLayer) => {
+      const numTasks = tasksInLayer.size;
+      if (numTasks === 0) return;
+      tasksInLayer.forEach(
+        (task) => task.progressWeight = weightPerLayer / numTasks
+      );
+    });
+  }
+  getSubgraphLayers() {
+    const layers = /* @__PURE__ */ new Map();
+    const queue = [this];
+    const visited = /* @__PURE__ */ new Set();
+    while (queue.length) {
+      const task = queue.shift();
+      if (visited.has(task)) continue;
+      visited.add(task);
+      if (!layers.has(task.layerIndex)) layers.set(task.layerIndex, /* @__PURE__ */ new Set());
+      layers.get(task.layerIndex).add(task);
+      task.nextTasks.forEach((next) => queue.push(next));
+    }
+    return layers;
+  }
+  updateLayerFromPredecessors() {
+    let maxPred = 0;
+    this.predecessorTasks.forEach(
+      (pred) => maxPred = Math.max(maxPred, pred.layerIndex)
+    );
+    this.layerIndex = maxPred + 1;
+    const queue = Array.from(this.nextTasks);
+    while (queue.length) {
+      const next = queue.shift();
+      next.updateLayerFromPredecessors();
+      next.nextTasks.forEach((n) => queue.push(n));
+    }
+  }
+  hasCycle() {
+    const visited = /* @__PURE__ */ new Set();
+    const recStack = /* @__PURE__ */ new Set();
+    const dfs = (task) => {
+      if (recStack.has(task)) return true;
+      if (visited.has(task)) return false;
+      visited.add(task);
+      recStack.add(task);
+      for (const next of task.nextTasks) {
+        if (dfs(next)) return true;
+      }
+      recStack.delete(task);
+      return false;
+    };
+    return dfs(this);
+  }
+  mapNext(callback, failed = false) {
+    const tasks = failed ? Array.from(this.onFailTasks) : Array.from(this.nextTasks);
+    return tasks.map(callback);
+  }
+  mapPrevious(callback) {
+    return Array.from(this.predecessorTasks).map(callback);
+  }
+  destroy() {
+    super.destroy();
+    this.predecessorTasks.forEach((pred) => pred.nextTasks.delete(this));
+    this.nextTasks.forEach((next) => next.predecessorTasks.delete(this));
+    this.onFailTasks.forEach((fail) => fail.predecessorTasks.delete(this));
+    this.nextTasks.clear();
+    this.predecessorTasks.clear();
+    this.onFailTasks.clear();
+    this.destroyed = true;
+    this.emit("meta.task.destroyed", { __id: this.id });
+  }
+  export() {
+    return {
+      __id: this.id,
+      __name: this.name,
+      __description: this.description,
+      __layerIndex: this.layerIndex,
+      __isUnique: this.isUnique,
+      __isMeta: this.isMeta,
+      __isSignal: this.isSignal,
+      __eventTriggers: this.observedSignals,
+      __attachedEvents: this.signalsToEmit,
+      __isDeputy: this.isDeputy,
+      __throttled: this.throttled,
+      __isEphemeral: this.isEphemeral,
+      __concurrency: this.concurrency,
+      __timeout: this.timeout,
+      __functionString: this.taskFunction.toString(),
+      __nextTasks: Array.from(this.nextTasks).map((t) => t.id),
+      __onFailTasks: Array.from(this.onFailTasks).map((t) => t.id),
+      __previousTasks: Array.from(this.predecessorTasks).map((t) => t.id)
+    };
+  }
+  getIterator() {
+    return new TaskIterator(this);
+  }
+  accept(visitor) {
+    visitor.visitTask(this);
+  }
+  log() {
+    console.log(this.name);
+  }
+};
+
+// src/graph/definition/meta/MetaTask.ts
+var MetaTask = class extends Task {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/controllers/GraphRegistry.ts
+var GraphRegistry = class _GraphRegistry {
+  constructor() {
+    this.tasks = /* @__PURE__ */ new Map();
+    this.routines = /* @__PURE__ */ new Map();
+    this.registerTask = new MetaTask(
+      "Registry Seed",
+      (context) => {
+        const { __task } = context;
+        if (__task && !this.tasks.has(__task.id)) {
+          console.log("Registering task:", __task.name);
+          this.tasks.set(__task.id, __task);
+        }
+        return true;
+      },
+      "Registers tasks. Seed for meta.taskCreated"
+    ).doOn("meta.task.created");
+    this.tasks.set(this.registerTask.id, this.registerTask);
+    this.updateTaskId = Cadenza.createMetaTask(
+      "Update task id",
+      (context) => {
+        const { __id, __oldId } = context;
+        const task = this.tasks.get(__oldId);
+        if (!task) return context;
+        this.tasks.set(__id, task);
+        this.tasks.delete(__oldId);
+        return context;
+      },
+      "Updates task id."
+    ).doOn("meta.task.global_id_set");
+    this.getTaskById = Cadenza.createMetaTask(
+      "Get task by id",
+      (context) => {
+        const { __id } = context;
+        return { ...context, __task: this.tasks.get(__id) };
+      },
+      "Gets task by id."
+    );
+    this.getTaskByName = Cadenza.createMetaTask(
+      "Get task by name",
+      (context) => {
+        const { __name } = context;
+        for (const task of this.tasks.values()) {
+          if (task.name === __name) {
+            return { ...context, __task: task };
+          }
+        }
+        return context;
+      },
+      "Gets task by name (first match)."
+    );
+    this.getTasksByLayer = Cadenza.createMetaTask(
+      "Get tasks by layer",
+      (context) => {
+        const { __layerIndex } = context;
+        const layerTasks = Array.from(this.tasks.values()).filter(
+          (task) => task.layerIndex === __layerIndex
+        );
+        return { ...context, __tasks: layerTasks };
+      },
+      "Gets tasks by layer index."
+    );
+    this.getAllTasks = Cadenza.createMetaTask(
+      "Get all tasks",
+      (context) => ({ ...context, __tasks: Array.from(this.tasks.values()) }),
+      // Use arrow to capture this
+      "Gets all tasks."
+    );
+    this.doForEachTask = Cadenza.createMetaTask(
+      "Do for each task",
+      function* (context) {
+        for (const task of this.tasks.values()) {
+          yield { ...context, __task: task };
+        }
+      }.bind(this),
+      // Bind to capture this in generator
+      "Yields each task for branching."
+    );
+    this.deleteTask = Cadenza.createMetaTask(
+      "Delete task",
+      (context) => {
+        const { __id } = context;
+        this.tasks.delete(__id);
+        return context;
+      },
+      "Deletes task."
+    ).doOn("meta.task.destroyed");
+    this.registerRoutine = Cadenza.createMetaTask(
+      "Register routine",
+      (context) => {
+        const { __routine } = context;
+        if (__routine && !this.routines.has(__routine.id)) {
+          this.routines.set(__routine.id, __routine);
+        }
+        return true;
+      },
+      "Registers routine."
+    ).doOn("meta.routine.created");
+    this.updateRoutineId = Cadenza.createMetaTask(
+      "Update routine id",
+      (context) => {
+        const { __id, __oldId } = context;
+        const routine = this.routines.get(__oldId);
+        if (!routine) return context;
+        this.routines.set(__id, routine);
+        this.routines.delete(__oldId);
+        return context;
+      },
+      "Updates routine id."
+    ).doOn("meta.routine.global_id_set");
+    this.getRoutineById = Cadenza.createMetaTask(
+      "Get routine by id",
+      (context) => {
+        const { __id } = context;
+        return { ...context, routine: this.routines.get(__id) };
+      },
+      "Gets routine by id."
+    );
+    this.getRoutineByName = Cadenza.createMetaTask(
+      "Get routine by name",
+      (context) => {
+        const { __name } = context;
+        for (const routine of this.routines.values()) {
+          if (routine.name === __name) {
+            return { ...context, __routine: routine };
+          }
+        }
+        return context;
+      },
+      "Gets routine by name."
+    );
+    this.getAllRoutines = Cadenza.createMetaTask(
+      "Get all routines",
+      (context) => ({
+        ...context,
+        __routines: Array.from(this.routines.values())
+      }),
+      // Use arrow to capture this
+      "Gets all routines."
+    );
+    this.doForEachRoutine = Cadenza.createMetaTask(
+      "Do for each routine",
+      function* (context) {
+        for (const routine of this.routines.values()) {
+          yield { ...context, __routine: routine };
+        }
+      }.bind(this),
+      "Yields each routine."
+    );
+    this.deleteRoutine = Cadenza.createMetaTask(
+      "Delete routine",
+      (context) => {
+        const { __id } = context;
+        this.routines.delete(__id);
+        return context;
+      },
+      "Deletes routine."
+    );
+  }
+  static get instance() {
+    if (!this._instance) this._instance = new _GraphRegistry();
+    return this._instance;
+  }
+  reset() {
+    this.tasks.clear();
+    this.routines.clear();
+    this.tasks.set(this.registerTask.id, this.registerTask);
+  }
+};
+
+// src/engine/GraphRunner.ts
+var GraphRunner = class extends SignalEmitter {
+  /**
+   * Constructs a runner.
+   * @param isMeta Meta flag (default false).
+   * @edge Creates 'Start run' meta-task chained to registry gets.
+   */
+  constructor(isMeta = false) {
+    super(isMeta);
+    this.debug = false;
+    this.isRunning = false;
+    this.isMeta = false;
+    this.id = uuid6();
+    this.isMeta = isMeta;
+    this.strategy = Cadenza.runStrategy.PARALLEL;
+    this.currentRun = new GraphRun(this.strategy);
+  }
+  init() {
+    if (this.isMeta) return;
+    Cadenza.createMetaTask(
+      "Start run",
+      this.startRun.bind(this),
+      "Starts a run"
+    ).doAfter(
+      GraphRegistry.instance.getTaskByName,
+      GraphRegistry.instance.getRoutineByName
+    );
+  }
+  /**
+   * Adds tasks/routines to current run.
+   * @param tasks Tasks/routines.
+   * @param context Context (defaults {}).
+   * @edge Flattens routines to tasks; generates routineExecId if not in context.
+   * @edge Emits 'meta.runner.added_tasks' with metadata.
+   * @edge Empty tasks warns no-op.
+   */
+  addTasks(tasks, context) {
+    var _a, _b, _c, _d, _e, _f;
+    let _tasks = Array.isArray(tasks) ? tasks : [tasks];
+    if (_tasks.length === 0) {
+      console.warn("No tasks/routines to add.");
+      return;
+    }
+    let routineName = _tasks.map((t) => t.name).join(" | ");
+    let isMeta = _tasks.every((t) => t.isMeta);
+    let routineId = null;
+    const allTasks = _tasks.flatMap((t) => {
+      if (t instanceof GraphRoutine) {
+        routineName = t.name;
+        isMeta = t.isMeta;
+        routineId = t.id;
+        const routineTasks = [];
+        t.forEachTask((task) => routineTasks.push(task));
+        return routineTasks;
+      }
+      return t;
+    });
+    const ctx = new GraphContext(context || {});
+    const routineExecId = (_a = context.__routineExecId) != null ? _a : uuid6();
+    const data = {
+      __routineExecId: routineExecId,
+      __routineName: routineName,
+      __isMeta: isMeta,
+      __routineId: routineId,
+      __context: ctx.export(),
+      __previousRoutineExecution: (_c = (_b = context.__metaData) == null ? void 0 : _b.__routineExecId) != null ? _c : null,
+      __contractId: (_f = (_e = (_d = context.__metaData) == null ? void 0 : _d.__contractId) != null ? _e : context.__contractId) != null ? _f : null,
+      __task: {
+        __name: routineName
+      },
+      __scheduled: Date.now()
+    };
+    this.emit("meta.runner.added_tasks", data);
+    allTasks.forEach(
+      (task) => this.currentRun.addNode(new GraphNode(task, ctx, routineExecId))
+    );
+  }
+  /**
+   * Runs tasks/routines.
+   * @param tasks Optional tasks/routines.
+   * @param context Optional context.
+   * @returns Current/last run (Promise if async).
+   * @edge If running, returns current; else runs and resets.
+   */
+  run(tasks, context) {
+    if (tasks) {
+      this.addTasks(tasks, context != null ? context : {});
+    }
+    if (this.isRunning) {
+      return this.currentRun;
+    }
+    if (this.currentRun) {
+      this.isRunning = true;
+      const runResult = this.currentRun.run();
+      if (runResult instanceof Promise) {
+        return this.runAsync(runResult);
+      }
+    }
+    return this.reset();
+  }
+  async runAsync(run) {
+    await run;
+    return this.reset();
+  }
+  reset() {
+    if (this.debug) {
+      this.currentRun.log();
+    }
+    this.isRunning = false;
+    const lastRun = this.currentRun;
+    if (!this.debug) {
+      this.destroy();
+    }
+    this.currentRun = new GraphRun(this.strategy);
+    return lastRun;
+  }
+  setDebug(value) {
+    this.debug = value;
+  }
+  destroy() {
+    this.currentRun.destroy();
+  }
+  setStrategy(strategy) {
+    this.strategy = strategy;
+    if (!this.isRunning) {
+      this.currentRun = new GraphRun(this.strategy);
+    }
+  }
+  startRun(context) {
+    var _a;
+    if (context.__task || context.__routine) {
+      const routine = (_a = context.__task) != null ? _a : context.__routine;
+      this.run(routine, context);
+      return true;
+    } else {
+      context.errored = true;
+      context.__error = "No routine or task defined.";
+      return false;
+    }
+  }
+};
+
+// src/graph/definition/UniqueTask.ts
+var UniqueTask = class extends Task {
+  constructor() {
+    super(...arguments);
+    this.isUnique = true;
+  }
+};
+
+// src/graph/definition/meta/UniqueMetaTask.ts
+var UniqueMetaTask = class extends UniqueTask {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/graph/definition/ThrottledTask.ts
+var ThrottledTask = class extends Task {
+  constructor(name, task, description = "", getTagCallback = (context, task2) => "default", concurrency = 1, timeout = 0, register = true) {
+    super(name, task, description, concurrency, timeout, register);
+    this.throttled = true;
+    this.getTag = (context) => getTagCallback(context, this);
+  }
+  export() {
+    return {
+      ...super.export(),
+      __getTagCallback: this.getTag.toString()
+    };
+  }
+};
+
+// src/graph/definition/meta/ThrottledMetaTask.ts
+var ThrottledMetaTask = class extends ThrottledTask {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/graph/definition/DebounceTask.ts
+var DebounceTask = class extends Task {
+  constructor(name, task, description = "", debounceTime = 1e3, leading = false, trailing = true, concurrency = 0, timeout = 0, register = true) {
+    super(name, task, description, concurrency, timeout, register);
+    this.timer = null;
+    this.lastResolve = null;
+    this.lastReject = null;
+    this.lastContext = null;
+    this.lastTimeout = null;
+    this.debounceTime = debounceTime;
+    this.leading = leading;
+    this.trailing = trailing;
+  }
+  executeFunction(progressCallback) {
+    if (this.lastTimeout) {
+      clearTimeout(this.lastTimeout);
+    }
+    let result;
+    try {
+      result = this.taskFunction(
+        this.lastContext.getClonedContext(),
+        progressCallback
+      );
+    } catch (error) {
+      if (this.lastResolve) {
+        this.lastResolve(error);
+      }
+      return;
+    }
+    if (result instanceof Promise) {
+      result.then(this.lastResolve).catch(this.lastReject);
+    } else {
+      if (this.lastResolve) {
+        this.lastResolve(result);
+      }
+    }
+  }
+  debouncedTrigger(resolve, reject, context, timeout, progressCallback) {
+    const callNow = this.leading && this.timer === null;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.lastResolve = resolve;
+    this.lastReject = reject;
+    this.lastContext = context;
+    this.lastTimeout = timeout;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      if (this.trailing) {
+        this.executeFunction(progressCallback);
+      }
+    }, this.debounceTime);
+    if (callNow) {
+      this.executeFunction(progressCallback);
+    }
+  }
+  execute(context, progressCallback) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        resolve(false);
+      }, this.debounceTime + 1);
+      this.debouncedTrigger(
+        resolve,
+        reject,
+        context,
+        timeout,
+        progressCallback
+      );
+    });
+  }
+};
+
+// src/graph/definition/meta/DebouncedMetaTask.ts
+var DebouncedMetaTask = class extends DebounceTask {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/graph/definition/EphemeralTask.ts
+var EphemeralTask = class extends Task {
+  constructor(name, task, description = "", once = true, condition = () => true, concurrency = 0, timeout = 0, register = false) {
+    super(name, task, description, concurrency, timeout, register);
+    this.isEphemeral = true;
+    this.once = once;
+    this.condition = condition;
+  }
+  execute(context, progressCallback) {
+    const result = super.execute(context, progressCallback);
+    this.emit("meta.ephemeral.executed", result);
+    if (this.once || !this.condition(result)) {
+      this.destroy();
+      return result;
+    }
+  }
+};
+
+// src/graph/definition/meta/EphemeralMetaTask.ts
+var EphemeralMetaTask = class extends EphemeralTask {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/graph/definition/meta/MetaRoutine.ts
+var MetaRoutine = class extends GraphRoutine {
+  constructor() {
+    super(...arguments);
+    this.isMeta = true;
+  }
+};
+
+// src/interfaces/ExecutionChain.ts
+var ExecutionChain = class {
+  setNext(next) {
+    if (this.hasNext) {
+      return;
+    }
+    next.previous = this;
+    this.next = next;
+  }
+  get hasNext() {
+    return !!this.next;
+  }
+  get hasPreceding() {
+    return !!this.previous;
+  }
+  getNext() {
+    return this.next;
+  }
+  getPreceding() {
+    return this.previous;
+  }
+  decouple() {
+    this.next = void 0;
+    this.previous = void 0;
+  }
+};
+
+// src/graph/iterators/GraphLayerIterator.ts
+var GraphLayerIterator = class {
+  constructor(graph) {
+    this.graph = graph;
+  }
+  hasNext() {
+    return !this.currentLayer || this.currentLayer.hasNext;
+  }
+  hasPrevious() {
+    return !this.currentLayer || this.currentLayer.hasPreceding;
+  }
+  next() {
+    if (!this.currentLayer) {
+      return this.getFirst();
+    } else if (this.hasNext()) {
+      this.currentLayer = this.currentLayer.getNext();
+    }
+    return this.currentLayer;
+  }
+  previous() {
+    if (!this.currentLayer) {
+      this.currentLayer = this.graph;
+    } else if (this.hasPrevious()) {
+      this.currentLayer = this.currentLayer.getPreceding();
+    }
+    return this.currentLayer;
+  }
+  getFirst() {
+    var _a;
+    if (!this.currentLayer) {
+      this.currentLayer = this.graph;
+    }
+    while (this.hasPrevious()) {
+      this.currentLayer = (_a = this.currentLayer) == null ? void 0 : _a.getPreceding();
+    }
+    return this.currentLayer;
+  }
+  getLast() {
+    var _a;
+    if (!this.currentLayer) {
+      this.currentLayer = this.graph;
+    }
+    while (this.hasNext()) {
+      this.currentLayer = (_a = this.currentLayer) == null ? void 0 : _a.getNext();
+    }
+    return this.currentLayer;
+  }
+};
+
+// src/interfaces/GraphLayer.ts
+var GraphLayer = class _GraphLayer extends ExecutionChain {
+  constructor(index) {
+    super();
+    this.nodes = [];
+    this.executionTime = 0;
+    this.executionStart = 0;
+    this.index = index;
+  }
+  get hasPreceding() {
+    return !!this.previous && this.previous instanceof _GraphLayer;
+  }
+  getNumberOfNodes() {
+    return this.nodes.length;
+  }
+  getNodesByRoutineExecId(routineExecId) {
+    return this.nodes.filter((node) => node.routineExecId === routineExecId);
+  }
+  isProcessed() {
+    for (const node of this.nodes) {
+      if (!node.isProcessed()) {
+        return false;
+      }
+    }
+    return true;
+  }
+  graphDone() {
+    let done = true;
+    let layer = this;
+    while (layer) {
+      if (!layer.isProcessed()) {
+        done = false;
+        break;
+      }
+      layer = layer.getNext();
+    }
+    return done;
+  }
+  setNext(next) {
+    if (next.index <= this.index) {
+      return;
+    }
+    if (next.previous !== void 0) {
+      this.previous = next.previous;
+    }
+    super.setNext(next);
+  }
+  add(node) {
+    this.nodes.push(node);
+  }
+  start() {
+    if (!this.executionStart) {
+      this.executionStart = Date.now();
+    }
+    return this.executionStart;
+  }
+  end() {
+    if (!this.executionStart) {
+      return 0;
+    }
+    const end = Date.now();
+    this.executionTime = end - this.executionStart;
+    return end;
+  }
+  destroy() {
+    for (const node of this.nodes) {
+      node.destroy();
+    }
+    this.nodes = [];
+    if (this.hasNext) {
+      const layer = this.getNext();
+      layer == null ? void 0 : layer.destroy();
+    }
+    this.decouple();
+  }
+  getIterator() {
+    return new GraphLayerIterator(this);
+  }
+  accept(visitor) {
+    visitor.visitLayer(this);
+    for (const node of this.nodes) {
+      node.accept(visitor);
+    }
+  }
+  export() {
+    return {
+      __index: this.index,
+      __executionTime: this.executionTime,
+      __numberOfNodes: this.getNumberOfNodes(),
+      __hasNextLayer: this.hasNext,
+      __hasPrecedingLayer: this.hasPreceding,
+      __nodes: this.nodes.map((node) => node.id)
+    };
+  }
+  log() {
+    console.log(`---Layer ${this.index}---`);
+    console.log("Execution time:", this.executionTime);
+    let prevNode;
+    for (const node of this.nodes) {
+      if (!prevNode || !prevNode.sharesContextWith(node)) {
+        console.log("**********");
+      }
+      node.log();
+      prevNode = node;
+    }
+    console.log("***********");
+    if (this.hasNext) {
+      this.getNext().log();
+    }
+  }
+};
+
+// src/graph/execution/SyncGraphLayer.ts
+var SyncGraphLayer = class extends GraphLayer {
+  execute() {
+    this.start();
+    const result = [];
+    for (const node of this.nodes) {
+      if (node.isProcessed()) {
+        continue;
+      }
+      const newNodes = node.execute();
+      if (newNodes instanceof Promise) {
+        console.error("Asynchronous functions are not allowed in sync mode!");
+        continue;
+      }
+      result.push(...newNodes);
+    }
+    this.end();
+    return result;
+  }
+};
+
+// src/interfaces/GraphBuilder.ts
+var GraphBuilder = class {
+  constructor() {
+    this.topLayerIndex = 0;
+    this.layers = [];
+  }
+  getResult() {
+    return this.graph;
+  }
+  compose() {
+    throw "Implement this in child class...";
+  }
+  addNode(node) {
+    const index = node.getLayerIndex();
+    this.addLayer(index);
+    const layer = this.getLayer(index);
+    node.scheduleOn(layer);
+  }
+  addNodes(nodes) {
+    for (const node of nodes) {
+      this.addNode(node);
+    }
+  }
+  addLayer(index) {
+    if (!this.graph) {
+      const layer = this.createLayer(index);
+      this.graph = layer;
+      this.layers.push(layer);
+      this.topLayerIndex = index;
+      return;
+    }
+    const lastLayerIndex = this.topLayerIndex + this.layers.length - 1;
+    if (index >= this.topLayerIndex && index <= lastLayerIndex) {
+      return;
+    }
+    if (this.topLayerIndex > index) {
+      const layer = this.createLayer(this.topLayerIndex - 1);
+      layer.setNext(this.layers[0]);
+      this.graph = layer;
+      this.layers.unshift(layer);
+      this.topLayerIndex = this.topLayerIndex - 1;
+      this.addLayer(index);
+    } else {
+      const layer = this.createLayer(lastLayerIndex + 1);
+      this.layers[this.layers.length - 1].setNext(layer);
+      this.layers.push(layer);
+      this.addLayer(index);
+    }
+  }
+  createLayer(index) {
+    return new SyncGraphLayer(index);
+  }
+  getLayer(layerIndex) {
+    return this.layers[layerIndex - this.topLayerIndex];
+  }
+  reset() {
+    this.graph = void 0;
+    this.topLayerIndex = 0;
+    this.layers = [];
+  }
+};
+
+// src/engine/builders/GraphBreadthFirstBuilder.ts
+var GraphBreadthFirstBuilder = class extends GraphBuilder {
+  compose() {
+    if (!this.graph) {
+      return;
+    }
+    const layers = this.graph.getIterator();
+    while (layers.hasNext()) {
+      const layer = layers.next();
+      const newNodes = layer.execute();
+      this.addNodes(newNodes);
+    }
+  }
+};
+
+// src/interfaces/GraphRunStrategy.ts
+var GraphRunStrategy = class {
+  constructor() {
+    this.graphBuilder = new GraphBreadthFirstBuilder();
+  }
+  setRunInstance(runInstance) {
+    this.runInstance = runInstance;
+  }
+  changeStrategy(builder) {
+    this.graphBuilder = builder;
+  }
+  reset() {
+    this.graphBuilder.reset();
+  }
+  addNode(node) {
+    this.graphBuilder.addNode(node);
+  }
+  updateRunInstance() {
+    var _a;
+    (_a = this.runInstance) == null ? void 0 : _a.setGraph(this.graphBuilder.getResult());
+  }
+};
+
+// src/utils/promise.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/engine/ThrottleEngine.ts
+var ThrottleEngine = class _ThrottleEngine {
+  constructor() {
+    this.queues = {};
+    this.runningCounts = {};
+    this.maxConcurrencyPerTag = {};
+    this.functionIdToPromiseResolve = {};
+  }
+  static get instance() {
+    if (!this.instance_) {
+      this.instance_ = new _ThrottleEngine();
+    }
+    return this.instance_;
+  }
+  /**
+   * Set a custom concurrency limit for a specific tag
+   */
+  setConcurrencyLimit(tag, limit) {
+    console.log("setConcurrency", tag, limit);
+    this.maxConcurrencyPerTag[tag] = limit;
+  }
+  throttle(fn, node, tag = "default") {
+    var _a, _b, _c, _d;
+    const functionPromise = new Promise((resolve) => {
+      this.functionIdToPromiseResolve[node.id] = resolve;
+    });
+    (_b = (_a = this.queues)[tag]) != null ? _b : _a[tag] = [];
+    this.queues[tag].push([fn, node]);
+    console.log(node.lightExport().__task.__name, tag, this.queues[tag]);
+    (_d = (_c = this.maxConcurrencyPerTag)[tag]) != null ? _d : _c[tag] = 1;
+    this.processQueue(tag);
+    return functionPromise;
+  }
+  processQueue(tag) {
+    var _a, _b, _c, _d, _e;
+    const maxAllowed = this.maxConcurrencyPerTag[tag];
+    while (((_b = (_a = this.queues[tag]) == null ? void 0 : _a.length) != null ? _b : 0) > 0 && ((_c = this.runningCounts[tag]) != null ? _c : 0) < maxAllowed) {
+      this.runningCounts[tag] = (this.runningCounts[tag] || 0) + 1;
+      const item = this.queues[tag].shift();
+      this.process(item).then(() => {
+        this.runningCounts[tag]--;
+        this.processQueue(tag);
+      });
+    }
+    if (((_e = (_d = this.queues[tag]) == null ? void 0 : _d.length) != null ? _e : 0) === 0 && this.runningCounts[tag] === 0) {
+      delete this.queues[tag];
+      delete this.runningCounts[tag];
+    }
+  }
+  async process(item) {
+    const fn = item[0];
+    const node = item[1];
+    const context = await fn(node);
+    this.functionIdToPromiseResolve[node.id](context);
+    delete this.functionIdToPromiseResolve[node.id];
+  }
+};
+
+// src/graph/execution/AsyncGraphLayer.ts
+var AsyncGraphLayer = class extends GraphLayer {
+  constructor(index) {
+    super(index);
+    this.waitingNodes = [];
+    this.processingNodes = /* @__PURE__ */ new Set();
+  }
+  add(node) {
+    this.nodes.push(node);
+    this.waitingNodes.push(node);
+  }
+  execute() {
+    var _a, _b;
+    if (this.waitingNodes.length === 0) {
+      return {};
+    }
+    this.start();
+    const result = {};
+    while (this.waitingNodes.length > 0) {
+      const node = this.waitingNodes.pop();
+      if (!node) {
+        break;
+      }
+      this.processingNodes.add(node);
+      (_b = result[_a = node.routineExecId]) != null ? _b : result[_a] = [];
+      let nextNodes;
+      if (node == null ? void 0 : node.getConcurrency()) {
+        const tag = node.getTag();
+        ThrottleEngine.instance.setConcurrencyLimit(tag, node.getConcurrency());
+        nextNodes = ThrottleEngine.instance.throttle(
+          this.processNode.bind(this),
+          node,
+          tag
+        );
+      } else {
+        nextNodes = this.processNode(node);
+      }
+      result[node.routineExecId].push(nextNodes);
+    }
+    if (this.processingNodes.size === 0) {
+      this.end();
+    }
+    return result;
+  }
+  processNode(node) {
+    node.start();
+    const nextNodes = node.execute();
+    if (nextNodes instanceof Promise) {
+      return this.processAsync(node, nextNodes);
+    }
+    this.processingNodes.delete(node);
+    return nextNodes;
+  }
+  async processAsync(node, nextNodes) {
+    const result = await nextNodes;
+    this.processingNodes.delete(node);
+    return result;
+  }
+  destroy() {
+    super.destroy();
+    this.waitingNodes = [];
+    this.processingNodes = /* @__PURE__ */ new Set();
+  }
+};
+
+// src/engine/builders/GraphAsyncQueueBuilder.ts
+var GraphAsyncQueueBuilder = class extends GraphBuilder {
+  async compose() {
+    if (!this.graph) {
+      return;
+    }
+    const layers = this.graph.getIterator();
+    while (true) {
+      let layer = layers.getFirst();
+      if (layer.graphDone()) {
+        return;
+      }
+      this.processLayer(layer);
+      while (layers.hasNext()) {
+        layer = layers.next();
+        this.processLayer(layer);
+      }
+      await sleep(0);
+    }
+  }
+  processLayer(layer) {
+    const nextNodes = layer.execute();
+    for (const routineExecId of Object.keys(nextNodes)) {
+      const group = nextNodes[routineExecId];
+      if (group.some((nodes) => nodes instanceof Promise)) {
+        Promise.all(group).then(
+          (result) => this.addNodes(result.flat())
+        );
+      } else {
+        this.addNodes(group.flat());
+      }
+    }
+  }
+  createLayer(index) {
+    return new AsyncGraphLayer(index);
+  }
+};
+
+// src/engine/strategy/GraphAsyncRun.ts
+var GraphAsyncRun = class extends GraphRunStrategy {
+  constructor() {
+    super();
+    this.graphBuilder = new GraphAsyncQueueBuilder();
+  }
+  async run() {
+    await this.graphBuilder.compose();
+    this.updateRunInstance();
+    this.reset();
+  }
+  reset() {
+    super.reset();
+  }
+  export() {
+    return {};
+  }
+};
+
+// src/engine/strategy/GraphStandardRun.ts
+var GraphStandardRun = class extends GraphRunStrategy {
+  run() {
+    this.graphBuilder.compose();
+    this.updateRunInstance();
+    this.reset();
+  }
+  export() {
+    return {};
+  }
+};
+
+// src/Cadenza.ts
+var Cadenza = class {
+  static bootstrap() {
+    if (this.isBootstrapped) return;
+    this.isBootstrapped = true;
+    this.broker = SignalBroker.instance;
+    this.runner = new GraphRunner();
+    this.metaRunner = new GraphRunner(true);
+    this.broker.init(this.runner, this.metaRunner);
+    this.registry = GraphRegistry.instance;
+    this.runner.init();
+    this.metaRunner.init();
+  }
+  static get runStrategy() {
+    return {
+      PARALLEL: new GraphAsyncRun(),
+      SEQUENTIAL: new GraphStandardRun()
+    };
+  }
+  /**
+   * Validates a name for uniqueness and non-emptiness.
+   * @param name The name to validate.
+   * @throws Error if invalid.
+   */
+  static validateName(name) {
+    if (!name || typeof name !== "string") {
+      throw new Error("Task or Routine name must be a non-empty string.");
+    }
+  }
+  /**
+   * Creates a standard Task and registers it in the GraphRegistry.
+   * @param name Unique identifier for the task.
+   * @param func The function or async generator to execute.
+   * @param description Optional human-readable description for introspection.
+   * @param options Optional task options.
+   * @returns The created Task instance.
+   * @throws Error if name is invalid or duplicate in registry.
+   */
+  static createTask(name, func, description, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new Task(
+      name,
+      func,
+      description,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a MetaTask (for meta-layer graphs) and registers it.
+   * MetaTasks suppress further meta-signal emissions to prevent loops.
+   * @param name Unique identifier for the meta-task.
+   * @param func The function or async generator to execute.
+   * @param description Optional description.
+   * @param options Optional task options.
+   * @returns The created MetaTask instance.
+   * @throws Error if name invalid or duplicate.
+   */
+  static createMetaTask(name, func, description, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new MetaTask(
+      name,
+      func,
+      description,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a UniqueTask (executes once per execution ID, merging parents) and registers it.
+   * Use for fan-in/joins after parallel branches.
+   * @param name Unique identifier.
+   * @param func Function receiving joinedContexts.
+   * @param description Optional description.
+   * @param options Optional task options.
+   * @returns The created UniqueTask.
+   * @throws Error if invalid.
+   */
+  static createUniqueTask(name, func, description, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new UniqueTask(
+      name,
+      func,
+      description,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a UniqueMetaTask for meta-layer joins.
+   * @param name Unique identifier.
+   * @param func Function.
+   * @param description Optional.
+   * @param options Optional task options.
+   * @returns The created UniqueMetaTask.
+   */
+  static createUniqueMetaTask(name, func, description, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new UniqueMetaTask(
+      name,
+      func,
+      description,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a ThrottledTask (rate-limited by concurrency or custom groups) and registers it.
+   * @param name Unique identifier.
+   * @param func Function.
+   * @param throttledIdGetter Optional getter for dynamic grouping (e.g., per-user).
+   * @param description Optional.
+   * @param options Optional task options.
+   * @returns The created ThrottledTask.
+   * @edge If no getter, throttles per task ID; use for resource protection.
+   */
+  static createThrottledTask(name, func, throttledIdGetter, description, options = {
+    concurrency: 1,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new ThrottledTask(
+      name,
+      func,
+      description,
+      throttledIdGetter,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a ThrottledMetaTask for meta-layer throttling.
+   * @param name Identifier.
+   * @param func Function.
+   * @param throttledIdGetter Optional getter.
+   * @param description Optional.
+   * @param options Optional task options.
+   * @returns The created ThrottledMetaTask.
+   */
+  static createThrottledMetaTask(name, func, throttledIdGetter, description, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new ThrottledMetaTask(
+      name,
+      func,
+      description,
+      throttledIdGetter,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a DebounceTask (delays exec until quiet period) and registers it.
+   * @param name Identifier.
+   * @param func Function.
+   * @param description Optional.
+   * @param debounceTime Delay in ms (default 1000).
+   * @param options Optional task options plus optional debounce config (e.g., leading/trailing).
+   * @returns The created DebounceTask.
+   * @edge Multiple triggers within time collapse to one exec.
+   */
+  static createDebounceTask(name, func, description, debounceTime = 1e3, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true,
+    leading: false,
+    trailing: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new DebounceTask(
+      name,
+      func,
+      description,
+      debounceTime,
+      options.leading,
+      options.trailing,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a DebouncedMetaTask for meta-layer debouncing.
+   * @param name Identifier.
+   * @param func Function.
+   * @param description Optional.
+   * @param debounceTime Delay in ms.
+   * @param options Optional task options plus optional debounce config (e.g., leading/trailing).
+   * @returns The created DebouncedMetaTask.
+   */
+  static createDebounceMetaTask(name, func, description, debounceTime = 1e3, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true,
+    leading: false,
+    trailing: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new DebouncedMetaTask(
+      name,
+      func,
+      description,
+      debounceTime,
+      options.leading,
+      options.trailing,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates an EphemeralTask (self-destructs after exec or condition) without default registration.
+   * Useful for transients; optionally register if needed.
+   * @param name Identifier (may not be unique if not registered).
+   * @param func Function.
+   * @param description Optional.
+   * @param once Destroy after first exec (default true).
+   * @param destroyCondition Predicate for destruction (default always true).
+   * @param options Optional task options.
+   * @returns The created EphemeralTask.
+   * @edge Destruction triggered post-exec via Node/Builder; emits meta-signal for cleanup.
+   */
+  static createEphemeralTask(name, func, description, once = true, destroyCondition = () => true, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new EphemeralTask(
+      name,
+      func,
+      description,
+      once,
+      destroyCondition,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates an EphemeralMetaTask for meta-layer transients.
+   * @param name Identifier.
+   * @param func Function.
+   * @param description Optional.
+   * @param once Destroy after first (default true).
+   * @param destroyCondition Destruction predicate.
+   * @param options Optional task options.
+   * @returns The created EphemeralMetaTask.
+   */
+  static createEphemeralMetaTask(name, func, description, once = true, destroyCondition = () => true, options = {
+    concurrency: 0,
+    timeout: 0,
+    register: true
+  }) {
+    this.bootstrap();
+    this.validateName(name);
+    return new EphemeralMetaTask(
+      name,
+      func,
+      description,
+      once,
+      destroyCondition,
+      options.concurrency,
+      options.timeout,
+      options.register
+    );
+  }
+  /**
+   * Creates a GraphRoutine (named entry to starting tasks) and registers it.
+   * @param name Unique identifier.
+   * @param tasks Starting tasks (can be empty, but warns as no-op).
+   * @param description Optional.
+   * @returns The created GraphRoutine.
+   * @edge If tasks empty, routine is valid but inert.
+   */
+  static createRoutine(name, tasks, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    if (tasks.length === 0) {
+      console.warn(`Routine '${name}' created with no starting tasks (no-op).`);
+    }
+    return new GraphRoutine(name, tasks, description);
+  }
+  /**
+   * Creates a MetaRoutine for meta-layer entry points.
+   * @param name Identifier.
+   * @param tasks Starting tasks.
+   * @param description Optional.
+   * @returns The created MetaRoutine.
+   */
+  static createMetaRoutine(name, tasks, description = "") {
+    this.bootstrap();
+    this.validateName(name);
+    if (tasks.length === 0) {
+      console.warn(`MetaRoutine '${name}' created with no starting tasks.`);
+    }
+    return new MetaRoutine(name, tasks, description);
+  }
+  static reset() {
+    var _a, _b;
+    (_a = this.broker) == null ? void 0 : _a.reset();
+    (_b = this.registry) == null ? void 0 : _b.reset();
+  }
+};
+Cadenza.isBootstrapped = false;
+
+// src/index.ts
+var index_default = Cadenza;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.mjs.map