@cadenza.io/core/dist/index.d.ts

This is a framework for building asynchronous graphs and flows of tasks and signals.

type AnyObject = {
    [key: string | number]: any;
};

declare class GraphContext {
    readonly id: string;
    private readonly fullContext;
    private readonly userData;
    private readonly metaData;
    constructor(context: AnyObject);
    /**
     * Gets frozen user data (read-only, no clone).
     * @returns Frozen user context.
     */
    getContext(): AnyObject;
    getClonedContext(): AnyObject;
    /**
     * Gets full raw context (cloned for safety).
     * @returns Cloned full context.
     */
    getFullContext(): AnyObject;
    /**
     * Gets frozen metadata (read-only).
     * @returns Frozen metadata object.
     */
    getMetaData(): AnyObject;
    /**
     * Clones this context (new instance).
     * @returns New GraphContext.
     */
    clone(): GraphContext;
    /**
     * Creates new context from data (via registry).
     * @param context New data.
     * @returns New GraphContext.
     */
    mutate(context: AnyObject): GraphContext;
    /**
     * Combines with another for uniques (joins userData).
     * @param otherContext The other.
     * @returns New combined GraphContext.
     * @edge Appends other.userData to joinedContexts in userData.
     */
    combine(otherContext: GraphContext): GraphContext;
    /**
     * Exports the context.
     * @returns Exported object.
     */
    export(): {
        __id: string;
        __context: AnyObject;
    };
}

declare abstract class Iterator {
    abstract hasNext(): boolean;
    abstract hasPrevious?(): boolean;
    abstract next(): any;
    abstract previous?(): any;
    abstract getFirst?(): any;
    abstract getLast?(): any;
}

declare abstract class Graph {
    /**
     * Executes this graph node/task.
     * @param args Execution args (e.g., context).
     * @returns Result.
     */
    abstract execute(...args: any[]): unknown;
    /**
     * Logs the graph node (debugging).
     */
    abstract log(): void;
    /**
     * Destroys the graph node.
     */
    abstract destroy(): void;
    /**
     * Exports the graph node.
     * @returns Exported data.
     */
    abstract export(): any;
    /**
     * Accepts a visitor for traversal (e.g., debugging/exporters).
     * @param visitor The visitor.
     * @note Non-runtime use; pairs with iterator for data extraction.
     */
    abstract accept(visitor: GraphVisitor): void;
    /**
     * Gets an iterator for graph traversal (e.g., BFS/DFS).
     * @returns Iterator.
     * @note For debugging/exporters.
     */
    abstract getIterator(): Iterator;
}

declare class GraphNodeIterator implements Iterator {
    currentNode: GraphNode | undefined;
    currentLayer: GraphNode[];
    nextLayer: GraphNode[];
    index: number;
    constructor(node: GraphNode);
    hasNext(): boolean;
    next(): any;
}

declare abstract class SignalEmitter {
    protected silent: boolean;
    /**
     * Constructor for signal emitters.
     * @param silent If true, suppresses all emissions (e.g., for meta-runners to avoid loops; affects all emits).
     */
    constructor(silent?: boolean);
    /**
     * Emits a signal via the broker if not silent.
     * @param signal The signal name.
     * @param data Optional payload (defaults to empty object).
     * @edge No emission if silent; for metrics in silent mode, consider override or separate method.
     */
    emit(signal: string, data?: any): void;
    /**
     * Emits a signal via the broker even if silent.
     * @param signal The signal name.
     * @param data Optional payload (defaults to empty object).
     */
    emitMetric(signal: string, data?: any): void;
}

declare abstract class ExecutionChain {
    protected next: ExecutionChain | undefined;
    protected previous: ExecutionChain | undefined;
    setNext(next: ExecutionChain): void;
    get hasNext(): boolean;
    get hasPreceding(): boolean;
    getNext(): ExecutionChain | undefined;
    getPreceding(): ExecutionChain | undefined;
    decouple(): void;
}

