@cadenza.io/core 3.10.0 → 3.12.0

package/dist/index.js

@@ -78,6 +78,7 @@ function formatTimestamp(timestamp) {
 }
 
 // src/engine/SignalBroker.ts
+var import_uuid = require("uuid");
 var SignalBroker = class _SignalBroker {
   // execId -> emitted signals
   constructor() {
@@ -88,10 +89,6 @@ var SignalBroker = class _SignalBroker {
     this.emitStacks = /* @__PURE__ */ new Map();
     this.addSignal("meta.signal_broker.added");
   }
-  /**
-   * Singleton instance for signal management.
-   * @returns The broker instance.
-   */
   static get instance() {
     if (!this.instance_) {
       this.instance_ = new _SignalBroker();
@@ -104,6 +101,15 @@ var SignalBroker = class _SignalBroker {
   setVerbose(value) {
     this.verbose = value;
   }
+  /**
+   * Validates the provided signal name string to ensure it adheres to specific formatting rules.
+   * Throws an error if any of the validation checks fail.
+   *
+   * @param {string} signalName - The signal name to be validated.
+   * @return {void} - Returns nothing if the signal name is valid.
+   * @throws {Error} - Throws an error if the signal name is longer than 100 characters, contains spaces,
+   *                   contains backslashes, or contains uppercase letters in restricted parts of the name.
+   */
   validateSignalName(signalName) {
     if (signalName.length > 100) {
       throw new Error(
@@ -133,6 +139,11 @@ var SignalBroker = class _SignalBroker {
     this.runner = runner;
     this.metaRunner = metaRunner;
   }
+  /**
+   * Initializes and sets up the various tasks for managing and processing signals.
+   *
+   * @return {void} This method does not return a value.
+   */
   init() {
     this.clearSignalsTask = Cadenza.createDebounceMetaTask(
       "Execute and clear queued signals",
@@ -196,6 +207,15 @@ var SignalBroker = class _SignalBroker {
       }
     }
   }
+  /**
+   * Schedules a signal to be emitted after a specified delay or at an exact date and time.
+   *
+   * @param {string} signal - The name of the signal to be emitted.
+   * @param {AnyObject} context - The context to be passed along with the signal.
+   * @param {number} [timeoutMs=60000] - The delay in milliseconds before the signal is emitted. Defaults to 60,000 ms.
+   * @param {Date} [exactDateTime] - An exact date and time at which to emit the signal. If provided, this overrides the `timeoutMs`.
+   * @return {AbortController} An AbortController instance that can be used to cancel the scheduled signal emission.
+   */
   schedule(signal, context, timeoutMs = 6e4, exactDateTime) {
     let delay = timeoutMs;
     if (exactDateTime != null) {
@@ -258,11 +278,12 @@ var SignalBroker = class _SignalBroker {
     };
   }
   /**
-   * 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.
+   * Emits a signal with the specified context, triggering any associated handlers for that signal.
+   *
+   * @param {string} signal - The name of the signal to emit.
+   * @param {AnyObject} [context={}] - An optional context object containing additional information or metadata
+   * associated with the signal. If the context includes a `__routineExecId`, it will be handled accordingly.
+   * @return {void} This method does not return a value.
    */
   emit(signal, context = {}) {
     const execId = context.__routineExecId || "global";
@@ -279,20 +300,62 @@ var SignalBroker = class _SignalBroker {
       if (stack.size === 0) this.emitStacks.delete(execId);
     }
   }
+  /**
+   * Executes a signal by emitting events, updating context, and invoking listeners.
+   * Creates a new execution trace if necessary and updates the context with relevant metadata.
+   * Handles specific, hierarchy-based, and wildcard signals.
+   *
+   * @param {string} signal - The signal name to be executed, potentially including namespaces or tags (e.g., "meta.*" or "signal:type").
+   * @param {AnyObject} context - An object containing relevant metadata and execution details used for handling the signal.
+   * @return {boolean} Returns true if any listeners were successfully executed, otherwise false.
+   */
   execute(signal, context) {
     const isMeta = signal.includes("meta.");
     const isSubMeta = signal.includes("sub_meta.") || context.__isSubMeta;
     const isMetric = context.__signalEmission?.isMetric;
     if (!isSubMeta && (!isMeta || this.debug)) {
+      const isNewTrace = !context.__signalEmission?.executionTraceId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
+      const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? (0, import_uuid.v4)();
+      if (isNewTrace) {
+        this.emit("sub_meta.signal_broker.new_trace", {
+          data: {
+            uuid: executionTraceId,
+            issuer_type: "service",
+            // TODO: Add issuer type
+            issuer_id: context.__metadata?.__issuerId ?? context.__issuerId ?? null,
+            issued_at: formatTimestamp(Date.now()),
+            intent: context.__metadata?.__intent ?? context.__intent ?? null,
+            context: {
+              id: (0, import_uuid.v4)(),
+              context
+            },
+            is_meta: isMeta
+          },
+          metadata: {
+            __executionTraceId: executionTraceId
+          }
+        });
+        context.__metadata = {
+          ...context.__metadata,
+          __executionTraceId: executionTraceId
+        };
+      }
       const emittedAt = Date.now();
+      const signalParts = signal.split(":");
+      const signalName = signalParts[0];
+      const signalTag = signalParts.length > 1 ? signalParts[1] : null;
       context.__signalEmission = {
         ...context.__signalEmission ?? {},
-        signalName: signal,
+        uuid: (0, import_uuid.v4)(),
+        executionTraceId,
+        signalName,
+        signalTag,
         emittedAt: formatTimestamp(emittedAt),
         consumed: false,
         consumedBy: null,
         isMeta
       };
+      this.emit("sub_meta.signal_broker.emitting_signal", context);
     } else if (isSubMeta) {
       context.__isSubMeta = true;
       delete context.__signalEmission;
@@ -315,6 +378,15 @@ var SignalBroker = class _SignalBroker {
     }
     return executed;
   }
+  /**
+   * Executes the tasks associated with a given signal and context.
+   * It processes both normal and meta tasks depending on the signal type
+   * and the availability of the appropriate runner.
+   *
+   * @param {string} signal - The signal identifier that determines which tasks to execute.
+   * @param {AnyObject} context - The context object passed to the task execution function.
+   * @return {boolean} - Returns true if tasks were executed; otherwise, false.
+   */
   executeListener(signal, context) {
     const obs = this.signalObservers.get(signal);
     if (!obs || obs.tasks.size === 0) {
@@ -340,6 +412,15 @@ var SignalBroker = class _SignalBroker {
     }
     return false;
   }
+  /**
+   * Adds a signal to the signalObservers for tracking and execution.
+   * Performs validation on the signal name and emits a meta signal event when added.
+   * If the signal contains a namespace (denoted by a colon ":"), its base signal is
+   * also added if it doesn't already exist.
+   *
+   * @param {string} signal - The name of the signal to be added.
+   * @return {void} This method does not return any value.
+   */
   addSignal(signal) {
     let _signal = signal;
     if (!this.signalObservers.has(_signal)) {
@@ -365,7 +446,6 @@ var SignalBroker = class _SignalBroker {
       this.emit("meta.signal_broker.added", { __signalName: _signal });
     }
   }
-  // TODO schedule signals
   /**
    * Lists all observed signals.
    * @returns Array of signals.
@@ -380,10 +460,10 @@ var SignalBroker = class _SignalBroker {
 };
 
 // src/engine/GraphRunner.ts
-var import_uuid4 = require("uuid");
+var import_uuid5 = require("uuid");
 
 // src/engine/GraphRun.ts
-var import_uuid = require("uuid");
+var import_uuid2 = require("uuid");
 
 // src/utils/ColorRandomizer.ts
 var ColorRandomizer = class {
@@ -574,7 +654,7 @@ var VueFlowExporter = class {
 // src/engine/GraphRun.ts
 var GraphRun = class {
   constructor(strategy) {
-    this.id = (0, import_uuid.v4)();
+    this.id = (0, import_uuid2.v4)();
     this.strategy = strategy;
     this.strategy.setRunInstance(this);
     this.exporter = new VueFlowExporter();
@@ -628,10 +708,10 @@ var GraphRun = class {
 };
 
 // src/graph/execution/GraphNode.ts
-var import_uuid3 = require("uuid");
+var import_uuid4 = require("uuid");
 
 // src/graph/context/GraphContext.ts
-var import_uuid2 = require("uuid");
+var import_uuid3 = require("uuid");
 var GraphContext = class _GraphContext {
   // __keys, frozen
   constructor(context) {
@@ -645,7 +725,7 @@ var GraphContext = class _GraphContext {
     this.metadata = Object.fromEntries(
       Object.entries(this.fullContext).filter(([key]) => key.startsWith("__"))
     );
-    this.id = (0, import_uuid2.v4)();
+    this.id = (0, import_uuid3.v4)();
   }
   /**
    * Gets frozen user data (read-only, no clone).
@@ -654,6 +734,11 @@ var GraphContext = class _GraphContext {
   getContext() {
     return this.userData;
   }
+  /**
+   * Clones the current user context data and returns a deep-cloned copy of it.
+   *
+   * @return {AnyObject} A deep-cloned copy of the user context data.
+   */
   getClonedContext() {
     return deepCloneFilter(this.userData);
   }
@@ -664,6 +749,11 @@ var GraphContext = class _GraphContext {
   getFullContext() {
     return this.fullContext;
   }
+  /**
+   * Creates and returns a deep-cloned version of the fullContext object.
+   *
+   * @return {AnyObject} A deep copy of the fullContext instance, preserving all nested structures and data.
+   */
   getClonedFullContext() {
     return deepCloneFilter(this.fullContext);
   }
@@ -690,10 +780,11 @@ var GraphContext = class _GraphContext {
     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.
+   * Combines the current GraphContext with another GraphContext, merging their user data
+   * and full context into a new GraphContext instance.
+   *
+   * @param {GraphContext} otherContext - The other GraphContext to combine with the current one.
+   * @return {GraphContext} A new GraphContext instance containing merged data from both contexts.
    */
   combine(otherContext) {
     const newUser = { ...this.userData };
@@ -811,7 +902,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.destroyed = false;
     this.debug = false;
     this.verbose = false;
-    this.id = (0, import_uuid3.v4)();
+    this.id = (0, import_uuid4.v4)();
     this.task = task;
     this.context = context;
     this.retryCount = task.retryCount;
@@ -821,6 +912,8 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.splitGroupId = routineExecId;
     this.debug = debug;
     this.verbose = verbose;
+    const ctx = context.getMetadata();
+    this.executionTraceId = ctx.__executionTraceId ?? ctx.__metadata?.__executionTraceId;
     if (!this.task || !this.task.validateInput) {
       console.log("task not found", this.task, this.context);
     }
@@ -846,15 +939,40 @@ var GraphNode = class _GraphNode extends SignalEmitter {
   graphDone() {
     return this.graphComplete;
   }
+  /**
+   * Compares the current GraphNode instance with another GraphNode to determine if they are considered equal.
+   *
+   * @param {GraphNode} node - The GraphNode object to compare with the current instance.
+   * @return {boolean} Returns true if the nodes share the same task, context, and belong to the same graph; otherwise, false.
+   */
   isEqualTo(node) {
     return this.sharesTaskWith(node) && this.sharesContextWith(node) && this.isPartOfSameGraph(node);
   }
+  /**
+   * Determines if the given node is part of the same graph as the current node.
+   *
+   * @param {GraphNode} node - The node to compare with the current node.
+   * @return {boolean} Returns true if the provided node is part of the same graph
+   *                   (i.e., has the same routineExecId), otherwise false.
+   */
   isPartOfSameGraph(node) {
     return this.routineExecId === node.routineExecId;
   }
+  /**
+   * Determines whether the current instance shares a task with the provided node.
+   *
+   * @param {GraphNode} node - The graph node to compare with the current instance.
+   * @return {boolean} Returns true if the task names of both nodes match, otherwise false.
+   */
   sharesTaskWith(node) {
     return this.task.name === node.task.name;
   }
+  /**
+   * Determines whether the current node shares the same context as the specified node.
+   *
+   * @param {GraphNode} node - The graph node to compare with the current node's context.
+   * @return {boolean} True if both nodes share the same context; otherwise, false.
+   */
   sharesContextWith(node) {
     return this.context.id === node.context.id;
   }
@@ -864,9 +982,26 @@ var GraphNode = class _GraphNode extends SignalEmitter {
   getConcurrency() {
     return this.task.concurrency;
   }
+  /**
+   * Retrieves the tag associated with the current task and context.
+   *
+   * @return {string} The tag retrieved from the task within the given context.
+   */
   getTag() {
     return this.task.getTag(this.context);
   }
+  /**
+   * Schedules the current node/task on the specified graph layer if applicable.
+   *
+   * This method assesses whether the current node/task should be scheduled
+   * on the given graph layer. It ensures that tasks are only scheduled
+   * under certain conditions, such as checking if the task shares
+   * execution contexts or dependencies with other nodes, and handles
+   * various metadata emissions and context updates during the scheduling process.
+   *
+   * @param {GraphLayer} layer - The graph layer on which the current task should be scheduled.
+   * @returns {void} Does not return a value.
+   */
   scheduleOn(layer) {
     let shouldSchedule = true;
     const nodes = layer.getNodesByRoutineExecId(this.routineExecId);
@@ -890,7 +1025,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
         data: {
           uuid: this.id,
           routineExecutionId: this.routineExecId,
-          executionTraceId: context.__executionTraceId ?? context.__metadata?.__executionTraceId,
+          executionTraceId: this.executionTraceId,
           context: this.previousNodes.length === 0 ? this.context.id : this.context.export(),
           taskName: this.task.name,
           taskVersion: this.task.version,
@@ -934,10 +1069,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       if (context.__signalEmission?.consumed === false && (!this.isMeta() || this.debug)) {
         this.emitMetricsWithMetadata("meta.node.consumed_signal", {
           data: {
+            signalEmissionId: context.__signalEmission.uuid,
             signalName: context.__signalEmission.signalName,
+            signalTag: context.__signalEmission.signalTag,
             taskName: this.task.name,
             taskVersion: this.task.version,
             taskExecutionId: this.id,
+            routineExecutionId: this.routineExecId,
+            executionTraceId: this.executionTraceId,
             consumedAt: formatTimestamp(scheduledAt)
           }
         });
@@ -946,6 +1085,18 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       }
     }
   }
+  /**
+   * Starts the execution process by initializing the execution start timestamp,
+   * emitting relevant metadata, and logging debug information if applicable.
+   *
+   * The method performs the following actions:
+   * 1. Sets the execution start timestamp if it's not already initialized.
+   * 2. Emits metrics with metadata about the routine execution starting, including additional data if there are no previous nodes.
+   * 3. Optionally logs debug or verbose information based on the current settings.
+   * 4. Emits additional metrics to indicate that the execution has started.
+   *
+   * @return {number} The timestamp indicating when the execution started.
+   */
   start() {
     if (this.executionStart === 0) {
       this.executionStart = Date.now();
@@ -971,6 +1122,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     });
     return this.executionStart;
   }
+  /**
+   * Marks the end of an execution process, performs necessary cleanup, emits
+   * metrics with associated metadata, and signals the completion of execution.
+   * Also handles specific cases when the graph completes.
+   *
+   * @return {number} The timestamp corresponding to the end of execution. If execution
+   * was not started, it returns 0.
+   */
   end() {
     if (this.executionStart === 0) {
       return 0;
@@ -1023,6 +1182,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     return end;
   }
+  /**
+   * Executes the main logic of the task, including input validation, processing, and post-processing.
+   * Handles both synchronous and asynchronous workflows.
+   *
+   * @return {Array|Promise|undefined} Returns the next nodes to process if available.
+   * If asynchronous processing is required, it returns a Promise that resolves to the next nodes.
+   * Returns undefined in case of an error during input validation or preconditions that prevent processing.
+   */
   execute() {
     if (!this.divided && !this.processing) {
       this.processing = true;
@@ -1046,6 +1213,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     return this.nextNodes;
   }
+  /**
+   * Executes an asynchronous workflow that processes a result and retries on errors.
+   * The method handles different result states, checks for error properties, and invokes
+   * error handling when necessary.
+   *
+   * @return {Promise<void>} A promise that resolves when the operation completes successfully,
+   * or rejects if an unhandled error occurs.
+   */
   async workAsync() {
     try {
       this.result = await this.result;
@@ -1062,6 +1237,12 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       }
     }
   }
+  /**
+   * Executes an asynchronous operation, processes the result, and determines the next nodes to execute.
+   * This method will manage asynchronous work, handle post-processing of results, and ensure proper handling of both synchronous and asynchronous next node configurations.
+   *
+   * @return {Promise<any>} A promise resolving to the next nodes to be executed. Can be the result of post-processing or a directly resolved next nodes object.
+   */
   async executeAsync() {
     await this.workAsync();
     const nextNodes = this.postProcess();
@@ -1071,6 +1252,16 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.nextNodes = nextNodes;
     return this.nextNodes;
   }
+  /**
+   * Executes the task associated with the current instance, using the given context,
+   * progress callback, and metadata. If the task fails or an error occurs, it attempts
+   * to retry the execution. If the retry is not successful, it propagates the error and
+   * returns the result.
+   *
+   * @return {TaskResult | Promise<TaskResult>} The result of the task execution, or a
+   * promise that resolves to the task result. This includes handling for retries on
+   * failure and error propagation.
+   */
   work() {
     try {
       const result = this.task.execute(
@@ -1094,39 +1285,67 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       });
     }
   }
+  /**
+   * Emits a signal along with its associated metadata. The metadata includes
+   * task-specific information such as task name, version, execution ID, and
+   * additional context metadata like routine execution ID and execution trace ID.
+   * This method is designed to enrich emitted signals with relevant details
+   * before broadcasting them.
+   *
+   * @param {string} signal - The name of the signal to be emitted.
+   * @param {AnyObject} data - The data object to be sent along with the signal. Metadata
+   * will be injected into this object before being emitted.
+   * @return {void} No return value.
+   */
   emitWithMetadata(signal, data) {
     if (!this.task?.isHidden) {
       data.__signalEmission = {
         taskName: this.task.name,
         taskVersion: this.task.version,
-        taskExecutionId: this.id
+        taskExecutionId: this.id,
+        routineExecutionId: this.routineExecId,
+        executionTraceId: this.executionTraceId,
+        isMetric: false
       };
-      const context = this.context.getMetadata();
       data.__metadata = {
         ...data.__metadata,
         __routineExecId: this.routineExecId,
-        __executionTraceId: context.__metadata?.__executionTraceId ?? context.__executionTraceId
+        __executionTraceId: this.executionTraceId
       };
     }
     this.emit(signal, data);
   }
+  /**
+   * Emits metrics with additional metadata describing the task execution and context.
+   *
+   * @param {string} signal - The signal name being emitted.
+   * @param {AnyObject} data - The data associated with the signal emission, enriched with metadata.
+   * @return {void} Emits the signal with enriched data and does not return a value.
+   */
   emitMetricsWithMetadata(signal, data) {
     if (!this.task?.isHidden) {
       data.__signalEmission = {
         taskName: this.task.name,
         taskVersion: this.task.version,
         taskExecutionId: this.id,
+        routineExecutionId: this.routineExecId,
+        executionTraceId: this.executionTraceId,
         isMetric: true
       };
-      const context = this.context.getMetadata();
       data.__metadata = {
         ...data.__metadata,
         __routineExecId: this.routineExecId,
-        __executionTraceId: context.__metadata?.__executionTraceId ?? context.__executionTraceId
+        __executionTraceId: this.executionTraceId
       };
     }
     this.emitMetrics(signal, data);
   }
+  /**
+   * Updates the progress of a task and emits metrics with associated metadata.
+   *
+   * @param {number} progress - A number representing the progress value, which will be clamped between 0 and 1.
+   * @return {void} This method does not return a value.
+   */
   onProgress(progress) {
     progress = Math.min(Math.max(0, progress), 1);
     this.emitMetricsWithMetadata("meta.node.progress", {
@@ -1149,6 +1368,18 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       }
     );
   }
+  /**
+   * Processes the result of the current operation, validates it, and determines the next set of nodes.
+   *
+   * This method ensures that results of certain types such as strings or arrays
+   * are flagged as errors. It divides the current context into subsequent nodes
+   * for further processing. If the division returns a promise, it delegates the
+   * processing to `postProcessAsync`. For synchronous division, it sets the
+   * `nextNodes` and finalizes the operation.
+   *
+   * @return {(Array|undefined)} Returns an array of next nodes for further processing,
+   * or undefined if no further processing is required.
+   */
   postProcess() {
     if (typeof this.result === "string") {
       this.onError(
@@ -1166,11 +1397,23 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.finalize();
     return this.nextNodes;
   }
+  /**
+   * Asynchronously processes and finalizes the provided graph nodes.
+   *
+   * @param {Promise<GraphNode[]>} nextNodes A promise that resolves to an array of graph nodes to be processed.
+   * @return {Promise<GraphNode[]>} A promise that resolves to the processed array of graph nodes.
+   */
   async postProcessAsync(nextNodes) {
     this.nextNodes = await nextNodes;
     this.finalize();
     return this.nextNodes;
   }
+  /**
+   * Finalizes the current task execution by determining if the task is complete, handles any errors or failures,
+   * emits relevant signals based on the task outcomes, and ensures proper end of the task lifecycle.
+   *
+   * @return {void} Does not return a value.
+   */
   finalize() {
     if (this.nextNodes.length === 0) {
       this.completeSubgraph();
@@ -1186,6 +1429,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     this.end();
   }
+  /**
+   * Handles an error event, processes the error, and updates the state accordingly.
+   *
+   * @param {unknown} error - The error object or message that occurred.
+   * @param {AnyObject} [errorData={}] - Additional error data to include in the result.
+   * @return {void} This method does not return any value.
+   */
   onError(error, errorData = {}) {
     this.result = {
       ...this.context.getFullContext(),
@@ -1199,6 +1449,12 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.migrate(this.result);
     this.errored = true;
   }
+  /**
+   * Retries a task based on the defined retry count and delay time. If the retry count is 0, it immediately resolves with the provided previous result.
+   *
+   * @param {any} [prevResult] - The result from a previous attempt, if any, to return when no retries are performed.
+   * @return {Promise<TaskResult>} - A promise that resolves with the result of the retried task or the previous result if no retries occur.
+   */
   async retry(prevResult) {
     if (this.retryCount === 0) {
       return prevResult;
@@ -1206,6 +1462,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     await this.delayRetry();
     return this.work();
   }
+  /**
+   * Retries an asynchronous operation and returns its result.
+   * If the retry count is zero, the method immediately returns the provided previous result.
+   *
+   * @param {any} [prevResult] - The optional result from a previous operation attempt, if applicable.
+   * @return {Promise<TaskResult>} A promise that resolves to the result of the retried operation.
+   */
   async retryAsync(prevResult) {
     if (this.retryCount === 0) {
       return prevResult;
@@ -1223,6 +1486,15 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       this.retryDelay = this.task.retryDelayMax;
     }
   }
+  /**
+   * Processes the result of a task by generating new nodes based on the task output.
+   * The method handles synchronous and asynchronous generators, validates task output,
+   * and creates new nodes accordingly. If errors occur, the method attempts to handle them
+   * by generating alternative task nodes.
+   *
+   * @return {GraphNode[] | Promise<GraphNode[]>} Returns an array of generated GraphNode objects
+   * (synchronously or wrapped in a Promise) based on the task result, or propagates errors if validation fails.
+   */
   divide() {
     const newNodes = [];
     if (this.result?.next && typeof this.result.next === "function") {
@@ -1261,7 +1533,7 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     if (this.errored) {
       newNodes.push(
         ...this.task.mapNext(
-          (t) => this.clone().split((0, import_uuid3.v4)()).differentiate(t).migrate({ ...this.result }),
+          (t) => this.clone().split((0, import_uuid4.v4)()).differentiate(t).migrate({ ...this.result }),
           true
         )
       );
@@ -1274,6 +1546,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     });
     return newNodes;
   }
+  /**
+   * Processes an asynchronous iterator result, validates its output, and generates new graph nodes accordingly.
+   * Additionally, continues to process and validate results from an asynchronous generator.
+   *
+   * @param {Promise<IteratorResult<any>>} current - A promise resolving to the current step result from an asynchronous iterator.
+   * @return {Promise<GraphNode[]>} A promise resolving to an array of generated GraphNode objects based on validated outputs.
+   */
   async divideAsync(current) {
     const nextNodes = [];
     const _current = await current;
@@ -1296,8 +1575,14 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.divided = true;
     return nextNodes;
   }
+  /**
+   * Generates new nodes based on the provided result and task configuration.
+   *
+   * @param {any} result - The result of the previous operation, which determines the configuration and context for new nodes. It can be a boolean or an object containing details like failure, errors, or metadata.
+   * @return {GraphNode[]} An array of newly generated graph nodes configured based on the task and context.
+   */
   generateNewNodes(result) {
-    const groupId = (0, import_uuid3.v4)();
+    const groupId = (0, import_uuid4.v4)();
     const newNodes = [];
     if (typeof result !== "boolean") {
       const failed = result.failed !== void 0 && result.failed || result.error !== void 0;
@@ -1338,6 +1623,12 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     return newNodes;
   }
+  /**
+   * Executes the differentiation process based on a given task and updates the instance properties accordingly.
+   *
+   * @param {Task} task - The task object containing information such as retry count, retry delay, and metadata status.
+   * @return {GraphNode} The updated instance after processing the task.
+   */
   differentiate(task) {
     this.task = task;
     this.retryCount = task.retryCount;
@@ -1345,14 +1636,32 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.silent = task.isMeta && !this.debug || task.isSubMeta || this.context?.getMetadata()?.__isSubMeta;
     return this;
   }
+  /**
+   * Migrates the current instance to a new context and returns the updated instance.
+   *
+   * @param {any} ctx - The context data to be used for migration.
+   * @return {GraphNode} The updated instance after migration.
+   */
   migrate(ctx) {
     this.context = new GraphContext(ctx);
     return this;
   }
+  /**
+   * Splits the current node into a new group identified by the provided ID.
+   *
+   * @param {string} id - The unique identifier for the new split group.
+   * @return {GraphNode} The current instance of the GraphNode with the updated split group ID.
+   */
   split(id) {
     this.splitGroupId = id;
     return this;
   }
+  /**
+   * Creates a new instance of the GraphNode with the current node's properties.
+   * This method allows for duplicating the existing graph node.
+   *
+   * @return {GraphNode} A new instance of GraphNode that is a copy of the current node.
+   */
   clone() {
     return new _GraphNode(
       this.task,
@@ -1363,6 +1672,13 @@ var GraphNode = class _GraphNode extends SignalEmitter {
       this.verbose
     );
   }
+  /**
+   * Consumes the given graph node by combining contexts, merging previous nodes,
+   * and performing associated operations on the provided node.
+   *
+   * @param {GraphNode} node - The graph node to be consumed.
+   * @return {void} This method does not return a value.
+   */
   consume(node) {
     this.context = this.context.combine(node.context);
     this.previousNodes = this.previousNodes.concat(node.previousNodes);
@@ -1370,9 +1686,22 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     node.changeIdentity(this.id);
     node.destroy();
   }
+  /**
+   * Changes the identity of the current instance by updating the `id` property.
+   *
+   * @param {string} id - The new identity value to be assigned.
+   * @return {void} Does not return a value.
+   */
   changeIdentity(id) {
     this.id = id;
   }
+  /**
+   * Completes the subgraph for the current node and recursively for its previous nodes
+   * once all next nodes have their subgraphs marked as done. If there are no previous nodes,
+   * it completes the entire graph.
+   *
+   * @return {void} Does not return a value.
+   */
   completeSubgraph() {
     for (const node of this.nextNodes) {
       if (!node.subgraphDone()) {
@@ -1386,10 +1715,22 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     }
     this.previousNodes.forEach((n) => n.completeSubgraph());
   }
+  /**
+   * Completes the current graph by setting a flag indicating the graph has been completed
+   * and recursively completes all subsequent nodes in the graph.
+   *
+   * @return {void} Does not return a value.
+   */
   completeGraph() {
     this.graphComplete = true;
     this.nextNodes.forEach((n) => n.completeGraph());
   }
+  /**
+   * Destroys the current instance by releasing resources, breaking references,
+   * and resetting properties to ensure proper cleanup.
+   *
+   * @return {void} No return value.
+   */
   destroy() {
     this.context = null;
     this.task = null;
@@ -1402,15 +1743,40 @@ var GraphNode = class _GraphNode extends SignalEmitter {
     this.layer = void 0;
     this.destroyed = true;
   }
+  /**
+   * Retrieves an iterator for traversing through the graph nodes.
+   *
+   * @return {GraphNodeIterator} An iterator instance specific to this graph node.
+   */
   getIterator() {
     return new GraphNodeIterator(this);
   }
+  /**
+   * Applies a callback function to each node in the `nextNodes` array and returns
+   * the resulting array from the map operation.
+   *
+   * @param {function} callback - A function to execute on each `GraphNode` in the `nextNodes` array.
+   * The function receives a `GraphNode` as its argument.
+   * @return {Array} The resulting array after applying the callback function to each node in `nextNodes`.
+   */
   mapNext(callback) {
     return this.nextNodes.map(callback);
   }
+  /**
+   * Accepts a visitor object and calls its visitNode method with the current instance.
+   *
+   * @param {GraphVisitor} visitor - The visitor instance implementing the GraphVisitor interface.
+   * @return {void} This method does not return a value.
+   */
   accept(visitor) {
     visitor.visitNode(this);
   }
+  /**
+   * Exports the current object's state and returns it in a serialized format.
+   * The exported object contains metadata, task details, context information, execution times, node relationships, routine execution status, and other state information.
+   *
+   * @return {Object} An object representing the current state.
+   */
   export() {
     return {
       __id: this.id,
@@ -1508,9 +1874,12 @@ var GraphRoutine = class extends SignalEmitter {
     });
   }
   /**
-   * Applies callback to starting tasks.
-   * @param callBack The callback.
-   * @returns Promise if async.
+   * Iterates over each task in the `tasks` collection and applies the provided callback function.
+   * If the callback returns a Promise, resolves all Promises concurrently.
+   *
+   * @param {function} callBack - A function to be executed on each task from the `tasks` collection.
+   *                              The callback receives the current task as its argument.
+   * @return {Promise<void>} A Promise that resolves once all callback executions, including asynchronous ones, are complete.
    */
   async forEachTask(callBack) {
     const promises = [];
@@ -1529,10 +1898,10 @@ var GraphRoutine = class extends SignalEmitter {
     this.emit("meta.routine.global_version_set", { version: this.version });
   }
   /**
-   * Subscribes to signals (chainable).
-   * @param signals The signal names.
-   * @returns This for chaining.
-   * @edge Duplicates ignored; assumes broker.observe binds this as handler.
+   * Subscribes the current instance to the specified signals, enabling it to observe them.
+   *
+   * @param {...string} signals - The names of the signals to observe.
+   * @return {this} Returns the instance to allow for method chaining.
    */
   doOn(...signals) {
     signals.forEach((signal) => {
@@ -1543,8 +1912,11 @@ var GraphRoutine = class extends SignalEmitter {
     return this;
   }
   /**
-   * Unsubscribes from all observed signals.
-   * @returns This for chaining.
+   * Unsubscribes from all observed signals and clears the internal collection
+   * of observed signals. This ensures that the instance is no longer listening
+   * or reacting to any previously subscribed signals.
+   *
+   * @return {this} Returns the current instance for chaining purposes.
    */
   unsubscribeAll() {
     this.observedSignals.forEach(
@@ -1554,10 +1926,10 @@ var GraphRoutine = class extends SignalEmitter {
     return this;
   }
   /**
-   * Unsubscribes from specific signals.
-   * @param signals The signals.
-   * @returns This for chaining.
-   * @edge No-op if not subscribed.
+   * Unsubscribes the current instance from the specified signals.
+   *
+   * @param {...string} signals - The signals to unsubscribe from.
+   * @return {this} The current instance for method chaining.
    */
   unsubscribe(...signals) {
     signals.forEach((signal) => {
@@ -1569,7 +1941,12 @@ var GraphRoutine = class extends SignalEmitter {
     return this;
   }
   /**
-   * Destroys the routine.
+   * Cleans up resources and emits an event indicating the destruction of the routine.
+   *
+   * This method unsubscribes from all events, clears the tasks list,
+   * and emits a "meta.routine.destroyed" event with details of the destruction.
+   *
+   * @return {void}
    */
   destroy() {
     this.unsubscribeAll();
@@ -1615,27 +1992,27 @@ var TaskIterator = class {
 // src/graph/definition/Task.ts
 var Task = class extends SignalEmitter {
   /**
-   * 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).
-   * @param isUnique
-   * @param isMeta
-   * @param isSubMeta
-   * @param isHidden
-   * @param getTagCallback
-   * @param inputSchema
-   * @param validateInputContext
-   * @param outputSchema
-   * @param validateOutputContext
-   * @param retryCount
-   * @param retryDelay
-   * @param retryDelayMax
-   * @param retryDelayFactor
-   * @edge Emits 'meta.task.created' with { __task: this } for seed.
+   * Constructs an instance of the task with the specified properties and configuration options.
+   *
+   * @param {string} name - The name of the task.
+   * @param {TaskFunction} task - The function that represents the task logic.
+   * @param {string} [description=""] - A description of the task.
+   * @param {number} [concurrency=0] - The number of concurrent executions allowed for the task.
+   * @param {number} [timeout=0] - The maximum execution time for the task in milliseconds.
+   * @param {boolean} [register=true] - Indicates if the task should be registered or not.
+   * @param {boolean} [isUnique=false] - Specifies if the task should only allow one instance to exist at any time.
+   * @param {boolean} [isMeta=false] - Indicates if the task is a meta-task.
+   * @param {boolean} [isSubMeta=false] - Indicates if the task is a sub-meta-task.
+   * @param {boolean} [isHidden=false] - Determines if the task is hidden and not exposed publicly.
+   * @param {ThrottleTagGetter} [getTagCallback=undefined] - A callback to generate a throttle tag for the task.
+   * @param {SchemaDefinition} [inputSchema=undefined] - The input schema for validating the task's input context.
+   * @param {boolean} [validateInputContext=false] - Specifies if the input context should be validated against the input schema.
+   * @param {SchemaDefinition} [outputSchema=undefined] - The output schema for validating the task's output context.
+   * @param {boolean} [validateOutputContext=false] - Specifies if the output context should be validated against the output schema.
+   * @param {number} [retryCount=0] - The number of retry attempts allowed for the task in case of failure.
+   * @param {number} [retryDelay=0] - The initial delay (in milliseconds) between retry attempts.
+   * @param {number} [retryDelayMax=0] - The maximum delay (in milliseconds) allowed between retries.
+   * @param {number} [retryDelayFactor=1] - The factor by which the retry delay increases after each attempt.
    */
   constructor(name, task, description = "", concurrency = 0, timeout = 0, register = true, isUnique = false, isMeta = false, isSubMeta = false, isHidden = false, getTagCallback = void 0, inputSchema = void 0, validateInputContext = false, outputSchema = void 0, validateOutputContext = false, retryCount = 0, retryDelay = 0, retryDelayMax = 0, retryDelayFactor = 1) {
     super(isSubMeta || isHidden);
@@ -1724,6 +2101,13 @@ var Task = class extends SignalEmitter {
       });
     }
   }
+  /**
+   * Retrieves the tag associated with the instance.
+   * Can be overridden by subclasses.
+   *
+   * @param {AnyObject} [context] - Optional context parameter that can be provided.
+   * @return {string} The tag value of the instance.
+   */
   getTag(context) {
     return this.name;
   }
@@ -1754,16 +2138,35 @@ var Task = class extends SignalEmitter {
   setValidateOutputContext(value) {
     this.validateOutputContext = value;
   }
+  /**
+   * Emits a signal along with metadata if certain conditions are met.
+   *
+   * This method sends a signal with optional context data and adds metadata
+   * to the emitted data if the instance is not hidden and not a subordinate metadata object.
+   *
+   * @param {string} signal - The name of the signal to emit.
+   * @param {AnyObject} [ctx={}] - Additional context data to include with the emitted signal.
+   * @return {void} Does not return a value.
+   */
   emitWithMetadata(signal, ctx = {}) {
     const data = { ...ctx };
     if (!this.isHidden && !this.isSubMeta) {
       data.__signalEmission = {
         taskName: this.name,
-        taskVersion: this.version
+        taskVersion: this.version,
+        isMetric: false
       };
     }
     this.emit(signal, data);
   }
+  /**
+   * Emits metrics with additional metadata enhancement based on the context and the state of the instance.
+   * This is used to prevent loops on the meta layer in debug mode.
+   *
+   * @param {string} signal - The signal identifier for the metric being emitted.
+   * @param {AnyObject} [ctx={}] - Optional context object to provide additional information with the metric.
+   * @return {void} This method does not return any value.
+   */
   emitMetricsWithMetadata(signal, ctx = {}) {
     const data = { ...ctx };
     if (!this.isHidden && !this.isSubMeta) {
@@ -1776,12 +2179,13 @@ var Task = class extends SignalEmitter {
     this.emitMetrics(signal, data);
   }
   /**
-   * Validates a context deeply against a schema.
-   * @param data - The data to validate (input context or output result).
-   * @param schema - The schema definition.
-   * @param path - The current path for error reporting (default: 'root').
-   * @returns { { valid: boolean, errors: Record<string, string> } } - Validation result with detailed errors if invalid.
-   * @description Recursively checks types, required fields, and constraints; allows extra properties not in schema.
+   * Validates a data object against a specified schema definition and returns validation results.
+   *
+   * @param {any} data - The target object to validate against the schema.
+   * @param {SchemaDefinition | undefined} schema - The schema definition describing the expected structure and constraints of the data.
+   * @param {string} [path="context"] - The base path or context for traversing the data, used in generating error messages.
+   * @return {{ valid: boolean, errors: Record<string, string> }} - An object containing a validity flag (`valid`)
+   * and a map (`errors`) of validation error messages keyed by property paths.
    */
   validateSchema(data, schema, path = "context") {
     const errors = {};
@@ -1884,6 +2288,12 @@ var Task = class extends SignalEmitter {
     }
     return { valid: true, errors: {} };
   }
+  /**
+   * Validates the input context against the predefined schema and emits metadata if validation fails.
+   *
+   * @param {AnyObject} context - The input context to validate.
+   * @return {true | AnyObject} - Returns `true` if validation succeeds, otherwise returns an error object containing details of the validation failure.
+   */
   validateInput(context) {
     if (this.validateInputContext) {
       const validationResult = this.validateSchema(
@@ -1906,6 +2316,13 @@ var Task = class extends SignalEmitter {
     }
     return true;
   }
+  /**
+   * Validates the output context using the provided schema and emits metadata if validation fails.
+   *
+   * @param {AnyObject} context - The output context to validate.
+   * @return {true | AnyObject} Returns `true` if the output context is valid; otherwise, returns an object
+   * containing error information when validation fails.
+   */
   validateOutput(context) {
     if (this.validateOutputContext) {
       const validationResult = this.validateSchema(
@@ -1929,14 +2346,13 @@ var Task = class extends SignalEmitter {
     return true;
   }
   /**
-   * Executes the task function after optional input validation.
-   * @param context - The GraphContext to validate and execute.
-   * @param emit
-   * @param progressCallback - Callback for progress updates.
-   * @param nodeData
-   * @returns TaskResult from the taskFunction or error object on validation failure.
-   * @edge If validateInputContext is true, validates context; on failure, emits 'meta.task.validationFailed' with detailed errors.
-   * @edge If validateOutputContext is true, validates output; on failure, emits 'meta.task.outputValidationFailed' with detailed errors.
+   * Executes a task within a given context, optionally emitting signals and reporting progress.
+   *
+   * @param {GraphContext} context The execution context which provides data and functions necessary for the task.
+   * @param {function(string, AnyObject): void} emit A function to emit signals and communicate intermediate results or states.
+   * @param {function(number): void} progressCallback A callback function used to report task progress as a percentage (0 to 100).
+   * @param {{ nodeId: string; routineExecId: string }} nodeData An object containing identifiers related to the node and execution routine.
+   * @return {TaskResult} The result of the executed task.
    */
   execute(context, emit, progressCallback, nodeData) {
     return this.taskFunction(
@@ -1945,6 +2361,15 @@ var Task = class extends SignalEmitter {
       progressCallback
     );
   }
+  /**
+   * Adds tasks as predecessors to the current task and establishes dependencies between them.
+   * Ensures that adding predecessors does not create cyclic dependencies.
+   * Updates task relationships, progress weights, and emits relevant metrics after operations.
+   *
+   * @param {Task[]} tasks - An array of tasks to be added as predecessors to the current task.
+   * @return {this} The current task instance for method chaining.
+   * @throws {Error} Throws an error if adding a predecessor creates a cycle in the task structure.
+   */
   doAfter(...tasks) {
     for (const pred of tasks) {
       if (this.predecessorTasks.has(pred)) continue;
@@ -1967,6 +2392,14 @@ var Task = class extends SignalEmitter {
     this.updateProgressWeights();
     return this;
   }
+  /**
+   * Adds a sequence of tasks as successors to the current task, ensuring no cyclic dependencies are introduced.
+   * Metrics are emitted when a relationship is successfully added.
+   *
+   * @param {...Task} tasks - The tasks to be added as successors to the current task.
+   * @return {this} Returns the current task instance for method chaining.
+   * @throws {Error} Throws an error if adding a task causes a cyclic dependency.
+   */
   then(...tasks) {
     for (const next of tasks) {
       if (this.nextTasks.has(next)) continue;
@@ -1989,6 +2422,12 @@ var Task = class extends SignalEmitter {
     this.updateProgressWeights();
     return this;
   }
+  /**
+   * Decouples the current task from the provided task by removing mutual references.
+   *
+   * @param {Task} task - The task to decouple from the current task.
+   * @return {void} This method does not return a value.
+   */
   decouple(task) {
     if (task.nextTasks.has(this)) {
       task.nextTasks.delete(this);
@@ -2000,6 +2439,14 @@ var Task = class extends SignalEmitter {
     }
     this.updateLayerFromPredecessors();
   }
+  /**
+   * Updates the progress weights for tasks within each layer of the subgraph.
+   * The progress weight for each task is calculated based on the inverse proportion
+   * of the number of layers and the number of tasks in each layer. This ensures an
+   * even distribution of progress weight across the tasks in the layers.
+   *
+   * @return {void} Does not return a value.
+   */
   updateProgressWeights() {
     const layers = this.getSubgraphLayers();
     const numLayers = layers.size;
@@ -2013,6 +2460,12 @@ var Task = class extends SignalEmitter {
       );
     });
   }
+  /**
+   * Retrieves a mapping of layer indices to sets of tasks within each layer of a subgraph.
+   * This method traverses the task dependencies and organizes tasks by their respective layer indices.
+   *
+   * @return {Map<number, Set<Task>>} A map where the key is the layer index (number) and the value is a set of tasks (Set<Task>) belonging to that layer.
+   */
   getSubgraphLayers() {
     const layers = /* @__PURE__ */ new Map();
     const queue = [this];
@@ -2027,6 +2480,13 @@ var Task = class extends SignalEmitter {
     }
     return layers;
   }
+  /**
+   * Updates the `layerIndex` of the current task based on the maximum layer index of its predecessors
+   * and propagates the update recursively to all subsequent tasks. If the `layerIndex` changes,
+   * emits a metric event with metadata about the change.
+   *
+   * @return {void} This method does not return a value.
+   */
   updateLayerFromPredecessors() {
     const prevLayerIndex = this.layerIndex;
     let maxPred = 0;
@@ -2049,6 +2509,12 @@ var Task = class extends SignalEmitter {
       next.nextTasks.forEach((n) => queue.push(n));
     }
   }
+  /**
+   * Determines whether there is a cycle in the tasks graph.
+   * This method performs a depth-first search (DFS) to detect cycles.
+   *
+   * @return {boolean} - Returns true if a cycle is found in the graph, otherwise false.
+   */
   hasCycle() {
     const visited = /* @__PURE__ */ new Set();
     const recStack = /* @__PURE__ */ new Set();
@@ -2065,18 +2531,33 @@ var Task = class extends SignalEmitter {
     };
     return dfs(this);
   }
+  /**
+   * Maps over the next set of tasks or failed tasks if specified, applying the provided callback function.
+   *
+   * @param {Function} callback A function that will be called with each task, transforming the task as needed. It receives a single parameter of type Task.
+   * @param {boolean} [failed=false] A boolean that determines whether to map over the failed tasks (true) or the next tasks (false).
+   * @return {any[]} An array of transformed tasks resulting from applying the callback function.
+   */
   mapNext(callback, failed = false) {
     const tasks = failed ? Array.from(this.onFailTasks) : Array.from(this.nextTasks);
     return tasks.map(callback);
   }
+  /**
+   * Maps through each task in the set of predecessor tasks and applies the provided callback function.
+   *
+   * @param {function} callback - A function to execute on each task in the predecessor tasks. The function receives a `Task` object as its argument and returns any value.
+   * @return {any[]} An array containing the results of applying the callback function to each predecessor task.
+   */
   mapPrevious(callback) {
     return Array.from(this.predecessorTasks).map(callback);
   }
   /**
-   * Subscribes to signals (chainable).
-   * @param signals The signal names.
-   * @returns This for chaining.
-   * @edge Duplicates ignored; assumes broker.observe binds this as handler.
+   * Adds the specified signals to the current instance, making it observe them.
+   * If the instance is already observing a signal, it will be skipped.
+   * The method also emits metadata information if the `register` property is set.
+   *
+   * @param {...string[]} signals - The array of signal names to observe.
+   * @return {this} The current instance after adding the specified signals.
    */
   doOn(...signals) {
     signals.forEach((signal) => {
@@ -2096,9 +2577,10 @@ var Task = class extends SignalEmitter {
     return this;
   }
   /**
-   * Sets signals to emit post-execution (chainable).
-   * @param signals The signal names.
-   * @returns This for chaining.
+   * Registers the specified signals to be emitted after the Task executes successfully and attaches them for further processing.
+   *
+   * @param {...string} signals - The list of signals to be registered for emission.
+   * @return {this} The current instance for method chaining.
    */
   emits(...signals) {
     signals.forEach((signal) => {
@@ -2107,6 +2589,13 @@ var Task = class extends SignalEmitter {
     });
     return this;
   }
+  /**
+   * Configures the instance to emit specified signals when the task execution fails.
+   * A failure is defined as anything that does not return a successful result.
+   *
+   * @param {...string} signals - The names of the signals to emit upon failure.
+   * @return {this} Returns the current instance for chaining.
+   */
   emitsOnFail(...signals) {
     signals.forEach((signal) => {
       this.signalsToEmitOnFail.add(signal);
@@ -2114,6 +2603,13 @@ var Task = class extends SignalEmitter {
     });
     return this;
   }
+  /**
+   * Attaches a signal to the current context and emits metadata if the register flag is set.
+   *
+   * @param {string} signal - The name of the signal to attach.
+   * @param {boolean} [isOnFail=false] - Indicates if the signal should be marked as "on fail".
+   * @return {void} This method does not return a value.
+   */
   attachSignal(signal, isOnFail = false) {
     this.emitsSignals.add(signal);
     if (this.register) {
@@ -2128,10 +2624,12 @@ var Task = class extends SignalEmitter {
     }
   }
   /**
-   * Unsubscribes from specific signals.
-   * @param signals The signals.
-   * @returns This for chaining.
-   * @edge No-op if not subscribed.
+   * Unsubscribes the current instance from the specified signals.
+   * This method removes the signals from the observedSignals set, unsubscribes
+   * from the underlying broker, and emits metadata for the unsubscription if applicable.
+   *
+   * @param {string[]} signals - The list of signal names to unsubscribe from.
+   * @return {this} Returns the current instance for method chaining.
    */
   unsubscribe(...signals) {
     signals.forEach((signal) => {
@@ -2153,8 +2651,9 @@ var Task = class extends SignalEmitter {
     return this;
   }
   /**
-   * Unsubscribes from all observed signals.
-   * @returns This for chaining.
+   * Unsubscribes from all currently observed signals and clears the list of observed signals.
+   *
+   * @return {this} The instance of the class to allow method chaining.
    */
   unsubscribeAll() {
     this.unsubscribe(...this.observedSignals);
@@ -2162,9 +2661,10 @@ var Task = class extends SignalEmitter {
     return this;
   }
   /**
-   * Detaches specific emitted signals.
-   * @param signals The signals.
-   * @returns This for chaining.
+   * Detaches the specified signals from being emitted after execution and optionally emits metadata for each detached signal.
+   *
+   * @param {...string} signals - The list of signal names to be detached. Signals can be in the format "namespace:signalName".
+   * @return {this} Returns the current instance of the object for method chaining.
    */
   detachSignals(...signals) {
     signals.forEach((signal) => {
@@ -2183,27 +2683,50 @@ var Task = class extends SignalEmitter {
     return this;
   }
   /**
-   * Detaches all emitted signals.
-   * @returns This for chaining.
+   * Detaches all signals associated with the object by invoking the `detachSignals` method
+   * and clearing the `signalsToEmitAfter` collection.
+   *
+   * @return {this} Returns the current instance to allow method chaining.
    */
   detachAllSignals() {
     this.detachSignals(...this.signalsToEmitAfter);
     this.signalsToEmitAfter.clear();
     return this;
   }
+  /**
+   * Maps over the signals in the `signalsToEmitAfter` set and applies a callback function to each signal.
+   *
+   * @param {function(string): void} callback - A function that is called with each signal
+   *   in the `signalsToEmitAfter` set, providing the signal as an argument.
+   * @return {Array<any>} An array containing the results of applying the callback
+   *   function to each signal.
+   */
   mapSignals(callback) {
     return Array.from(this.signalsToEmitAfter).map(callback);
   }
+  /**
+   * Maps over the signals in `signalsToEmitOnFail` and applies the provided callback to each signal.
+   *
+   * @param {function(string): void} callback - A function that receives each signal as a string and performs an operation or transformation on it.
+   * @return {Array} The array resulting from applying the callback to each signal in `signalsToEmitOnFail`.
+   */
   mapOnFailSignals(callback) {
     return Array.from(this.signalsToEmitOnFail).map(callback);
   }
+  /**
+   * Maps over the observed signals with the provided callback function.
+   *
+   * @param {function(string): void} callback - A function to execute on each signal in the observed signals array.
+   * @return {Array} A new array containing the results of calling the callback function on each observed signal.
+   */
   mapObservedSignals(callback) {
     return Array.from(this.observedSignals).map(callback);
   }
   /**
-   * Emits attached signals.
-   * @param context The context for emission.
-   * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
+   * Emits a collection of signals stored in the `signalsToEmitAfter` array.
+   *
+   * @param {GraphContext} context - The context object containing data or state to be passed to the emitted signals.
+   * @return {void} This method does not return a value.
    */
   emitSignals(context) {
     this.signalsToEmitAfter.forEach((signal) => {
@@ -2211,15 +2734,29 @@ var Task = class extends SignalEmitter {
     });
   }
   /**
-   * Emits attached fail signals.
-   * @param context The context for emission.
-   * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
+   * Emits registered signals when an operation fails.
+   *
+   * @param {GraphContext} context - The context from which the full context is derived and passed to the signals being emitted.
+   * @return {void} This method does not return any value.
    */
   emitOnFailSignals(context) {
     this.signalsToEmitOnFail.forEach((signal) => {
       this.emit(signal, context.getFullContext());
     });
   }
+  /**
+   * Cleans up and destroys the task instance, detaching it from other tasks and
+   * performing necessary cleanup operations.
+   *
+   * This method:
+   * - Unsubscribes from all signals and events.
+   * - Detaches all associated signal handlers.
+   * - Removes the task from successor and predecessor task mappings.
+   * - Clears all task relationships and marks the task as destroyed.
+   * - Emits destruction metrics, if applicable.
+   *
+   * @return {void} No value is returned because the function performs clean-up operations.
+   */
   destroy() {
     this.unsubscribeAll();
     this.detachAllSignals();
@@ -2237,6 +2774,18 @@ var Task = class extends SignalEmitter {
       });
     }
   }
+  /**
+   * Exports the current state of the object as a structured plain object.
+   *
+   * @return {AnyObject} An object containing the serialized properties of the current instance. The exported object includes various metadata, schema information, task attributes, and related tasks, such as:
+   * - Name and description of the task.
+   * - Layer index, uniqueness, meta, and signal-related flags.
+   * - Event triggers and attached signals.
+   * - Throttling, concurrency, timeout settings, and ephemeral flag.
+   * - Task function as a string.
+   * - Serialization of getter callbacks and schemas for input/output validation.
+   * - Relationships such as next tasks, failure tasks, and predecessor tasks.
+   */
   export() {
     return {
       __name: this.name,
@@ -2263,9 +2812,20 @@ var Task = class extends SignalEmitter {
       __previousTasks: Array.from(this.predecessorTasks).map((t) => t.name)
     };
   }
+  /**
+   * Returns an iterator for iterating over tasks associated with this instance.
+   *
+   * @return {TaskIterator} An iterator instance for tasks.
+   */
   getIterator() {
     return new TaskIterator(this);
   }
+  /**
+   * Accepts a visitor object to perform operations on the current instance.
+   *
+   * @param {GraphVisitor} visitor - The visitor object implementing operations for this instance.
+   * @return {void} This method does not return a value.
+   */
   accept(visitor) {
     visitor.visitTask(this);
   }
@@ -2276,6 +2836,16 @@ var Task = class extends SignalEmitter {
 
 // src/registry/GraphRegistry.ts
 var GraphRegistry = class _GraphRegistry {
+  /**
+   * Constructs a new instance and sets up various meta tasks and routines.
+   *
+   * This constructor initializes several predefined tasks for managing operations
+   * like registering tasks, updating schemas for tasks, fetching tasks or routines,
+   * and performing actions on all tasks or routines. It also initializes routines
+   * to handle similar operations and hardcodes the initial meta tasks and routines.
+   *
+   * It initializes the instance state by setting up tasks and routines.
+   */
   constructor() {
     this.tasks = /* @__PURE__ */ new Map();
     this.routines = /* @__PURE__ */ new Map();
@@ -2460,12 +3030,14 @@ var GraphRunner = class extends SignalEmitter {
     );
   }
   /**
-   * 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.
+   * Adds tasks or routines to the current execution pipeline. Supports both individual tasks,
+   * routines, or arrays of tasks and routines. Handles metadata and execution context management.
+   *
+   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} tasks - The task(s) or routine(s) to be added.
+   * It can be a single task, a single routine, or an array of tasks and routines.
+   * @param {AnyObject} [context={}] - Optional context object to provide execution trace and metadata.
+   * Used to propagate information across task or routine executions.
+   * @return {void} - This method does not return a value.
    */
   addTasks(tasks, context = {}) {
     let _tasks = Array.isArray(tasks) ? tasks : [tasks];
@@ -2490,9 +3062,9 @@ var GraphRunner = class extends SignalEmitter {
     const isSubMeta = allTasks.some((t) => t.isSubMeta) || !!context.__isSubMeta;
     context.__isSubMeta = isSubMeta;
     const isNewTrace = !context.__routineExecId && !context.__metadata?.__executionTraceId && !context.__executionTraceId;
-    const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? (0, import_uuid4.v4)();
+    const executionTraceId = context.__metadata?.__executionTraceId ?? context.__executionTraceId ?? (0, import_uuid5.v4)();
     context.__executionTraceId = executionTraceId;
-    const routineExecId = context.__routineExecId ?? (0, import_uuid4.v4)();
+    const routineExecId = context.__routineExecId ?? (0, import_uuid5.v4)();
     context.__routineExecId = routineExecId;
     const ctx = new GraphContext(context || {});
     if (!isSubMeta) {
@@ -2538,11 +3110,12 @@ var GraphRunner = class extends SignalEmitter {
     );
   }
   /**
-   * 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.
+   * Executes the provided tasks or routines. Maintains the execution state
+   * and handles synchronous or asynchronous processing.
+   *
+   * @param {Task|GraphRoutine|(Task|GraphRoutine)[]} [tasks] - A single task, a single routine, or an array of tasks or routines to execute. Optional.
+   * @param {AnyObject} [context] - An optional context object to be used during task execution.
+   * @return {GraphRun|Promise<GraphRun>} - Returns a `GraphRun` instance if the execution is synchronous, or a `Promise` resolving to a `GraphRun` for asynchronous execution.
    */
   run(tasks, context) {
     if (tasks) {
@@ -2560,10 +3133,23 @@ var GraphRunner = class extends SignalEmitter {
     }
     return this.reset();
   }
+  /**
+   * Executes the provided asynchronous operation and resets the state afterwards.
+   *
+   * @param {Promise<void>} run - A promise representing the asynchronous operation to execute.
+   * @return {Promise<GraphRun>} A promise that resolves to the result of the reset operation after the asynchronous operation completes.
+   */
   async runAsync(run) {
     await run;
     return this.reset();
   }
+  /**
+   * Resets the current state of the graph, creating a new GraphRun instance
+   * and returning the previous run instance.
+   * If the debug mode is not enabled, it will destroy the existing resources.
+   *
+   * @return {GraphRun} The last GraphRun instance before the reset.
+   */
   reset() {
     this.isRunning = false;
     const lastRun = this.currentRun;
@@ -2582,6 +3168,13 @@ var GraphRunner = class extends SignalEmitter {
   destroy() {
     this.currentRun.destroy();
   }
+  /**
+   * Sets the strategy to be used for running the graph and initializes
+   * the current run with the provided strategy if no process is currently running.
+   *
+   * @param {GraphRunStrategy} strategy - The strategy to use for running the graph.
+   * @return {void}
+   */
   setStrategy(strategy) {
     this.strategy = strategy;
     if (!this.isRunning) {
@@ -2641,6 +3234,14 @@ var DebounceTask = class extends Task {
     this.trailing = trailing;
     this.maxWait = maxWait;
   }
+  /**
+   * Executes the taskFunction with the provided context, emit function, and progress callback.
+   * It clears any existing timeout before execution.
+   * Handles synchronous and asynchronous results from taskFunction.
+   * If an error occurs during execution, it resolves with the error.
+   *
+   * @return {void} This method does not return any value.
+   */
   executeFunction() {
     if (this.lastTimeout) {
       clearTimeout(this.lastTimeout);
@@ -2666,6 +3267,19 @@ var DebounceTask = class extends Task {
       }
     }
   }
+  /**
+   * Executes a debounced operation, ensuring controlled execution of functions
+   * over a specified debounce time and maximum wait time. This method handles
+   * both leading and trailing edge executions and invokes callbacks accordingly.
+   *
+   * @param {Function} resolve - The function to call when the operation is successfully resolved.
+   * @param {Function} reject - The function to call with an error or reason if the operation fails.
+   * @param {GraphContext} context - The execution context for the operation.
+   * @param {NodeJS.Timeout} timeout - A timeout object for managing execution delays.
+   * @param {Function} emit - A callback function to emit signals with a specific context.
+   * @param {Function} progressCallback - A callback function to report progress during operation execution.
+   * @return {void} Does not return a value but sets internal timers and invokes provided callbacks.
+   */
   debouncedTrigger(resolve, reject, context, timeout, emit, progressCallback) {
     const callNow = this.leading && this.timer === null;
     const isNewBurst = this.timer === null;
@@ -2711,6 +3325,14 @@ var DebounceTask = class extends Task {
       }, this.maxWait);
     }
   }
+  /**
+   * Executes a task with a debounced trigger mechanism.
+   *
+   * @param {GraphContext} context - The context containing relevant graph data for the execution.
+   * @param {function(string, any): void} emit - A function used to emit signals with associated context.
+   * @param {function(number): void} progressCallback - A callback function to report the progress of the task as a number between 0 and 1.
+   * @return {Promise<TaskResult>} A promise that resolves with the task result upon completion or rejects on failure.
+   */
   execute(context, emit, progressCallback) {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
@@ -2756,6 +3378,15 @@ var EphemeralTask = class extends Task {
     this.once = once;
     this.condition = condition;
   }
+  /**
+   * Executes the process logic with the provided context, emit function, progress callback, and node data.
+   *
+   * @param {any} context - The execution context, carrying necessary parameters or states for the operation.
+   * @param {function(string, AnyObject): void} emit - A function to emit signals with a string identifier and associated context.
+   * @param {function(number): void} progressCallback - A callback function to report the progress of the execution as a numerical value.
+   * @param {{ nodeId: string, routineExecId: string }} nodeData - An object containing details about the node ID and routine execution ID.
+   * @return {any} The result of the execution, returned from the base implementation or processed internally.
+   */
   execute(context, emit, progressCallback, nodeData) {
     const result = super.execute(context, emit, progressCallback, nodeData);
     if (this.once || this.condition(result)) {
@@ -2849,26 +3480,56 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     this.debug = false;
     this.index = index;
   }
+  /**
+   * Sets the debug mode for the current instance and all associated nodes.
+   *
+   * @param {boolean} value - A boolean value to enable (true) or disable (false) debug mode.
+   * @return {void} No return value.
+   */
   setDebug(value) {
     this.debug = value;
     for (const node of this.nodes) {
       node.setDebug(value);
     }
   }
+  /**
+   * Checks if the current layer has a preceding layer.
+   *
+   * @return {boolean} True if the current layer has a preceding layer that is an instance of GraphLayer; otherwise, false.
+   */
   get hasPreceding() {
     return !!this.previous && this.previous instanceof _GraphLayer;
   }
   getNumberOfNodes() {
     return this.nodes.length;
   }
+  /**
+   * Retrieves a list of nodes that match the given routine execution ID.
+   *
+   * @param {string} routineExecId - The ID of the routine execution to filter nodes by.
+   * @return {Array} An array of nodes that have the specified routine execution ID.
+   */
   getNodesByRoutineExecId(routineExecId) {
     return this.nodes.filter((node) => node.routineExecId === routineExecId);
   }
+  /**
+   * Finds and returns all nodes in the graph that are identical to the given node.
+   * Two nodes are considered identical if they share the same routine execution ID
+   * and share a task with each other.
+   *
+   * @param {GraphNode} node - The reference node to compare against other nodes in the graph.
+   * @return {GraphNode[]} An array of nodes that are identical to the given node.
+   */
   getIdenticalNodes(node) {
     return this.nodes.filter(
       (n) => node.routineExecId === n.routineExecId && node.sharesTaskWith(n)
     );
   }
+  /**
+   * Checks whether all nodes in the collection have been processed.
+   *
+   * @return {boolean} Returns true if all nodes are processed, otherwise false.
+   */
   isProcessed() {
     for (const node of this.nodes) {
       if (!node.isProcessed()) {
@@ -2877,6 +3538,11 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     }
     return true;
   }
+  /**
+   * Checks whether all layers in the graph have been processed.
+   *
+   * @return {boolean} Returns true if all graph layers are processed; otherwise, returns false.
+   */
   graphDone() {
     let done = true;
     let layer = this;
@@ -2889,6 +3555,13 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     }
     return done;
   }
+  /**
+   * Sets the next GraphLayer in the sequence if it has a higher index than the current layer.
+   * Updates the previous property if the given next layer has an existing previous layer.
+   *
+   * @param {GraphLayer} next - The next GraphLayer to be linked in the sequence.
+   * @return {void} Does not return a value. Modifies the current layer's state.
+   */
   setNext(next) {
     if (next.index <= this.index) {
       return;
@@ -2898,15 +3571,32 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     }
     super.setNext(next);
   }
+  /**
+   * Adds a node to the graph.
+   *
+   * @param {GraphNode} node - The node to be added to the graph.
+   * @return {void}
+   */
   add(node) {
     this.nodes.push(node);
   }
+  /**
+   * Starts the execution timer if it has not been started already.
+   * Records the current timestamp as the start time.
+   *
+   * @return {number} The timestamp representing the start time in milliseconds.
+   */
   start() {
     if (!this.executionStart) {
       this.executionStart = Date.now();
     }
     return this.executionStart;
   }
+  /**
+   * Marks the end of a process by capturing the current timestamp and calculating the execution time if a start time exists.
+   *
+   * @return {number} The timestamp at which the process ended, or 0 if the start time is not defined.
+   */
   end() {
     if (!this.executionStart) {
       return 0;
@@ -2915,6 +3605,14 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     this.executionTime = end - this.executionStart;
     return end;
   }
+  /**
+   * Destroys the current graph layer and its associated resources.
+   * This method recursively destroys all nodes in the current layer, clears the node list,
+   * and ensures that any connected subsequent graph layers are also destroyed.
+   * Additionally, it calls the decoupling logic to disconnect the current layer from its dependencies.
+   *
+   * @return {void} Does not return any value.
+   */
   destroy() {
     for (const node of this.nodes) {
       node.destroy();
@@ -2926,9 +3624,20 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
     }
     this.decouple();
   }
+  /**
+   * Returns an iterator for traversing through the graph layers.
+   *
+   * @return {GraphLayerIterator} An instance of GraphLayerIterator to traverse graph layers.
+   */
   getIterator() {
     return new GraphLayerIterator(this);
   }
+  /**
+   * Accepts a visitor object to traverse or perform operations on the current graph layer and its nodes.
+   *
+   * @param {GraphVisitor} visitor - The visitor instance implementing the visitLayer and visitNode behavior.
+   * @return {void} Returns nothing.
+   */
   accept(visitor) {
     visitor.visitLayer(this);
     for (const node of this.nodes) {
@@ -2965,6 +3674,14 @@ var GraphLayer = class _GraphLayer extends ExecutionChain {
 
 // src/graph/execution/SyncGraphLayer.ts
 var SyncGraphLayer = class extends GraphLayer {
+  /**
+   * Executes the processing logic of the current set of graph nodes. Iterates through all
+   * nodes, skipping any that have already been processed, and executes their respective
+   * logic to generate new nodes. Asynchronous functions are not supported and will
+   * trigger an error log.
+   *
+   * @return {GraphNode[]} An array of newly generated graph nodes after executing the logic of each unprocessed node.
+   */
   execute() {
     this.start();
     const result = [];
@@ -2997,20 +3714,49 @@ var GraphBuilder = class {
   getResult() {
     return this.graph;
   }
+  /**
+   * Composes a series of functions or operations.
+   * This method should be implemented in the child class
+   * to define custom composition logic.
+   *
+   * @return {any} The result of the composed operations or functions
+   * when implemented in the child class.
+   */
   compose() {
     throw "Implement this in child class...";
   }
+  /**
+   * Adds a node to the appropriate layer of the graph.
+   *
+   * @param {GraphNode} node - The node to be added to the graph. The node contains
+   *                           layer information that determines which layer it belongs to.
+   * @return {void} Does not return a value.
+   */
   addNode(node) {
     const index = node.getLayerIndex();
     this.addLayer(index);
     const layer = this.getLayer(index);
     node.scheduleOn(layer);
   }
+  /**
+   * Adds multiple nodes to the graph.
+   *
+   * @param {GraphNode[]} nodes - An array of nodes to be added to the graph.
+   * @return {void} This method does not return a value.
+   */
   addNodes(nodes) {
     for (const node of nodes) {
       this.addNode(node);
     }
   }
+  /**
+   * Adds a new layer to the graph at the specified index. If the graph does not exist,
+   * it creates the graph using the specified index. Updates the graph's top layer index
+   * and maintains the order of layers.
+   *
+   * @param {number} index - The index at which the new layer should be added to the graph.
+   * @return {void} This method does not return a value.
+   */
   addLayer(index) {
     if (!this.graph) {
       const layer = this.createLayer(index);
@@ -3037,11 +3783,23 @@ var GraphBuilder = class {
       this.addLayer(index);
     }
   }
+  /**
+   * Creates a new layer for the graph at the specified index.
+   *
+   * @param {number} index - The index of the layer to be created.
+   * @return {GraphLayer} A new instance of the graph layer corresponding to the provided index.
+   */
   createLayer(index) {
     const layer = new SyncGraphLayer(index);
     layer.setDebug(this.debug);
     return layer;
   }
+  /**
+   * Retrieves a specific layer from the current set of layers.
+   *
+   * @param {number} layerIndex - The index of the layer to retrieve.
+   * @return {*} The layer corresponding to the given index.
+   */
   getLayer(layerIndex) {
     return this.layers[layerIndex - this.topLayerIndex];
   }
@@ -3054,6 +3812,12 @@ var GraphBuilder = class {
 
 // src/engine/builders/GraphBreadthFirstBuilder.ts
 var GraphBreadthFirstBuilder = class extends GraphBuilder {
+  /**
+   * Composes layers of a graph by iterating through them, executing their logic,
+   * and adding the resulting nodes to the current graph.
+   *
+   * @return {void} This method does not return a value.
+   */
   compose() {
     if (!this.graph) {
       return;
@@ -3109,6 +3873,15 @@ var ThrottleEngine = class _ThrottleEngine {
   setConcurrencyLimit(tag, limit) {
     this.maxConcurrencyPerTag[tag] = limit;
   }
+  /**
+   * Manages the execution of a function `fn` applied on a specified node `node` with controlled concurrency for a given tag.
+   * The method ensures that processes are executed in a throttled manner, respecting the maximum concurrency for each tag.
+   *
+   * @param {ProcessFunction} fn - The function to be executed on the provided node.
+   * @param {GraphNode} node - The graph node on which the function `fn` will be applied.
+   * @param {string} [tag="default"] - The concurrency grouping tag used to control and group the throttling behavior.
+   * @return {Promise<GraphNode[]>} A promise resolving to an array of GraphNode objects once the throttled function execution completes.
+   */
   throttle(fn, node, tag = "default") {
     var _a, _b;
     const functionPromise = new Promise((resolve) => {
@@ -3120,6 +3893,12 @@ var ThrottleEngine = class _ThrottleEngine {
     this.processQueue(tag);
     return functionPromise;
   }
+  /**
+   * Processes the tasks in the queue for a given tag while respecting concurrency limits.
+   *
+   * @param {string} tag - The identifier for the queue to be processed, used to group tasks and manage concurrency controls.
+   * @return {void} Does not return a value; it processes tasks asynchronously and manages state internally.
+   */
   processQueue(tag) {
     const maxAllowed = this.maxConcurrencyPerTag[tag];
     while ((this.queues[tag]?.length ?? 0) > 0 && (this.runningCounts[tag] ?? 0) < maxAllowed) {
@@ -3135,6 +3914,14 @@ var ThrottleEngine = class _ThrottleEngine {
       delete this.runningCounts[tag];
     }
   }
+  /**
+   * Processes a given item consisting of a function and a graph node.
+   *
+   * @param {Array} item - An array where the first element is a processing function and the second element is a graph node.
+   * @param {Function} item[0] - The function to process the graph node.
+   * @param {GraphNode} item[1] - The graph node to be processed.
+   * @return {Promise<void>} A promise that resolves when the processing and cleanup are complete.
+   */
   async process(item) {
     const fn = item[0];
     const node = item[1];
@@ -3151,10 +3938,24 @@ var AsyncGraphLayer = class extends GraphLayer {
     this.waitingNodes = [];
     this.processingNodes = /* @__PURE__ */ new Set();
   }
+  /**
+   * Adds a node to the graph and tracks it as a waiting node.
+   *
+   * @param {GraphNode} node - The graph node to be added.
+   * @return {void}
+   */
   add(node) {
     this.nodes.push(node);
     this.waitingNodes.push(node);
   }
+  /**
+   * Executes the processing of nodes by iterating over the queued `waitingNodes`,
+   * processing each node, and managing concurrency limits where applicable.
+   * The method returns a mapping of routine execution IDs to arrays of processed nodes or promises.
+   *
+   * @return {Object} An object where the keys are routine execution IDs and the values
+   * represent arrays of processed nodes or promises resolving to processed nodes.
+   */
   execute() {
     var _a;
     if (this.waitingNodes.length === 0) {
@@ -3188,6 +3989,13 @@ var AsyncGraphLayer = class extends GraphLayer {
     }
     return result;
   }
+  /**
+   * Processes the given graph node, executes its logic, and handles synchronous or asynchronous outcomes.
+   *
+   * @param {GraphNode} node - The graph node to be processed.
+   * @return {Promise<GraphNode[]> | GraphNode[]} A promise that resolves to an array of next graph nodes if asynchronous,
+   * or an array of next graph nodes if synchronous.
+   */
   processNode(node) {
     node.start();
     const nextNodes = node.execute();
@@ -3197,11 +4005,23 @@ var AsyncGraphLayer = class extends GraphLayer {
     this.processingNodes.delete(node);
     return nextNodes;
   }
+  /**
+   * Processes the given graph node asynchronously and removes it from the processing nodes set.
+   *
+   * @param {GraphNode} node - The current graph node being processed.
+   * @param {Promise<GraphNode[]>} nextNodes - A promise that resolves to an array of the next graph nodes to process.
+   * @return {Promise<GraphNode[]>} A promise that resolves to an array of the next graph nodes.
+   */
   async processAsync(node, nextNodes) {
     const result = await nextNodes;
     this.processingNodes.delete(node);
     return result;
   }
+  /**
+   * Cleans up resources used by the instance by resetting relevant properties and invoking the parent class's destroy method.
+   *
+   * @return {void} No value is returned as the method performs cleanup operations.
+   */
   destroy() {
     super.destroy();
     this.waitingNodes = [];
@@ -3211,6 +4031,14 @@ var AsyncGraphLayer = class extends GraphLayer {
 
 // src/engine/builders/GraphAsyncQueueBuilder.ts
 var GraphAsyncQueueBuilder = class extends GraphBuilder {
+  /**
+   * This method iterates over a graph structure and processes its layers sequentially.
+   * It continues processing each layer until all layers in the graph are completed.
+   * The asynchronous behavior ensures the operation provides breathing room for other
+   * tasks/processes to execute during its operation.
+   *
+   * @return {Promise<void>} A promise that resolves when all layers of the graph are processed or rejects if an error occurs.
+   */
   async compose() {
     if (!this.graph) {
       return;
@@ -3229,6 +4057,14 @@ var GraphAsyncQueueBuilder = class extends GraphBuilder {
       await sleep(0);
     }
   }
+  /**
+   * Processes a given asynchronous graph layer and executes its nodes.
+   * Handles promises within the nodes and adds the resolved or processed
+   * nodes to the graph.
+   *
+   * @param {AsyncGraphLayer} layer - The asynchronous graph layer to be processed.
+   * @return {void} - This method does not return a value.
+   */
   processLayer(layer) {
     const nextNodes = layer.execute();
     for (const routineExecId of Object.keys(nextNodes)) {
@@ -3242,6 +4078,13 @@ var GraphAsyncQueueBuilder = class extends GraphBuilder {
       }
     }
   }
+  /**
+   * Creates a new instance of AsyncGraphLayer, sets its debug configuration,
+   * and returns the created layer.
+   *
+   * @param {number} index - The index to associate with the new AsyncGraphLayer.
+   * @return {AsyncGraphLayer} A new instance of AsyncGraphLayer with the specified index and debug configuration.
+   */
   createLayer(index) {
     const layer = new AsyncGraphLayer(index);
     layer.setDebug(this.debug);
@@ -3255,6 +4098,12 @@ var GraphAsyncRun = class extends GraphRunStrategy {
     super();
     this.graphBuilder = new GraphAsyncQueueBuilder();
   }
+  /**
+   * Executes the run operation, which involves composing the graph builder,
+   * updating the run instance, and resetting the state.
+   *
+   * @return {Promise<void>} A promise that resolves when the operation completes.
+   */
   async run() {
     await this.graphBuilder.compose();
     this.updateRunInstance();
@@ -3270,6 +4119,12 @@ var GraphAsyncRun = class extends GraphRunStrategy {
 
 // src/engine/strategy/GraphStandardRun.ts
 var GraphStandardRun = class extends GraphRunStrategy {
+  /**
+   * Executes the sequence of operations involving graph composition,
+   * instance updating, and reset mechanisms.
+   *
+   * @return {void} Does not return a value.
+   */
   run() {
     this.graphBuilder.compose();
     this.updateRunInstance();
@@ -3282,6 +4137,13 @@ var GraphStandardRun = class extends GraphRunStrategy {
 
 // src/Cadenza.ts
 var Cadenza = class {
+  /**
+   * Initializes the system by setting up the required components such as the
+   * signal broker, runners, and graph registry. Ensures the initialization
+   * happens only once. Configures debug settings if applicable.
+   *
+   * @return {void} No value is returned.
+   */
   static bootstrap() {
     if (this.isBootstrapped) return;
     this.isBootstrapped = true;
@@ -3299,12 +4161,27 @@ var Cadenza = class {
     this.runner.init();
     this.metaRunner.init();
   }
+  /**
+   * Retrieves the available strategies for running graphs.
+   *
+   * @return {Object} An object containing the available run strategies, where:
+   *                  - PARALLEL: Executes graph runs asynchronously.
+   *                  - SEQUENTIAL: Executes graph runs in a sequential order.
+   */
   static get runStrategy() {
     return {
       PARALLEL: new GraphAsyncRun(),
       SEQUENTIAL: new GraphStandardRun()
     };
   }
+  /**
+   * Sets the mode for the application and configures the broker and runner settings accordingly.
+   *
+   * @param {CadenzaMode} mode - The mode to set. It can be one of the following:
+   *                             "debug", "dev", "verbose", or "production".
+   *                             Each mode adjusts debug and verbosity settings.
+   * @return {void} This method does not return a value.
+   */
   static setMode(mode) {
     this.mode = mode;
     this.bootstrap();
@@ -3326,29 +4203,129 @@ var Cadenza = class {
     }
   }
   /**
-   * Validates a name for uniqueness and non-emptiness.
-   * @param name The name to validate.
-   * @throws Error if invalid.
+   * Validates the given name to ensure it is a non-empty string.
+   * Throws an error if the validation fails.
+   *
+   * @param {string} name - The name to validate.
+   * @return {void} This method does not return anything.
+   * @throws {Error} If the name is not a non-empty string.
    */
   static validateName(name) {
     if (!name || typeof name !== "string") {
       throw new Error("Task or Routine name must be a non-empty string.");
     }
   }
+  /**
+   * Executes the specified task or GraphRoutine with the given context using an internal runner.
+   *
+   * @param {Task | GraphRoutine} task - The task or GraphRoutine to be executed.
+   * @param {AnyObject} context - The context in which the task or GraphRoutine should be executed.
+   * @return {void}
+   *
+   * @example
+   * ```ts
+   * const task = Cadenza.createTask('My task', (ctx) => {
+   *   console.log('My task executed with context:', ctx);
+   * });
+   *
+   * Cadenza.run(task, { foo: 'bar' });
+   *
+   * const routine = Cadenza.createRoutine('My routine', [task], 'My routine description');
+   *
+   * Cadenza.run(routine, { foo: 'bar' });
+   * ```
+   */
   static run(task, context) {
     this.runner?.run(task, context);
   }
+  /**
+   * Emits an event with the specified name and data payload to the broker.
+   *
+   * @param {string} event - The name of the event to emit.
+   * @param {AnyObject} [data={}] - The data payload associated with the event.
+   * @return {void} - No return value.
+   *
+   * @example
+   * This is meant to be used as a global event emitter.
+   * If you want to emit an event from within a task, you can use the `emit` method provided to the task function. See {@link TaskFunction}.
+   * ```ts
+   * Cadenza.emit('main.my_event', { foo: 'bar' });
+   * ```
+   */
   static emit(event, data = {}) {
     this.broker?.emit(event, data);
   }
   /**
-   * 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.
+   * Creates and registers a new task with the specified parameters and options.
+   * Tasks are the basic building blocks of Cadenza graphs and are responsible for executing logic.
+   * See {@link Task} for more information.
+   *
+   * @param {string} name - The unique name of the task.
+   * @param {TaskFunction} func - The function to be executed by the task.
+   * @param {string} [description] - An optional description for the task.
+   * @param {TaskOptions} [options={}] - Configuration options for the task, such as concurrency, timeout, and retry settings.
+   * @return {Task} The created task instance.
+   *
+   * @example
+   * You can use arrow functions to create tasks.
+   * ```ts
+   * const task = Cadenza.createTask('My task', (ctx) => {
+   *   console.log('My task executed with context:', ctx);
+   * }, 'My task description');
+   * ```
+   *
+   * You can also use named functions to create tasks.
+   * This is the preferred way to create tasks since it allows for code inspection in the CadenzaUI.
+   * ```ts
+   * function myTask(ctx) {
+   *   console.log('My task executed with context:', ctx);
+   * }
+   *
+   * const task = Cadenza.createTask('My task', myTask);
+   * ```
+   *
+   * ** Use the TaskOptions object to configure the task. **
+   *
+   * With concurrency limit, timeout limit and retry settings.
+   * ```ts
+   * Cadenza.createTask('My task', (ctx) => {
+   *   console.log('My task executed with context:', ctx);
+   * }, 'My task description', {
+   *   concurrency: 10,
+   *   timeout: 10000,
+   *   retryCount: 3,
+   *   retryDelay: 1000,
+   *   retryDelayFactor: 1.5,
+   * });
+   * ```
+   *
+   * You can specify the input and output context schemas for the task.
+   * ```ts
+   * Cadenza.createTask('My task', (ctx) => {
+   *   return { bar: 'foo' + ctx.foo };
+   * }, 'My task description', {
+   *   inputContextSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       foo: {
+   *         type: 'string',
+   *       },
+   *     },
+   *   required: ['foo'],
+   *   },
+   *   validateInputContext: true, // default is false
+   *   outputContextSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       bar: {
+   *         type: 'string',
+   *       },
+   *     },
+   *     required: ['bar'],
+   *   },
+   *   validateOutputContext: true, // default is false
+   * });
+   * ```
    */
   static createTask(name, func, description, options = {}) {
     this.bootstrap();
@@ -3395,40 +4372,82 @@ var Cadenza = class {
     );
   }
   /**
-   * 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.
+   * Creates a meta task with the specified name, functionality, description, and options.
+   * This is used for creating tasks that lives on the meta layer.
+   * The meta layer is a special layer that is executed separately from the business logic layer and is used for extending Cadenzas core functionality.
+   * See {@link Task} or {@link createTask} for more information.
+   *
+   * @param {string} name - The name of the meta task.
+   * @param {TaskFunction} func - The function to be executed by the meta task.
+   * @param {string} [description] - An optional description of the meta task.
+   * @param {TaskOptions} [options={}] - Additional optional task configuration. Automatically sets `isMeta` to true.
+   * @return {Task} A task instance configured as a meta task.
    */
   static createMetaTask(name, func, description, options = {}) {
     options.isMeta = true;
     return this.createTask(name, func, description, options);
   }
   /**
-   * 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.
+   * Creates a unique task by wrapping the provided task function with a uniqueness constraint.
+   * Unique tasks are designed to execute once per execution ID, merging parents. This is useful for
+   * tasks that require fan-in/joins after parallel branches.
+   * See {@link Task} for more information.
+   *
+   * @param {string} name - The name of the task to be created.
+   * @param {TaskFunction} func - The function that contains the logic for the task. It receives joinedContexts as a list in the context (context.joinedContexts).
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions} [options={}] - Optional configuration for the task, such as additional metadata or task options.
+   * @return {Task} The task instance that was created with a uniqueness constraint.
+   *
+   * @example
+   * ```ts
+   * const splitTask = Cadenza.createTask('Split foos', function* (ctx) {
+   *   for (const foo of ctx.foos) {
+   *     yield { foo };
+   *   }
+   * }, 'Splits a list of foos into multiple sub-branches');
+   *
+   * const processTask = Cadenza.createTask('Process foo', (ctx) => {
+   *  return { bar: 'foo' + ctx.foo };
+   * }, 'Process a foo');
+   *
+   * const uniqueTask = Cadenza.createUniqueTask('Gather processed foos', (ctx) => {
+   *   // A unique task will always be provided with a list of contexts (ctx.joinedContexts) from its predecessors.
+   *   const processedFoos = ctx.joinedContexts.map((c) => c.bar);
+   *   return { foos: processedFoos };
+   * }, 'Gathers together the processed foos.');
+   *
+   * splitTask.then(
+   *   processTask.then(
+   *     uniqueTask,
+   *   ),
+   * );
+   *
+   * // Give the flow a name using a routine
+   * Cadenza.createRoutine(
+   *   'Process foos',
+   *   [splitTask],
+   *   'Processes a list of foos'
+   * ).doOn('main.received_foos'); // Subscribe to a signal
+   *
+   * // Trigger the flow from anywhere
+   * Cadenza.emit('main.received_foos', { foos: ['foo1', 'foo2', 'foo3'] });
+   * ```
+   *
    */
   static createUniqueTask(name, func, description, options = {}) {
     options.isUnique = true;
     return this.createTask(name, func, description, options);
   }
   /**
-   * 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.
+   * Creates a unique meta task with the specified name, function, description, and options.
+   * See {@link createUniqueTask} and {@link createMetaTask} for more information.
+   *
+   * @param {string} name - The name of the task to create.
+   * @param {TaskFunction} func - The function to execute when the task is run.
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions} [options={}] - Optional settings for the task. Defaults to an empty object. Automatically sets `isMeta` and `isUnique` to true.
+   * @return {Task} The created unique meta task.
    */
   static createUniqueMetaTask(name, func, description, options = {}) {
     options.isMeta = true;
@@ -3436,14 +4455,33 @@ var Cadenza = class {
     return this.createUniqueTask(name, func, description, options);
   }
   /**
-   * 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.
+   * Creates a throttled task with a concurrency limit of 1, ensuring that only one instance of the task can run at a time for a specific throttle tag.
+   * This is useful for ensuring execution order and preventing race conditions.
+   * See {@link Task} for more information.
+   *
+   * @param {string} name - The name of the task.
+   * @param {TaskFunction} func - The function to be executed when the task runs.
+   * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function that generates a throttle tag identifier to group tasks for throttling.
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions} [options={}] - Additional options to customize the task behavior.
+   * @return {Task} The created throttled task.
+   *
+   * @example
+   * ```ts
+   * const task = Cadenza.createThrottledTask(
+   *   'My task',
+   *   async (ctx) => {
+   *      await new Promise((resolve) => setTimeout(resolve, 1000));
+   *      console.log('My task executed with context:', ctx);
+   *   },
+   *   // Will throttle by the value of ctx.foo to make sure tasks with the same value are executed sequentially
+   *   (ctx) => ctx.foo,
+   * );
+   *
+   * Cadenza.run(task, { foo: 'bar' }); // (First execution)
+   * Cadenza.run(task, { foo: 'bar' }); // This will be executed after the first execution is finished
+   * Cadenza.run(task, { foo: 'baz' }); // This will be executed in parallel with the first execution
+   * ```
    */
   static createThrottledTask(name, func, throttledIdGetter = () => "default", description, options = {}) {
     options.concurrency = 1;
@@ -3451,13 +4489,15 @@ var Cadenza = class {
     return this.createTask(name, func, description, options);
   }
   /**
-   * 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.
+   * Creates a throttled meta task with the specified configuration.
+   * See {@link createThrottledTask} and {@link createMetaTask} for more information.
+   *
+   * @param {string} name - The name of the throttled meta task.
+   * @param {TaskFunction} func - The task function to be executed.
+   * @param {ThrottleTagGetter} throttledIdGetter - A function to retrieve the throttling identifier.
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions} [options={}] - Additional options for configuring the task.
+   * @return {Task} The created throttled meta task.
    */
   static createThrottledMetaTask(name, func, throttledIdGetter, description, options = {}) {
     options.isMeta = true;
@@ -3470,14 +4510,37 @@ var Cadenza = class {
     );
   }
   /**
-   * 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.
+   * Creates and returns a new debounced task with the specified parameters.
+   * This is useful to prevent rapid execution of tasks that may be triggered by multiple events within a certain time frame.
+   * See {@link DebounceTask} for more information.
+   *
+   * @param {string} name - The unique name of the task to be created.
+   * @param {TaskFunction} func - The function to be executed by the task.
+   * @param {string} [description] - An optional description of the task.
+   * @param {number} [debounceTime=1000] - The debounce time in milliseconds to delay the execution of the task.
+   * @param {TaskOptions & DebounceOptions} [options={}] - Additional configuration options for the task, including debounce behavior and other task properties.
+   * @return {DebounceTask} A new instance of the DebounceTask with the specified configuration.
+   *
+   * @example
+   * ```ts
+   * const task = Cadenza.createDebounceTask(
+   *   'My debounced task',
+   *   (ctx) => {
+   *      console.log('My task executed with context:', ctx);
+   *   },
+   *   'My debounced task description',
+   *   100, // Debounce time in milliseconds. Default is 1000
+   *   {
+   *     leading: false, // Should the first execution of a burst be executed immediately? Default is false
+   *     trailing: true, // Should the last execution of a burst be executed? Default is true
+   *     maxWait: 1000, // Maximum time in milliseconds to wait for the next execution. Default is 0
+   *   },
+   * );
+   *
+   * Cadenza.run(task, { foo: 'bar' }); // This will not be executed
+   * Cadenza.run(task, { foo: 'bar' }); // This will not be executed
+   * Cadenza.run(task, { foo: 'baz' }); // This execution will be delayed by 100ms
+   * ```
    */
   static createDebounceTask(name, func, description, debounceTime = 1e3, options = {}) {
     this.bootstrap();
@@ -3521,13 +4584,15 @@ var Cadenza = class {
     );
   }
   /**
-   * 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.
+   * Creates a debounced meta task with the specified parameters.
+   * See {@link createDebounceTask} and {@link createMetaTask} for more information.
+   *
+   * @param {string} name - The name of the task.
+   * @param {TaskFunction} func - The function to be executed by the task.
+   * @param {string} [description] - Optional description of the task.
+   * @param {number} [debounceTime=1000] - The debounce delay in milliseconds.
+   * @param {TaskOptions & DebounceOptions} [options={}] - Additional configuration options for the task.
+   * @return {DebounceTask} Returns an instance of the debounced meta task.
    */
   static createDebounceMetaTask(name, func, description, debounceTime = 1e3, options = {}) {
     options.isMeta = true;
@@ -3540,14 +4605,64 @@ var Cadenza = class {
     );
   }
   /**
-   * 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 options Optional task options plus optional "once" (true) and "destroyCondition" (ctx => boolean).
-   * @returns The created EphemeralTask.
-   * @edge Destruction triggered post-exec via Node/Builder; emits meta-signal for cleanup.
+   * Creates an ephemeral task with the specified configuration.
+   * Ephemeral tasks are designed to self-destruct after execution or a certain condition is met.
+   * This is useful for transient tasks such as resolving promises or performing cleanup operations.
+   * They are not registered by default.
+   * See {@link EphemeralTask} for more information.
+   *
+   * @param {string} name - The name of the task to be created.
+   * @param {TaskFunction} func - The function that defines the logic of the task.
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions & EphemeralTaskOptions} [options={}] - The configuration options for the task, including concurrency, timeouts, and retry policies.
+   * @return {EphemeralTask} The created ephemeral task instance.
+   *
+   * @example
+   * By default, ephemeral tasks are executed once and destroyed after execution.
+   * ```ts
+   * const task = Cadenza.createEphemeralTask('My ephemeral task', (ctx) => {
+   *   console.log('My task executed with context:', ctx);
+   * });
+   *
+   * Cadenza.run(task); // Executes the task once and destroys it after execution
+   * Cadenza.run(task); // Does nothing, since the task is destroyed
+   * ```
+   *
+   * Use destroy condition to conditionally destroy the task
+   * ```ts
+   * const task = Cadenza.createEphemeralTask(
+   *   'My ephemeral task',
+   *   (ctx) => {
+   *      console.log('My task executed with context:', ctx);
+   *   },
+   *   'My ephemeral task description',
+   *   {
+   *     once: false, // Should the task be executed only once? Default is true
+   *     destroyCondition: (ctx) => ctx.foo > 10, // Should the task be destroyed after execution? Default is undefined
+   *   },
+   * );
+   *
+   * Cadenza.run(task, { foo: 5 }); // The task will not be destroyed and can still be executed
+   * Cadenza.run(task, { foo: 10 }); // The task will not be destroyed and can still be executed
+   * Cadenza.run(task, { foo: 20 }); // The task will be destroyed after execution and cannot be executed anymore
+   * Cadenza.run(task, { foo: 30 }); // This will not be executed
+   * ```
+   *
+   * A practical use case for ephemeral tasks is to resolve a promise upon some external event.
+   * ```ts
+   * const task = Cadenza.createTask('Confirm something', (ctx, emit) => {
+   *   return new Promise((resolve) => {
+   *     ctx.foo = uuid();
+   *
+   *     Cadenza.createEphemeralTask(`Resolve promise of ${ctx.foo}`, (c) => {
+   *       console.log('My task executed with context:', ctx);
+   *       resolve(c);
+   *     }).doOn(`socket.confirmation_received:${ctx.foo}`);
+   *
+   *     emit('this_domain.confirmation_requested', ctx);
+   *   });
+   * });
+   * ```
    */
   static createEphemeralTask(name, func, description, options = {}) {
     this.bootstrap();
@@ -3598,45 +4713,72 @@ var Cadenza = class {
     );
   }
   /**
-   * Creates an EphemeralMetaTask for meta-layer transients.
-   * @param name Identifier.
-   * @param func Function.
-   * @param description Optional.
-   * @param options Optional task options plus optional "once" (true) and "destroyCondition" (ctx => boolean).
-   * @returns The created EphemeralMetaTask.
+   * Creates an ephemeral meta task with the specified name, function, description, and options.
+   * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
+   *
+   * @param {string} name - The name of the task to be created.
+   * @param {TaskFunction} func - The function to be executed as part of the task.
+   * @param {string} [description] - An optional description of the task.
+   * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
+   * @return {EphemeralTask} The created ephemeral meta task.
    */
   static createEphemeralMetaTask(name, func, description, options = {}) {
     options.isMeta = true;
     return this.createEphemeralTask(name, func, description, options);
   }
   /**
-   * 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.
+   * Creates a new routine with the specified name, tasks, and an optional description.
+   * Routines are named entry points to starting tasks and are registered in the GraphRegistry.
+   * They are used to group tasks together and provide a high-level structure for organizing and managing the execution of a set of tasks.
+   * See {@link GraphRoutine} for more information.
+   *
+   * @param {string} name - The name of the routine to create.
+   * @param {Task[]} tasks - A list of tasks to include in the routine.
+   * @param {string} [description=""] - An optional description for the routine.
+   * @return {GraphRoutine} A new instance of the GraphRoutine containing the specified tasks and description.
+   *
+   * @example
+   * ```ts
+   * const task1 = Cadenza.createTask("Task 1", () => {});
+   * const task2 = Cadenza.createTask("Task 2", () => {});
+   *
+   * task1.then(task2);
+   *
+   * const routine = Cadenza.createRoutine("Some routine", [task1]);
+   *
+   * Cadenza.run(routine);
+   *
+   * // Or, routines can be triggered by signals
+   * routine.doOn("some.signal");
+   *
+   * Cadenza.emit("some.signal", {});
+   * ```
    */
   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).`);
+      throw new Error(`Routine '${name}' created with no starting tasks.`);
     }
     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.
+   * Creates a meta routine with a given name, tasks, and optional description.
+   * Routines are named entry points to starting tasks and are registered in the GraphRegistry.
+   * They are used to group tasks together and provide a high-level structure for organizing and managing the execution of a set of tasks.
+   * See {@link GraphRoutine} and {@link createRoutine} for more information.
+   *
+   * @param {string} name - The name of the routine to be created.
+   * @param {Task[]} tasks - An array of tasks that the routine will consist of.
+   * @param {string} [description=""] - An optional description for the routine.
+   * @return {GraphRoutine} A new instance of the `GraphRoutine` representing the created routine.
+   * @throws {Error} If no starting tasks are provided.
    */
   static createMetaRoutine(name, tasks, description = "") {
     this.bootstrap();
     this.validateName(name);
     if (tasks.length === 0) {
-      console.warn(`Routine '${name}' created with no starting tasks (no-op).`);
+      throw new Error(`Routine '${name}' created with no starting tasks.`);
     }
     return new GraphRoutine(name, tasks, description, true);
   }