@cadenza.io/service 1.24.1 → 1.24.3

package/dist/index.d.mts

@@ -2,46 +2,51 @@ import * as _cadenza_io_core from '@cadenza.io/core';
 import { Task, ThrottleTagGetter, SchemaDefinition as SchemaDefinition$1, GraphContext, AnyObject, TaskResult, SignalBroker, GraphRunner, GraphRegistry, CadenzaMode, GraphRoutine, TaskOptions, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
 export { AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
 
+/**
+ * Represents a task that delegates execution of a routine to a remote system or service.
+ * The `DeputyTask` serves as a proxy to perform and track the progress of a remote workflow.
+ * It extends the `Task` class with additional delegation capabilities.
+ *
+ * Emits various meta-signals for monitoring delegation progress and resolution.
+ */
 declare class DeputyTask extends Task {
     readonly isDeputy: boolean;
     protected readonly remoteRoutineName: string;
     protected serviceName: string | undefined;
     /**
-     * Constructs a DeputyTask as a proxy for triggering a remote flow.
-     * @param name - The local name of the DeputyTask.
-     * @param remoteRoutineName - The name of the remote routine or task to trigger.
-     * @param serviceName - The target service name (optional, defaults to local service if undefined).
-     * @param description - A description of the task's purpose (default: '').
-     * @param concurrency - The maximum number of concurrent executions (default: 0, unlimited).
-     * @param timeout - Timeout in milliseconds (default: 0, handled by engine).
-     * @param register - Whether to register the task in the registry (default: true).
-     * @param isUnique - Whether to create a unique task (default: false). A unique task will only be executed once per execution ID, merging parents.
-     * @param isMeta - Whether to create a meta task (default: false). A meta task is separate from the user logic and is only used for monitoring, optimization, and feature extensions.
-     * @param isSubMeta
-     * @param isHidden
-     * @param getTagCallback - Callback for dynamic tagging, e.g., 'return "default"'.
-     * @param inputSchema - Input schema definition.
-     * @param validateInputContext - Whether to validate the input context (default: false).
-     * @param outputSchema - Output schema definition.
-     * @param validateOutputContext - Whether to validate the output context (default: false).
-     * @param retryCount
-     * @param retryDelay
-     * @param retryDelayMax
-     * @param retryDelayFactor
-     * @emits {meta.deputy.delegation_requested} - Emitted on construction with task and service details.
-     * @note Fallbacks should be handled externally via `.doOnFail`; timeouts are managed by the engine.
+     * Constructs a new instance of the class with the specified parameters.
+     *
+     * @param {string} name - The name of the task.
+     * @param {string} remoteRoutineName - The name of the remote routine to delegate tasks to.
+     * @param {string | undefined} [serviceName=undefined] - The name of the service associated with the task.
+     * @param {string} [description=""] - A brief description of the task.
+     * @param {number} [concurrency=0] - The concurrency level of the task.
+     * @param {number} [timeout=0] - The timeout duration for the task.
+     * @param {boolean} [register=true] - Whether the task should be registered in the system.
+     * @param {boolean} [isUnique=false] - Whether the task is unique.
+     * @param {boolean} [isMeta=false] - Whether the task is a meta task.
+     * @param {boolean} [isSubMeta=false] - Whether the task is a sub-meta task.
+     * @param {boolean} [isHidden=false] - Whether the task is hidden from the system.
+     * @param {ThrottleTagGetter | undefined} [getTagCallback=undefined] - A callback function to retrieve throttle tags.
+     * @param {SchemaDefinition | undefined} [inputSchema=undefined] - The input schema definition for the task.
+     * @param {boolean} [validateInputContext=false] - Whether to validate the input context against the input schema.
+     * @param {SchemaDefinition | undefined} [outputSchema=undefined] - The output schema definition for the task.
+     * @param {boolean} [validateOutputContext=false] - Whether to validate the output context against the output schema.
+     * @param {number} [retryCount=0] - The number of retries allowed for task execution.
+     * @param {number} [retryDelay=0] - The initial delay between retries in milliseconds.
+     * @param {number} [retryDelayMax=0] - The maximum retry delay in milliseconds.
+     * @param {number} [retryDelayFactor=1] - The factor by which to increase the retry delay for subsequent retries.
+     * @return {void} This constructor does not return a value.
      */
     constructor(name: string, remoteRoutineName: string, serviceName?: string | undefined, description?: string, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, isSubMeta?: boolean, isHidden?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition$1 | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition$1 | undefined, validateOutputContext?: boolean, retryCount?: number, retryDelay?: number, retryDelayMax?: number, retryDelayFactor?: number);
     /**
-     * Triggers the delegation flow via a signal to the meta-layer.
-     * @param context - The GraphContext containing execution data.
-     * @param emit
-     * @param progressCallback - Callback to update progress (invoked by meta-layer).
-     * @param nodeData
-     * @returns A Promise resolving with the task result or rejecting on error.
-     * @emits {meta.deputy.executed} - Emitted with context to initiate delegation.
-     * @edge Engine handles timeout and error, triggering `.doOnFail` if chained.
-     * @note The resolution and progress are managed by ephemeral meta-tasks.
+     * Executes the specified task function within the provided execution context.
+     *
+     * @param {GraphContext} context - The execution context containing methods and metadata for task execution.
+     * @param {function(string, AnyObject): void} emit - A function for emitting signals with associated data during execution.
+     * @param {function(number): void} progressCallback - A callback function to report progress updates during task processing.
+     * @param {{ nodeId: string, routineExecId: string }} nodeData - Object containing identifiers for the node and routine execution.
+     * @return {TaskResult} Returns the result of the task function execution.
      */
     execute(context: GraphContext, emit: (signal: string, ctx: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
         nodeId: string;
@@ -96,45 +101,48 @@ interface DbOperationPayload {
     }>;
 }
 
+/**
+ * Represents a specialized task for delegating database operations. Extends `DeputyTask`.
+ * This class is designed to abstract database operation requests, delegating execution to a meta-layer system.
+ */
 declare class DatabaseTask extends DeputyTask {
     private readonly queryData;
     /**
-     * Constructs a DatabaseTask to execute a database operation on a remote service.
-     * @param name - The local name of the DatabaseTask.
-     * @param taskName - The name of the database operation task to trigger (e.g., 'dbQueryTaskExecution').
-     * @param serviceName - The target database service name (optional, defaults to 'DatabaseService').
-     * @param description - A description of the task's purpose (default: '').
-     * @param queryData - The query data object containing operation details (e.g., { __operation: 'query', __table: 'users' }).
-     * @param concurrency - The maximum number of concurrent executions (default: 0, unlimited).
-     * @param timeout - Timeout in milliseconds (default: 0, handled by engine).
-     * @param register - Whether to register the task in the registry (default: true).
-     * @param isUnique
-     * @param isMeta
-     * @param isSubMeta
-     * @param isHidden
-     * @param getTagCallback - Callback for dynamic tagging, e.g., 'return "default"'.
-     * @param inputSchema - Input schema definition.
-     * @param validateInputContext - Whether to validate the input context (default: false).
-     * @param outputSchema - Output schema definition.
-     * @param validateOutputContext - Whether to validate the output context (default: false).
-     * @param retryCount
-     * @param retryDelay
-     * @param retryDelayMax
-     * @param retryDelayFactor
-     * @emits {meta.deputy.created} - Emitted on construction with task and service details.
-     * @note Fallbacks via `.doOnFail` externally; timeouts managed by the engine.
+     * Constructs an instance of the class with the provided parameters, defining
+     * various configuration options and behaviors for the task.
+     *
+     * @param {string} name - The unique name of the task.
+     * @param {string} taskName - The specific name of the task.
+     * @param {string | undefined} serviceName - The associated service name. Defaults to undefined.
+     * @param {string} description - A brief description of the task. Defaults to an empty string.
+     * @param {DbOperationPayload} queryData - The data payload for database operations.
+     * @param {number} concurrency - The level of concurrency allowed. Defaults to 0.
+     * @param {number} timeout - The timeout duration in milliseconds. Defaults to 0.
+     * @param {boolean} register - A flag indicating whether to register the task. Defaults to true.
+     * @param {boolean} isUnique - Indicates if the task instance is unique. Defaults to false.
+     * @param {boolean} isMeta - Indicates if the task is meta. Defaults to false.
+     * @param {boolean} isSubMeta - Indicates if the task is a sub-meta task. Defaults to false.
+     * @param {boolean} isHidden - Indicates if the task is hidden. Defaults to false.
+     * @param {ThrottleTagGetter | undefined} getTagCallback - A callback used for throttling. Defaults to undefined.
+     * @param {SchemaDefinition | undefined} inputSchema - The schema definition for input validation. Defaults to undefined.
+     * @param {boolean} validateInputContext - Whether to validate the input context. Defaults to false.
+     * @param {SchemaDefinition | undefined} outputSchema - The schema definition for output validation. Defaults to undefined.
+     * @param {boolean} validateOutputContext - Whether to validate the output context. Defaults to false.
+     * @param {number} retryCount - The maximum number of retry attempts. Defaults to 0.
+     * @param {number} retryDelay - The delay between retries in milliseconds. Defaults to 0.
+     * @param {number} retryDelayMax - The maximum delay between retries in milliseconds. Defaults to 0.
+     * @param {number} retryDelayFactor - The factor for exponential backoff. Defaults to 1.
+     * @return {void}
      */
     constructor(name: string, taskName: string, serviceName: string | undefined, description: string | undefined, queryData: DbOperationPayload, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, isSubMeta?: boolean, isHidden?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition$1 | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition$1 | undefined, validateOutputContext?: boolean, retryCount?: number, retryDelay?: number, retryDelayMax?: number, retryDelayFactor?: number);
     /**
-     * Triggers the database operation delegation flow via a signal to the meta-layer.
-     * @param context - The GraphContext containing execution data.
-     * @param emit
-     * @param progressCallback - Callback to update progress (invoked by meta-layer).
-     * @param nodeData
-     * @returns A Promise resolving with the task result or rejecting on error.
-     * @emits {meta.deputy.executed} - Emitted with context including queryData to initiate delegation.
-     * @edge Engine handles timeout and error, triggering `.doOnFail` if chained.
-     * @note The resolution and progress are managed by ephemeral meta-tasks.
+     * Executes the specified task within the given context.
+     *
+     * @param {GraphContext} context - The execution context for the current task, which includes data and metadata required for processing.
+     * @param {(signal: string, ctx: AnyObject) => void} emit - A function used to send signals or events during task execution.
+     * @param {(progress: number) => void} progressCallback - A function to report execution progress as a percentage (0-100).
+     * @param {{ nodeId: string; routineExecId: string }} nodeData - An object containing identifiers for the current node and routine execution.
+     * @return {TaskResult} The result of the task execution.
      */
     execute(context: GraphContext, emit: (signal: string, ctx: AnyObject) => void, progressCallback: (progress: number) => void, nodeData: {
         nodeId: string;
@@ -164,6 +172,12 @@ interface DeputyDescriptor {
     localTaskName: string;
     communicationType: string;
 }
+/**
+ * The ServiceRegistry class is a singleton that manages the registration and lifecycle of
+ * service instances, deputies, and remote signals in a distributed service architecture.
+ * It handles various tasks such as instance updates, remote signal registration,
+ * service status synchronization, and error/event broadcasting.
+ */
 declare class ServiceRegistry {
     private static _instance;
     static get instance(): ServiceRegistry;
@@ -192,49 +206,63 @@ declare class ServiceRegistry {
     insertServiceInstanceTask: Task;
     handleServiceNotRespondingTask: Task;
     handleServiceHandshakeTask: Task;
+    /**
+     * Initializes a private constructor for managing service instances, remote signals,
+     * service health, and handling updates or synchronization tasks. The constructor
+     * creates a variety of meta tasks that process different lifecycle events and
+     * service-related updates in a distributed service registry model.
+     *
+     * @return {Object} An instance of the constructed class with initialized tasks
+     *                  and state management necessary to process service-related events.
+     */
     private constructor();
     reset(): void;
 }
 
+/**
+ * Represents a task responsible for transmitting signals to a remote service
+ * through the meta-layer for operations delegation.
+ *
+ * @class
+ * @extends Task
+ */
 declare class SignalTransmissionTask extends Task {
     readonly isDeputy: boolean;
     protected readonly signalName: string;
     protected readonly serviceName: string;
     /**
-     * Constructs a DatabaseTask to execute a database operation on a remote service.
-     * @param name - The local name of the Task.
-     * @param signalName - The name of the signal to transmit to the service.
-     * @param serviceName - The target database service name (optional, defaults to 'DatabaseService').
-     * @param description - A description of the task's purpose (default: '').
-     * @param concurrency - The maximum number of concurrent executions (default: 0, unlimited).
-     * @param timeout - Timeout in milliseconds (default: 0, handled by engine).
-     * @param register - Whether to register the task in the registry (default: true).
-     * @param isUnique
-     * @param isMeta
-     * @param isSubMeta
-     * @param isHidden
-     * @param getTagCallback - Callback for dynamic tagging, e.g., 'return "default"'.
-     * @param inputSchema - Input schema definition.
-     * @param validateInputContext - Whether to validate the input context (default: false).
-     * @param outputSchema - Output schema definition.
-     * @param validateOutputContext - Whether to validate the output context (default: false).
-     * @param retryCount
-     * @param retryDelay
-     * @param retryDelayMax
-     * @param retryDelayFactor
-     * @emits {meta.deputy.created} - Emitted on construction with task and service details.
-     * @note Fallbacks via `.doOnFail` externally; timeouts managed by the engine.
+     * Constructs a new instance of the class and initializes it with the provided parameters.
+     *
+     * @param {string} name - The name of the task being created.
+     * @param {string} signalName - The name of the signal associated with this task.
+     * @param {string} serviceName - The name of the service associated with this task.
+     * @param {string} [description=""] - An optional description of the task.
+     * @param {number} [concurrency=0] - The maximum allowed concurrency for this task.
+     * @param {number} [timeout=0] - The maximum execution time for this task, in milliseconds.
+     * @param {boolean} [register=true] - Whether the task should be registered upon creation.
+     * @param {boolean} [isUnique=false] - Indicates if the task should enforce uniqueness.
+     * @param {boolean} [isMeta=false] - Specifies if the task is a meta-task.
+     * @param {boolean} [isSubMeta=false] - Specifies if the task is a sub-meta-task.
+     * @param {boolean} [isHidden=false] - Indicates if the task is hidden from visibility.
+     * @param {ThrottleTagGetter|undefined} [getTagCallback=undefined] - A callback for tag throttling logic.
+     * @param {SchemaDefinition|undefined} [inputSchema=undefined] - An optional schema for validating input data.
+     * @param {boolean} [validateInputContext=false] - Whether to validate the input context against the input schema.
+     * @param {SchemaDefinition|undefined} [outputSchema=undefined] - An optional schema for validating output data.
+     * @param {boolean} [validateOutputContext=false] - Whether to validate the output context against the output schema.
+     * @param {number} [retryCount=0] - The number of retry attempts allowed in case of task failure.
+     * @param {number} [retryDelay=0] - The initial delay before retrying a failed task, in milliseconds.
+     * @param {number} [retryDelayMax=0] - The maximum delay between retry attempts, in milliseconds.
+     * @param {number} [retryDelayFactor=1] - A multiplier applied to retry delay for exponential backoff.
+     * @return {void} Does not return a value.
      */
     constructor(name: string, signalName: string, serviceName: string, description?: string, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, isSubMeta?: boolean, isHidden?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition$1 | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition$1 | undefined, validateOutputContext?: boolean, retryCount?: number, retryDelay?: number, retryDelayMax?: number, retryDelayFactor?: number);
     /**
-     * Triggers the database operation delegation flow via a signal to the meta-layer.
-     * @param context - The GraphContext containing execution data.
-     * @param emit
-     * @param progressCallback - Callback to update progress (invoked by meta-layer).
-     * @returns A Promise resolving with the task result or rejecting on error.
-     * @emits {meta.deputy.executed} - Emitted with context including queryData to initiate delegation.
-     * @edge Engine handles timeout and error, triggering `.doOnFail` if chained.
-     * @note The resolution and progress are managed by ephemeral meta-tasks.
+     * Executes the given task function within the provided execution context.
+     *
+     * @param {GraphContext} context - The context object providing the graph execution environment and metadata.
+     * @param {Function} emit - A function to emit signals with the provided name and context.
+     * @param {Function} progressCallback - A callback function to report the progress of the task execution as a number between 0 and 1.
+     * @return {TaskResult} The result of the executed task function.
      */
     execute(context: GraphContext, emit: (signal: string, ctx: AnyObject) => void, progressCallback: (progress: number) => void): TaskResult;
 }
@@ -359,6 +387,10 @@ interface DatabaseOptions {
     databaseName?: string;
     poolSize?: number;
 }
+/**
+ * The CadenzaService class serves as a central service layer providing various utility methods for managing tasks, signals, logging, and service interactions.
+ * This class handles the initialization (`bootstrap`) and validation of services, as well as the creation of tasks associated with services and signals.
+ */
 declare class CadenzaService {
     static broker: SignalBroker;
     static runner: GraphRunner;
@@ -367,9 +399,38 @@ declare class CadenzaService {
     static serviceRegistry: ServiceRegistry;
     protected static isBootstrapped: boolean;
     protected static serviceCreated: boolean;
+    /**
+     * Initializes the application by setting up necessary components and configurations.
+     * This method ensures the initialization process is only executed once throughout the application lifecycle.
+     *
+     * @return {void} This method does not return any value.
+     */
     static bootstrap(): void;
+    /**
+     * Validates the provided service name based on specific rules.
+     *
+     * @param {string} serviceName - The service name to validate. Must be less than 100 characters,
+     *                                must not contain spaces, dots, or backslashes, and must start with a capital letter.
+     * @return {void} Throws an error if the service name does not meet the validation criteria.
+     * @throws {Error} If the service name exceeds 100 characters.
+     * @throws {Error} If the service name contains spaces.
+     * @throws {Error} If the service name contains dots.
+     * @throws {Error} If the service name contains backslashes.
+     * @throws {Error} If the service name does not start with a capital letter.
+     */
     protected static validateServiceName(serviceName: string): void;
+    /**
+     * Validates the provided name to ensure it meets the required criteria.
+     *
+     * @param {string} name - The name to be validated.
+     * @return {void} Does not return any value.
+     */
     protected static validateName(name: string): void;
+    /**
+     * Gets the current run strategy from the Cadenza configuration.
+     *
+     * @return {Function} The run strategy function defined in the Cadenza configuration.
+     */
     static get runStrategy(): {
         PARALLEL: {
             run(): Promise<void>;
@@ -21740,155 +21801,326 @@ declare class CadenzaService {
             updateRunInstance(): void;
         };
     };
+    /**
+     * Sets the mode for the Cadenza application.
+     *
+     * @param {CadenzaMode} mode - The mode to be set for the application.
+     * @return {void} This method does not return a value.
+     */
     static setMode(mode: CadenzaMode): void;
+    /**
+     * Emits a signal with the specified data using the associated broker.
+     *
+     * @param {string} signal - The name of the event or signal to emit.
+     * @param {AnyObject} [data={}] - The data to be emitted along with the signal.
+     * @return {void} No return value.
+     */
     static emit(signal: string, data?: AnyObject): void;
+    /**
+     * Executes the given task or graph routine within the provided context using the configured runner.
+     *
+     * @param {Task | GraphRoutine} task - The task or graph routine to be executed.
+     * @param {AnyObject} context - The context within which the task will be executed.
+     * @return {void}
+     */
     static run(task: Task | GraphRoutine, context: AnyObject): void;
+    /**
+     * Logs a message with a specified log level and additional contextual data.
+     *
+     * @param {string} message - The main message to be logged.
+     * @param {any} [data={}] - Additional data or metadata to include with the log.
+     * @param {"info"|"warning"|"error"|"critical"} [level="info"] - The severity level of the log message.
+     * @param {string|null} [subjectServiceName=null] - The name of the subject service related to the log.
+     * @param {string|null} [subjectServiceInstanceId=null] - The instance ID of the subject service related to the log.
+     * @return {void} No return value.
+     */
     static log(message: string, data?: any, level?: "info" | "warning" | "error" | "critical", subjectServiceName?: string | null, subjectServiceInstanceId?: string | null): void;
+    /**
+     * Creates a new DeputyTask instance based on the provided routine name, service name, and options.
+     * This method ensures proper task initialization, including setting a unique name,
+     * validation of the routine name, and applying default option values.
+     *
+     * @param {string} routineName - The name of the routine the task references. This is mandatory and should be a valid string.
+     * @param {string|undefined} [serviceName] - The name of the service that the routine belongs to. This is optional and defaults to undefined.
+     * @param {TaskOptions} [options={}] - A configuration object for the task, allowing various properties such as concurrency, timeout, and retry settings to be customized.
+     * @return {DeputyTask} - A new DeputyTask instance initialized with the specified parameters.
+     */
     static createDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates a meta deputy task by setting the `isMeta` property in the options to true,
+     * and delegating task creation to the `createDeputyTask` method.
+     *
+     * @param {string} routineName - The name of the routine associated with the task.
+     * @param {string | undefined} [serviceName] - The optional name of the service associated with the task.
+     * @param {TaskOptions} [options={}] - Additional options for the task. Defaults to an empty object if not provided.
+     * @return {DeputyTask} - The created meta deputy task.
+     */
     static createMetaDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates a unique deputy task with the specified routine name, service name,
+     * and optional task options. The uniqueness is ensured by setting the
+     * `isUnique` property in the task options.
+     *
+     * @param {string} routineName - The name of the routine associated with the task.
+     * @param {string | undefined} [serviceName] - The name of the service associated with the task. If undefined, no service name is used.
+     * @param {TaskOptions} [options={}] - Additional configuration options for the task.
+     * @return {*} - Returns the result of creating a deputy task with the provided parameters and unique configuration.
+     */
     static createUniqueDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates a unique meta deputy task based on the provided routine name, service name, and options.
+     * This method sets the task as a meta task and delegates the creation to the `createUniqueDeputyTask` method.
+     *
+     * @param {string} routineName - The routine name to associate with the meta deputy task.
+     * @param {string | undefined} [serviceName] - The optional service name associated with the task.
+     * @param {TaskOptions} [options] - Additional options to configure the task. Defaults to an empty options object.
+     * @return {*} A unique meta deputy task created based on the given parameters.
+     */
     static createUniqueMetaDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates a throttled deputy task with the specified parameters.
+     *
+     * @param {string} routineName - The name of the routine to be executed.
+     * @param {string | undefined} [serviceName=undefined] - The name of the service, if applicable.
+     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function to get the throttled tag for the task.
+     * @param {TaskOptions} [options={}] - The options for task configuration, including concurrency and callbacks.
+     * @return {any} The created throttled deputy task.
+     */
     static createThrottledDeputyTask(routineName: string, serviceName?: string | undefined, throttledIdGetter?: ThrottleTagGetter, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates a throttled deputy task with meta-task settings enabled.
+     *
+     * @param {string} routineName - The name of the routine for which the task is being created.
+     * @param {string|undefined} [serviceName=undefined] - The name of the service associated with the task, or undefined if not applicable.
+     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function to compute or return the throttling identifier.
+     * @param {TaskOptions} [options={}] - Additional options for the task configuration.
+     * @return {any} Returns the created throttled deputy task instance.
+     */
     static createMetaThrottledDeputyTask(routineName: string, serviceName?: string | undefined, throttledIdGetter?: ThrottleTagGetter, options?: TaskOptions): DeputyTask;
+    /**
+     * Creates and configures a signal transmission task that handles the transmission
+     * of a specified signal to a target service with a set of customizable options.
+     *
+     * @param {string} signalName - The name of the signal to be transmitted.
+     * @param {string} serviceName - The name of the target service to transmit the signal to.
+     * @param {TaskOptions} [options={}] - A set of optional parameters to further configure the task.
+     * @return {SignalTransmissionTask} A new instance of SignalTransmissionTask configured with the given parameters.
+     */
     static createSignalTransmissionTask(signalName: string, serviceName: string, options?: TaskOptions): SignalTransmissionTask;
+    /**
+     * Creates and configures a database task that performs an operation on a specified table.
+     *
+     * @param {string} tableName - The name of the database table on which the operation will be performed.
+     * @param {DbOperationType} operation - The type of database operation to execute (e.g., insert, update, delete).
+     * @param {string|undefined} [databaseServiceName=undefined] - The name of the database service; defaults to "default database service" if not provided.
+     * @param {DbOperationPayload} queryData - The data payload required for executing the specified database operation.
+     * @param {TaskOptions} [options={}] - Optional configuration for the task, including concurrency, timeout, and retry policies.
+     * @return {DatabaseTask} A configured database task instance ready for execution.
+     */
     static createDatabaseTask(tableName: string, operation: DbOperationType$1, databaseServiceName: string | undefined, queryData: DbOperationPayload, options?: TaskOptions): DatabaseTask;
+    /**
+     * Creates a task for performing a database insert operation.
+     *
+     * @param {string} tableName - The name of the table where the insert operation will be performed.
+     * @param {string | undefined} [databaseServiceName=undefined] - The name of the database service to use. Optional parameter, defaults to undefined.
+     * @param {DbOperationPayload} [queryData={}] - The data payload for the insert operation. Defaults to an empty object.
+     * @param {TaskOptions} [options={}] - Additional task options to configure the insert operation. Defaults to an empty object.
+     * @return {object} A task configuration object for the database insert operation.
+     */
     static createDatabaseInsertTask(tableName: string, databaseServiceName?: string | undefined, queryData?: DbOperationPayload, options?: TaskOptions): DatabaseTask;
+    /**
+     * Creates a database query task for the specified table and configuration.
+     *
+     * @param {string} tableName - The name of the database table to execute the query on.
+     * @param {string | undefined} [databaseServiceName=undefined] - The name of the database service to use. If undefined, the default service will be used.
+     * @param {DbOperationPayload} queryData - The payload containing the query data to be executed.
+     * @param {TaskOptions} [options={}] - Optional parameters to configure the task execution.
+     * @return {Task} The created database query task.
+     */
     static createDatabaseQueryTask(tableName: string, databaseServiceName: string | undefined, queryData: DbOperationPayload, options?: TaskOptions): DatabaseTask;
+    /**
+     * Creates a database task for the CadenzaDB with the specified parameters.
+     *
+     * @param {string} tableName - The name of the database table on which the operation will be performed.
+     * @param {DbOperationType} operation - The type of database operation to execute (e.g., INSERT, UPDATE, DELETE).
+     * @param {DbOperationPayload} queryData - The payload or data required to perform the database operation.
+     * @param {TaskOptions} [options={}] - Additional options for the task, such as configuration settings.
+     * @return {any} The result of creating the database task.
+     */
     static createCadenzaDBTask(tableName: string, operation: DbOperationType$1, queryData: DbOperationPayload, options?: TaskOptions): DatabaseTask;
+    /**
+     * Creates a database insert task specifically for the CadenzaDB database.
+     *
+     * @param {string} tableName - The name of the table into which the data will be inserted.
+     * @param {DbOperationPayload} [queryData={}] - An object representing the data to be inserted.
+     * @param {TaskOptions} [options={}] - Additional options to customize the task. The `isMeta` property is set to true by default.
+     * @return {Task} A task object configured to perform an insert operation in the CadenzaDB database.
+     */
     static createCadenzaDBInsertTask(tableName: string, queryData?: DbOperationPayload, options?: TaskOptions): DatabaseTask;
+    /**
+     * Creates a database query task specifically for the CadenzaDB.
+     *
+     * @param {string} tableName - The name of the database table to execute the query on.
+     * @param {DbOperationPayload} queryData - The payload containing data and parameters for the database operation.
+     * @param {TaskOptions} [options={}] - Additional options for the task configuration.
+     * @return {any} The created task for executing a database query.
+     */
     static createCadenzaDBQueryTask(tableName: string, queryData: DbOperationPayload, options?: TaskOptions): DatabaseTask;
     /**
-     * Creates a MetaTask (for meta-layer graphs) and registers it.
-     * MetaTasks suppress further meta-signal emissions to prevent loops.
-     * @param serviceName Unique identifier for the meta-task.
-     * @param description Optional description.
-     * @param options Optional service options. A service can either be connected to a database service and/or a list of related services.
-     * Example RELATED_SERVICES=serviceId123,service1,http://address:port | serviceId124,service2,http://address:port
-     * @returns The created MetaTask instance.
-     * @throws Error if name invalid or duplicate.
+     * Creates a new Cadenza service with the specified configuration.
+     *
+     * @param {string} serviceName - The unique name of the service to create.
+     * @param {string} [description] - An optional description of the service.
+     * @param {ServerOptions} [options] - An optional object containing configuration options for the service.
+     * @return {boolean} Returns true when the service is successfully created.
      */
     static createCadenzaService(serviceName: string, description?: string, options?: ServerOptions): void;
+    /**
+     * Creates a Cadenza metadata service with the specified name, description, and options.
+     *
+     * @param {string} serviceName - The name of the metadata service to be created.
+     * @param {string} description - A brief description of the metadata service.
+     * @param {ServerOptions} [options={}] - Optional configuration for the metadata service. Defaults to an empty object.
+     * @return {void} Does not return a value.
+     */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
+    /**
+     * Creates and initializes a database service with the provided name, schema, and configuration options.
+     * This method is not supported in a browser environment and will log a warning if called in such an environment.
+     *
+     * @param {string} name - The name of the database service to be created.
+     * @param {SchemaDefinition} schema - The schema definition for the database service.
+     * @param {string} [description=""] - An optional description of the database service.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional configuration settings for the database and server.
+     * @return {void} This method does not return a value.
+     */
     static createDatabaseService(name: string, schema: SchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a meta database service with the specified configuration.
+     *
+     * @param {string} name - The name of the database service to be created.
+     * @param {SchemaDefinition} schema - The schema definition for the database.
+     * @param {string} [description=""] - An optional description of the database service.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server and database configuration options. The `isMeta` flag will be automatically set to true.
+     * @return {void} - This method does not return a value.
+     */
     static createMetaDatabaseService(name: string, schema: SchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
-     * 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 provided name, function, and optional details.
+     *
+     * @param {string} name - The name of the task to be created.
+     * @param {TaskFunction} func - The function that contains the task execution logic.
+     * @param {string} [description] - An optional description of what the task does.
+     * @param {TaskOptions} [options={}] - An optional configuration object specifying additional task options.
+     * @return {Task} - The created task instance.
      */
     static createTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * 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 new meta task with the specified name, function, description, and options.
+     *
+     * @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 options to configure the meta task.
+     * @return {Task} The created meta task instance.
      */
     static createMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
      * 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.
+     * @param {string} name Unique identifier.
+     * @param {TaskFunction} func Function receiving joinedContexts as a list (context.joinedContexts).
+     * @param {string} [description] Optional description.
+     * @param {TaskOptions} [options={}] Optional task options.
+     * @returns {Task} The created UniqueTask.
      */
     static createUniqueTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * 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 provided name, function, description, and options.
+     *
+     * @param {string} name - The unique name for the meta task.
+     * @param {TaskFunction} func - The function to be executed by the task.
+     * @param {string} [description] - An optional description of the task's purpose.
+     * @param {TaskOptions} [options={}] - Additional optional configuration settings for the task.
+     * @return {Task} Returns the created unique meta task.
      */
     static createUniqueMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
      * 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.
+     * @param {string} name Unique identifier.
+     * @param {TaskFunction} func Function.
+     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] Optional getter for dynamic grouping (e.g., per-user).
+     * @param {string} [description] Optional.
+     * @param {TaskOptions} [options={}] Optional task options.
+     * @returns {Task} The created ThrottledTask.
      */
     static createThrottledTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
-     * 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 and returns a throttled meta task with the specified name, function,
+     * and additional options. Throttling is determined based on the throttled ID getter.
+     *
+     * @param {string} name - The unique name for the meta task.
+     * @param {TaskFunction} func - The function to be executed as the task.
+     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function that determines the throttle ID for the task.
+     * @param {string} [description] - An optional description of the task.
+     * @param {TaskOptions} [options={}] - Additional configuration options for the task.
+     * @return {Task} The created throttled meta task.
      */
-    static createThrottledMetaTask(name: string, func: TaskFunction, throttledIdGetter: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
+    static createThrottledMetaTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
      * 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.
+     * @param {string} name Identifier.
+     * @param {TaskFunction} func Function.
+     * @param {string} [description] Optional.
+     * @param {number} [debounceTime=1000] Delay in ms.
+     * @param {TaskOptions & DebounceOptions} [options={}] Optional task options plus optional debounce config (e.g., leading/trailing).
+     * @returns {Task} The created DebounceTask.
      */
     static createDebounceTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebounceTask;
     /**
-     * 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 DebounceTask for the meta layer (delays exec until quiet period) and registers it.
+     * @param {string} name Identifier.
+     * @param {TaskFunction} func Function.
+     * @param {string} [description] Optional.
+     * @param {number} [debounceTime=1000] Delay in ms.
+     * @param {TaskOptions & DebounceOptions} [options={}] Optional task options plus optional debounce config (e.g., leading/trailing).
+     * @returns {Task} The created DebounceMetaTask.
      */
     static createDebounceMetaTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebounceTask;
     /**
      * 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.
-     * @returns The created EphemeralTask.
-     * @edge Destruction triggered post-exec via Node/Builder; emits meta-signal for cleanup.
+     * @param {string} name Identifier (may not be unique if not registered).
+     * @param {TaskFunction} func Function.
+     * @param {string} [description] Optional.
+     * @param {TaskOptions & EphemeralTaskOptions} [options={}] Optional task options.
+     * @returns {Task} The created EphemeralTask.
      */
     static createEphemeralTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates an EphemeralMetaTask for meta-layer transients.
-     * @param name Identifier.
-     * @param func Function.
-     * @param description Optional.
-     * @param options Optional task options.
-     * @returns The created EphemeralMetaTask.
+     * Creates an EphemeralTask for the meta layer (self-destructs after exec or condition) without default registration.
+     * Useful for transients; optionally register if needed.
+     * @param {string} name Identifier (may not be unique if not registered).
+     * @param {TaskFunction} func Function.
+     * @param {string} [description] Optional.
+     * @param {TaskOptions & EphemeralTaskOptions} [options={}] Optional task options.
+     * @returns {Task} The created EphemeralMetaTask.
      */
     static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
      * 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.
+     * @param {string} name Unique identifier.
+     * @param {Task[]} tasks Starting tasks.
+     * @param {string} [description] Optional.
+     * @returns {GraphRoutine} The created GraphRoutine.
      */
     static createRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
     /**
-     * Creates a MetaRoutine for meta-layer entry points.
-     * @param name Identifier.
-     * @param tasks Starting tasks.
-     * @param description Optional.
-     * @returns The created MetaRoutine.
+     * Creates a GraphRoutine for the meta layer (named entry to starting tasks) and registers it.
+     * @param {string} name Unique identifier.
+     * @param {Task[]} tasks Starting tasks.
+     * @param {string} [description] Optional.
+     * @returns {GraphRoutine} The created GraphMetaRoutine.
      */
     static createMetaRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
     static reset(): void;
@@ -21900,22 +22132,102 @@ declare class GraphMetadataController {
     constructor();
 }
 
+/**
+ * RestController class is responsible for managing RESTful interactions, including defining
+ * server configurations and handling client requests. It serves as a singleton, accessible via
+ * the `instance` property.
+ */
 declare class RestController {
     private static _instance;
     static get instance(): RestController;
+    /**
+     * Fetches data from the given URL with a specified timeout. This function performs
+     * a fetch request with the ability to cancel the request if it exceeds the provided timeout duration.
+     *
+     * @param {string} url - The URL to make the request to.
+     * @param {any} requestInit - The initialization object for the fetch request, which may include method, headers, and body.
+     * @param {number} timeoutMs - The maximum duration in milliseconds to wait for the fetch request to complete before aborting.
+     * @returns {Promise<any>} A promise that resolves to the parsed response data if the request is successful.
+     * @throws {Error} Throws an error if the request fails due to issues such as timeout or other unexpected errors.
+     */
     fetchDataWithTimeout: (url: string, requestInit: any, timeoutMs: number) => Promise<any>;
+    /**
+     * Constructor for initializing the REST server and related configurations.
+     *
+     * This method configures and sets up the REST server tasks using Cadenza's meta-task system, defining certain endpoints
+     * like `/handshake`, `/delegation`, `/signal`, and `/status`. It also integrates security settings, CORS policies,
+     * and rate-limiting profiles (low, medium, high) based on the provided context. Furthermore, it starts the server and
+     * establishes necessary meta-handlings to enable delegated operations and signal processing.
+     *
+     * It initializes and configures the REST server tasks.
+     */
     constructor();
 }
 
+/**
+ * The `SocketController` class handles the setup and management of a WebSocket server,
+ * ensuring secure connections, message handling, and rate-limiting.
+ * This class is designed to function as a singleton, providing a unified interface
+ * for WebSocket interactions in the application by standardizing the server setup
+ * and integrating task-based processing through the `Cadenza` framework.
+ */
 declare class SocketController {
     private static _instance;
     static get instance(): SocketController;
+    /**
+     * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
+     * including connection state recovery, rate limiting, CORS handling, and custom event handling.
+     * This class sets up the communication infrastructure for scalable, resilient, and secure WebSocket-based interactions
+     * using metadata-driven task execution with `Cadenza`.
+     *
+     * It provides support for:
+     * - Origin-based access control for connections.
+     * - Optional payload sanitization.
+     * - Configurable rate limiting and behavior on limit breaches (soft/hard disconnects).
+     * - Event handlers for connection, handshake, delegation, signaling, status checks, and disconnection.
+     *
+     * The server can handle both internal and external interactions depending on the provided configurations,
+     * and integrates directly with Cadenza's task workflow engine.
+     *
+     * Initializes the `SocketServer` to be ready for WebSocket communication.
+     */
     constructor();
 }
 
+/**
+ * SignalController is a singleton class that manages signal registration, transmission,
+ * and metadata handling within a service instance.
+ *
+ * This class utilizes the Cadenza framework to handle various tasks related to signals,
+ * such as registering signals, transmitting signals to remote services, adding metadata,
+ * and maintaining clean-forwarding and processing of signals.
+ *
+ * Features:
+ * - Ensures signals are properly registered and metadata is propagated.
+ * - Handles foreign signal registration for cross-service communication.
+ * - Forwards signal observations and manages their metadata.
+ * - Adds metadata during signal emission and consumption.
+ * - Implements a meta-task-based system for handling complex workflows.
+ *
+ * Constructor initializes the necessary meta-tasks and tasks required for signal management.
+ */
 declare class SignalController {
     private static _instance;
     static get instance(): SignalController;
+    /**
+     * Constructor method for initializing the signal registration and data transmission process.
+     * This method defines multiple meta tasks to manage signals, forwarding, and adding metadata
+     * for service instances in a distributed system.
+     *
+     * Some key functionalities include:
+     * - Registering signals from a service instance.
+     * - Handling foreign signal registration from remote services.
+     * - Forwarding signal observations between services.
+     * - Adding metadata to signal emissions for better traceability.
+     * - Adding metadata to signal consumption events.
+     *
+     * It serves as an initializer for signals and tasks.
+     */
     constructor();
 }