declare class GraphLayerIterator implements Iterator {
    graph: GraphLayer;
    currentLayer: GraphLayer | undefined;
    constructor(graph: GraphLayer);
    hasNext(): boolean;
    hasPrevious(): boolean;
    next(): GraphLayer;
    previous(): GraphLayer;
    getFirst(): GraphLayer;
    getLast(): GraphLayer;
}

declare abstract class GraphLayer extends ExecutionChain implements Graph {
    protected readonly index: number;
    protected nodes: GraphNode[];
    private executionTime;
    private executionStart;
    protected debug: boolean;
    constructor(index: number);
    setDebug(value: boolean): void;
    abstract execute(context?: GraphContext): unknown;
    get hasPreceding(): boolean;
    getNumberOfNodes(): number;
    getNodesByRoutineExecId(routineExecId: string): GraphNode[];
    isProcessed(): boolean;
    graphDone(): boolean;
    setNext(next: GraphLayer): void;
    add(node: GraphNode): void;
    start(): number;
    end(): number;
    destroy(): void;
    getIterator(): GraphLayerIterator;
    accept(visitor: GraphVisitor): void;
    export(): {
        __index: number;
        __executionTime: number;
        __numberOfNodes: number;
        __hasNextLayer: boolean;
        __hasPrecedingLayer: boolean;
        __nodes: string[];
    };
    log(): void;
}

declare class GraphNode extends SignalEmitter implements Graph {
    id: string;
    routineExecId: string;
    private task;
    private context;
    private layer;
    private divided;
    private splitGroupId;
    private processing;
    private subgraphComplete;
    private graphComplete;
    private result;
    private previousNodes;
    private nextNodes;
    private executionTime;
    private executionStart;
    private failed;
    private errored;
    destroyed: boolean;
    protected debug: boolean;
    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[], debug?: boolean);
    setDebug(value: boolean): void;
    isUnique(): boolean;
    isMeta(): boolean;
    isProcessed(): boolean;
    isProcessing(): boolean;
    subgraphDone(): boolean;
    graphDone(): boolean;
    isEqualTo(node: GraphNode): boolean;
    isPartOfSameGraph(node: GraphNode): boolean;
    sharesTaskWith(node: GraphNode): boolean;
    sharesContextWith(node: GraphNode): boolean;
    getLayerIndex(): number;
    getConcurrency(): number;
    getTag(): string;
    scheduleOn(layer: GraphLayer): void;
    start(): number;
    end(): number;
    execute(): GraphNode[] | Promise<GraphNode[]>;
    private processAsync;
    private work;
    private onProgress;
    private postProcess;
    private onError;
    private divide;
    private generateNewNodes;
    private differentiate;
    private migrate;
    private split;
    clone(): GraphNode;
    consume(node: GraphNode): void;
    private changeIdentity;
    private completeSubgraph;
    private completeGraph;
    destroy(): void;
    getIterator(): GraphNodeIterator;
    mapNext(callback: (node: GraphNode) => any): any[];
    accept(visitor: GraphVisitor): void;
    export(): {
        __id: string;
        __task: AnyObject;
        __context: {
            __id: string;
            __context: AnyObject;
        };
        __result: unknown;
        __executionTime: number;
        __executionStart: number;
        __executionEnd: number;
        __nextNodes: string[];
        __previousNodes: string[];
        __routineExecId: string;
        __isProcessing: boolean;
        __isMeta: boolean;
        __graphComplete: boolean;
        __failed: boolean;
        __errored: boolean;
        __isUnique: boolean;
        __splitGroupId: string;
        __tag: string;
    };
    lightExport(): {
        __id: string;
        __task: {
            __id: string;
            __name: string;
        };
        __context: {
            __id: string;
            __context: AnyObject;
        };
        __executionTime: number;
        __executionStart: number;
        __nextNodes: string[];
        __previousNodes: string[];
        __routineExecId: string;
        __isProcessing: boolean;
        __graphComplete: boolean;
        __isMeta: boolean;
        __failed: boolean;
        __errored: boolean;
        __isUnique: boolean;
        __splitGroupId: string;
        __tag: string;
    };
    log(): void;
}

