@cadenza.io/core 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,843 @@
+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;
+    constructor(index: number);
+    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;
+    constructor(task: Task, context: GraphContext, routineExecId: string, prevNodes?: GraphNode[]);
+    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 TaskFunction = (context: AnyObject, progressCallback: (progress: number) => void) => TaskResult;
+type TaskResult = boolean | object | Generator | Promise<any> | void;
+declare class Task extends SignalParticipant implements Graph {
+    id: string;
+    readonly name: string;
+    readonly description: string;
+    concurrency: number;
+    timeout: number;
+    readonly isUnique: boolean;
+    readonly throttled: boolean;
+    readonly isSignal: boolean;
+    readonly isMeta: boolean;
+    readonly isDeputy: boolean;
+    readonly isEphemeral: 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).
+     * @edge Emits 'meta.task.created' with { __task: this } for seed.
+     */
+    constructor(name: string, task: TaskFunction, description?: string, concurrency?: number, timeout?: number, register?: boolean);
+    getTag(context?: AnyObject): string;
+    setGlobalId(id: string): void;
+    setTimeout(timeout: number): void;
+    setConcurrency(concurrency: number): void;
+    setProgressWeight(weight: number): void;
+    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[];
+    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);
+    /**
+     * 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;
+    protected runner: GraphRunner | undefined;
+    protected metaRunner: GraphRunner | undefined;
+    protected signalObservers: Map<string, {
+        fn: (runner: GraphRunner, tasks: (Task | GraphRoutine)[], context: AnyObject) => void;
+        tasks: Set<Task | GraphRoutine>;
+    }>;
+    protected emitStacks: Map<string, Set<string>>;
+    protected constructor();
+    /**
+     * Initializes with runners.
+     * @param runner Standard runner for user signals.
+     * @param metaRunner Meta runner for 'meta.' signals (suppresses further meta-emits).
+     */
+    init(runner: GraphRunner, metaRunner: GraphRunner): 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.
+     * @throws Error on detected loop.
+     */
+    emit(signal: string, context?: AnyObject): void;
+    private executeListener;
+    private addSignal;
+    /**
+     * Lists all observed signals.
+     * @returns Array of signals.
+     */
+    listObservedSignals(): string[];
+    private getRunner;
+    reset(): void;
+}
+
+declare class MetaTask extends Task {
+    readonly isMeta: boolean;
+}
+
+declare class GraphRegistry {
+    private static _instance;
+    static get instance(): GraphRegistry;
+    private tasks;
+    private routines;
+    registerTask: MetaTask;
+    updateTaskId: MetaTask;
+    getTaskById: MetaTask;
+    getTaskByName: MetaTask;
+    getTasksByLayer: MetaTask;
+    getAllTasks: MetaTask;
+    doForEachTask: MetaTask;
+    deleteTask: MetaTask;
+    registerRoutine: MetaTask;
+    updateRoutineId: MetaTask;
+    getRoutineById: MetaTask;
+    getRoutineByName: MetaTask;
+    getAllRoutines: MetaTask;
+    doForEachRoutine: MetaTask;
+    deleteRoutine: MetaTask;
+    private constructor();
+    reset(): void;
+}
+
+declare class UniqueTask extends Task {
+    readonly isUnique: boolean;
+}
+
+declare class UniqueMetaTask extends UniqueTask {
+    readonly isMeta: boolean;
+}
+
+type ThrottleTagGetter = (context?: AnyObject, task?: Task) => string;
+declare class ThrottledTask extends Task {
+    readonly throttled: boolean;
+    constructor(name: string, task: TaskFunction, description?: string, getTagCallback?: ThrottleTagGetter, concurrency?: number, timeout?: number, register?: boolean);
+    export(): {
+        __getTagCallback: string;
+    };
+}
+
+declare class ThrottledMetaTask extends ThrottledTask {
+    readonly isMeta: boolean;
+}
+
+interface DebounceOptions {
+    leading?: boolean;
+    trailing?: boolean;
+}
+declare class DebounceTask extends Task {
+    private readonly debounceTime;
+    private leading;
+    private trailing;
+    private timer;
+    private lastResolve;
+    private lastReject;
+    private lastContext;
+    private lastTimeout;
+    constructor(name: string, task: TaskFunction, description?: string, debounceTime?: number, leading?: boolean, trailing?: boolean, concurrency?: number, timeout?: number, register?: boolean);
+    private executeFunction;
+    private debouncedTrigger;
+    execute(context: GraphContext, progressCallback: (progress: number) => void): TaskResult;
+}
+
+declare class DebouncedMetaTask extends DebounceTask {
+    readonly isMeta: boolean;
+}
+
+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);
+    execute(context: any, progressCallback: (progress: number) => void): TaskResult;
+}
+
+declare class EphemeralMetaTask extends EphemeralTask {
+    readonly isMeta: boolean;
+}
+
+declare class MetaRoutine extends GraphRoutine {
+    readonly isMeta: boolean;
+}
+
+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;
+}
+declare class Cadenza {
+    static broker: SignalBroker;
+    static runner: GraphRunner;
+    static metaRunner: GraphRunner;
+    static registry: GraphRegistry;
+    private static isBootstrapped;
+    private static bootstrap;
+    static get runStrategy(): {
+        PARALLEL: GraphAsyncRun;
+        SEQUENTIAL: GraphStandardRun;
+    };
+    /**
+     * Validates a name for uniqueness and non-emptiness.
+     * @param name The name to validate.
+     * @throws Error if invalid.
+     */
+    private static validateName;
+    /**
+     * 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): MetaTask;
+    /**
+     * 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): UniqueTask;
+    /**
+     * 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): UniqueMetaTask;
+    /**
+     * 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): ThrottledTask;
+    /**
+     * 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): ThrottledMetaTask;
+    /**
+     * 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): DebouncedMetaTask;
+    /**
+     * 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): EphemeralMetaTask;
+    /**
+     * 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): MetaRoutine;
+    static reset(): void;
+}
+
+export { Cadenza as default };