declare abstract class GraphVisitor {
    abstract visitLayer(layer: GraphLayer): any;
    abstract visitNode(node: GraphNode): any;
    abstract visitTask(task: Task): any;
}

declare class TaskIterator implements Iterator {
    private currentTask;
    private currentLayer;
    private nextLayer;
    private iterator;
    constructor(task: Task);
    hasNext(): boolean;
    next(): Task | undefined;
}

declare class SignalParticipant extends SignalEmitter {
    protected signalsToEmit: Set<string>;
    protected signalsToEmitOnFail: Set<string>;
    protected observedSignals: Set<string>;
    /**
     * Subscribes to signals (chainable).
     * @param signals The signal names.
     * @returns This for chaining.
     * @edge Duplicates ignored; assumes broker.observe binds this as handler.
     */
    doOn(...signals: string[]): this;
    /**
     * Sets signals to emit post-execution (chainable).
     * @param signals The signal names.
     * @returns This for chaining.
     */
    emits(...signals: string[]): this;
    emitsOnFail(...signals: string[]): this;
    /**
     * Unsubscribes from all observed signals.
     * @returns This for chaining.
     */
    unsubscribeAll(): this;
    /**
     * Unsubscribes from specific signals.
     * @param signals The signals.
     * @returns This for chaining.
     * @edge No-op if not subscribed.
     */
    unsubscribe(...signals: string[]): this;
    /**
     * Detaches specific emitted signals.
     * @param signals The signals.
     * @returns This for chaining.
     */
    detachSignals(...signals: string[]): this;
    /**
     * Detaches all emitted signals.
     * @returns This for chaining.
     */
    detachAllSignals(): this;
    /**
     * Emits attached signals.
     * @param context The context for emission.
     * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
     */
    emitSignals(context: GraphContext): void;
    /**
     * Emits attached fail signals.
     * @param context The context for emission.
     * @edge If isMeta (from Task), suppresses further "meta.*" to prevent loops.
     */
    emitOnFailSignals(context: GraphContext): void;
    /**
     * Destroys the participant (unsub/detach).
     */
    destroy(): void;
}

type SchemaType = "string" | "number" | "boolean" | "array" | "object" | "null" | "any";
type SchemaConstraints = {
    min?: number;
    max?: number;
    minLength?: number;
    maxLength?: number;
    pattern?: string;
    enum?: any[];
    multipleOf?: number;
    format?: "email" | "url" | "date-time" | "uuid" | "custom";
    oneOf?: any[];
};
type SchemaDefinition = {
    type: SchemaType;
    required?: string[];
    properties?: {
        [key: string]: SchemaDefinition;
    };
    items?: SchemaDefinition;
    constraints?: SchemaConstraints;
    description?: string;
    strict?: boolean;
};

type TaskFunction = (context: AnyObject, progressCallback: (progress: number) => void) => TaskResult;
type TaskResult = boolean | object | Generator | Promise<any> | void;
type ThrottleTagGetter = (context?: AnyObject, task?: Task) => string;
declare class Task extends SignalParticipant implements Graph {
    id: string;
    readonly name: string;
    readonly description: string;
    concurrency: number;
    timeout: number;
    readonly isMeta: boolean;
    readonly isUnique: boolean;
    readonly throttled: boolean;
    readonly isSignal: boolean;
    readonly isDeputy: boolean;
    readonly isEphemeral: boolean;
    protected inputContextSchema: SchemaDefinition | undefined;
    protected validateInputContext: boolean;
    protected outputContextSchema: SchemaDefinition | undefined;
    protected validateOutputContext: boolean;
    layerIndex: number;
    progressWeight: number;
    private nextTasks;
    private onFailTasks;
    private predecessorTasks;
    destroyed: boolean;
    protected readonly taskFunction: TaskFunction;
    /**
     * 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 getTagCallback
     * @param inputSchema
     * @param validateInputContext
     * @param outputSchema
     * @param validateOutputContext
     * @edge Emits 'meta.task.created' with { __task: this } for seed.
     */
    constructor(name: string, task: TaskFunction, description?: string, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean);
    getTag(context?: AnyObject): string;
    setGlobalId(id: string): void;
    setTimeout(timeout: number): void;
    setConcurrency(concurrency: number): void;
    setProgressWeight(weight: number): void;
    setInputContextSchema(schema: SchemaDefinition): void;
    setOutputContextSchema(schema: SchemaDefinition): void;
    setValidateInputContext(value: boolean): void;
    setValidateOutputContext(value: boolean): void;
    /**
     * 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.
     */
    protected validateSchema(data: any, schema: SchemaDefinition | undefined, path?: string): {
        valid: boolean;
        errors: Record<string, string>;
    };
    validateInput(context: AnyObject): true | AnyObject;
    validateOutput(context: AnyObject): true | AnyObject;
    /**
     * Executes the task function after optional input validation.
     * @param context - The GraphContext to validate and execute.
     * @param progressCallback - Callback for progress updates.
     * @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.
     */
    execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
    doAfter(...tasks: Task[]): this;
    then(...tasks: Task[]): this;
    decouple(task: Task): void;
    doOnFail(...tasks: Task[]): this;
    private updateProgressWeights;
    private getSubgraphLayers;
    private updateLayerFromPredecessors;
    private hasCycle;
    mapNext(callback: (task: Task) => any, failed?: boolean): any[];
    mapPrevious(callback: (task: Task) => any): any[];
    destroy(): void;
    export(): AnyObject;
    getIterator(): TaskIterator;
    accept(visitor: GraphVisitor): void;
    log(): void;
}

declare class SyncGraphLayer extends GraphLayer {
    execute(): GraphNode[];
}

declare abstract class GraphExporter {
    abstract exportGraph(graph: SyncGraphLayer): any;
    abstract exportStaticGraph(graph: Task[]): any;
}

declare abstract class GraphBuilder {
    graph: GraphLayer | undefined;
    topLayerIndex: number;
    layers: GraphLayer[];
    debug: boolean;
    setDebug(value: boolean): void;
    getResult(): GraphLayer;
    compose(): void;
    addNode(node: GraphNode): void;
    protected addNodes(nodes: GraphNode[]): void;
    protected addLayer(index: number): void;
    protected createLayer(index: number): GraphLayer;
    protected getLayer(layerIndex: number): GraphLayer;
    reset(): void;
}

declare abstract class GraphRunStrategy {
    protected graphBuilder: GraphBuilder;
    protected runInstance?: GraphRun;
    constructor();
    setRunInstance(runInstance: GraphRun): void;
    changeStrategy(builder: GraphBuilder): void;
    protected reset(): void;
    addNode(node: GraphNode): void;
    updateRunInstance(): void;
    abstract run(): void;
    abstract export(): any;
}

interface RunJson {
    __id: string;
    __label: string;
    __graph: any;
    __data: any;
}
declare class GraphRun {
    readonly id: string;
    private graph;
    private strategy;
    private exporter;
    constructor(strategy: GraphRunStrategy);
    setGraph(graph: GraphLayer): void;
    addNode(node: GraphNode): void;
    run(): void | Promise<void>;
    destroy(): void;
    log(): void;
    export(): RunJson;
    setExporter(exporter: GraphExporter): void;
}

declare class GraphRoutine extends SignalParticipant {
    id: string;
    readonly name: string;
    readonly description: string;
    readonly isMeta: boolean;
    private tasks;
    constructor(name: string, tasks: Task[], description: string, isMeta?: boolean);
    /**
     * Applies callback to starting tasks.
     * @param callBack The callback.
     * @returns Promise if async.
     */
    forEachTask(callBack: (task: Task) => any): Promise<void>;
    /**
     * Sets global ID.
     * @param id The ID.
     */
    setGlobalId(id: string): void;
    /**
     * Destroys the routine.
     */
    destroy(): void;
}

declare class GraphRunner extends SignalEmitter {
    readonly id: string;
    protected currentRun: GraphRun;
    private debug;
    protected isRunning: boolean;
    private readonly isMeta;
    protected strategy: GraphRunStrategy;
    /**
     * Constructs a runner.
     * @param isMeta Meta flag (default false).
     * @edge Creates 'Start run' meta-task chained to registry gets.
     */
    constructor(isMeta?: boolean);
    init(): void;
    /**
     * 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.
     */
    protected addTasks(tasks: Task | GraphRoutine | (Task | GraphRoutine)[], context?: AnyObject): void;
    /**
     * Runs tasks/routines.
     * @param tasks Optional tasks/routines.
     * @param context Optional context.
     * @returns Current/last run (Promise if async).
     * @edge If running, returns current; else runs and resets.
     */
    run(tasks?: Task | GraphRoutine | (Task | GraphRoutine)[], context?: AnyObject): GraphRun | Promise<GraphRun>;
    private runAsync;
    protected reset(): GraphRun;
    setDebug(value: boolean): void;
    destroy(): void;
    setStrategy(strategy: GraphRunStrategy): void;
    private startRun;
}

declare class SignalBroker {
    private static instance_;
    /**
     * Singleton instance for signal management.
     * @returns The broker instance.
     */
    static get instance(): SignalBroker;
    private debug;
    setDebug(value: boolean): void;
    protected sanitizeSignalName(signalName: string): void;
    protected runner: GraphRunner | undefined;
    protected metaRunner: GraphRunner | undefined;
    getSignalsTask: Task | undefined;
    protected signalObservers: Map<string, {
        fn: (runner: GraphRunner, tasks: (Task | GraphRoutine)[], context: AnyObject) => void;
        tasks: Set<Task | GraphRoutine>;
    }>;
    protected emitStacks: Map<string, Map<string, AnyObject>>;
    protected constructor();
    /**
     * Initializes with runners.
     * @param runner Standard runner for user signals.
     * @param metaRunner Meta runner for 'meta.' signals (suppresses further meta-emits).
     */
    bootstrap(runner: GraphRunner, metaRunner: GraphRunner): void;
    init(): void;
    /**
     * Observes a signal with a routine/task.
     * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
     * @param routineOrTask The observer.
     * @edge Duplicates ignored; supports wildcards for broad listening.
     */
    observe(signal: string, routineOrTask: Task | GraphRoutine): void;
    /**
     * Unsubscribes a routine/task from a signal.
     * @param signal The signal.
     * @param routineOrTask The observer.
     * @edge Removes all instances if duplicate; deletes if empty.
     */
    unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
    /**
     * 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.
     */
    emit(signal: string, context?: AnyObject): void;
    execute(signal: string, context: AnyObject): boolean;
    private executeListener;
    private addSignal;
    /**
     * Lists all observed signals.
     * @returns Array of signals.
     */
    listObservedSignals(): string[];
    reset(): void;
}

declare class GraphRegistry {
    private static _instance;
    static get instance(): GraphRegistry;
    private tasks;
    private routines;
    registerTask: Task;
    updateTaskId: Task;
    updateTaskInputSchema: Task;
    updateTaskOutputSchema: Task;
    getTaskById: Task;
    getTaskByName: Task;
    getTasksByLayer: Task;
    getAllTasks: Task;
    doForEachTask: Task;
    deleteTask: Task;
    registerRoutine: Task;
    updateRoutineId: Task;
    getRoutineById: Task;
    getRoutineByName: Task;
    getAllRoutines: Task;
    doForEachRoutine: Task;
    deleteRoutine: Task;
    private constructor();
    reset(): void;
}

interface DebounceOptions {
    leading?: boolean;
    trailing?: boolean;
    maxWait?: number;
}
declare class DebounceTask extends Task {
    private readonly debounceTime;
    private leading;
    private trailing;
    private maxWait;
    private timer;
    private maxTimer;
    private hasLaterCall;
    private lastResolve;
    private lastReject;
    private lastContext;
    private lastTimeout;
    private lastProgressCallback;
    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, maxWait?: number, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, inputSchema?: SchemaDefinition | undefined, validateInputSchema?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputSchema?: boolean);
    private executeFunction;
    private debouncedTrigger;
    execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
}

declare class EphemeralTask extends Task {
    private readonly once;
    private readonly condition;
    readonly isEphemeral: boolean;
    constructor(name: string, task: TaskFunction, description?: string, once?: boolean, condition?: (context: any) => boolean, concurrency?: number, timeout?: number, register?: boolean, isUnique?: boolean, isMeta?: boolean, getTagCallback?: ThrottleTagGetter | undefined, inputSchema?: SchemaDefinition | undefined, validateInputContext?: boolean, outputSchema?: SchemaDefinition | undefined, validateOutputContext?: boolean);
    execute(context: any, progressCallback: (progress: number) => void): TaskResult;
}

declare class GraphAsyncRun extends GraphRunStrategy {
    constructor();
    run(): Promise<void>;
    protected reset(): void;
    export(): any;
}

declare class GraphStandardRun extends GraphRunStrategy {
    run(): void;
    export(): any;
}

interface TaskOptions {
    concurrency?: number;
    timeout?: number;
    register?: boolean;
    isUnique?: boolean;
    isMeta?: boolean;
    getTagCallback?: ThrottleTagGetter;
    inputSchema?: SchemaDefinition;
    validateInputContext?: boolean;
    outputSchema?: SchemaDefinition;
    validateOutputContext?: boolean;
}
type CadenzaMode = "dev" | "debug" | "production";
declare class Cadenza {
    static broker: SignalBroker;
    static runner: GraphRunner;
    static metaRunner: GraphRunner;
    static registry: GraphRegistry;
    protected static isBootstrapped: boolean;
    protected static mode: CadenzaMode;
    protected static bootstrap(): void;
    static get runStrategy(): {
        PARALLEL: GraphAsyncRun;
        SEQUENTIAL: GraphStandardRun;
    };
    static setMode(mode: CadenzaMode): void;
    /**
     * Validates a name for uniqueness and non-emptiness.
     * @param name The name to validate.
     * @throws Error if invalid.
     */
    protected static validateName(name: string): 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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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.
     */
    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 once Destroy after first exec (default true).
     * @param destroyCondition Predicate for destruction (default always true).
     * @param options Optional task options.
     * @returns The created EphemeralTask.
     * @edge Destruction triggered post-exec via Node/Builder; emits meta-signal for cleanup.
     */
    static createEphemeralTask(name: string, func: TaskFunction, description?: string, once?: boolean, destroyCondition?: (context: any) => boolean, options?: TaskOptions): EphemeralTask;
    /**
     * Creates an EphemeralMetaTask for meta-layer transients.
     * @param name Identifier.
     * @param func Function.
     * @param description Optional.
     * @param once Destroy after first (default true).
     * @param destroyCondition Destruction predicate.
     * @param options Optional task options.
     * @returns The created EphemeralMetaTask.
     */
    static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, once?: boolean, destroyCondition?: (context: any) => boolean, options?: TaskOptions): 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.
     */
    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.
     */
    static createMetaRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
    static reset(): void;
}

declare class SignalTask extends Task {
    constructor(signal: string, description?: string);
}

export { type AnyObject, DebounceTask, EphemeralTask, GraphContext, GraphRegistry, GraphRoutine, GraphRun, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalEmitter, SignalParticipant, SignalTask, Task, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };