@supergrowthai/tq 1.0.13 → 1.1.1

package/dist/src/core/Actions.d.cts

@@ -3,6 +3,7 @@ import { Logger } from '@supergrowthai/utils';
 import { CronTask } from '../adapters';
 import { StartFlowInput } from './flow/types.js';
 import { EntityTaskProjection } from './entity/IEntityProjectionProvider.js';
+import { IFlowLifecycleProvider } from './lifecycle.js';
 export interface ActionResults<ID = any> {
     failedTasks: CronTask<ID>[];
     successTasks: CronTask<ID>[];
@@ -18,7 +19,10 @@ export declare class Actions<ID = any> implements ExecutorActions<ID> {
     private readonly _flowProjections;
     /** Logger for multi-task executors — carries runtime-only context (RFC-005) */
     readonly log: Logger;
-    constructor(taskRunnerId: string);
+    private readonly flowLifecycleProvider?;
+    /** Process identity (hostname-pid-timestamp) for lifecycle events */
+    private readonly workerId;
+    constructor(taskRunnerId: string, flowLifecycleProvider?: IFlowLifecycleProvider, workerId?: string);
     /**
      * Fork execution context for a specific task (for single-task executors)
      */

package/dist/src/core/Actions.d.ts

@@ -3,6 +3,7 @@ import { Logger } from '@supergrowthai/utils';
 import { CronTask } from '../adapters';
 import { StartFlowInput } from './flow/types.js';
 import { EntityTaskProjection } from './entity/IEntityProjectionProvider.js';
+import { IFlowLifecycleProvider } from './lifecycle.js';
 export interface ActionResults<ID = any> {
     failedTasks: CronTask<ID>[];
     successTasks: CronTask<ID>[];
@@ -18,7 +19,10 @@ export declare class Actions<ID = any> implements ExecutorActions<ID> {
     private readonly _flowProjections;
     /** Logger for multi-task executors — carries runtime-only context (RFC-005) */
     readonly log: Logger;
-    constructor(taskRunnerId: string);
+    private readonly flowLifecycleProvider?;
+    /** Process identity (hostname-pid-timestamp) for lifecycle events */
+    private readonly workerId;
+    constructor(taskRunnerId: string, flowLifecycleProvider?: IFlowLifecycleProvider, workerId?: string);
     /**
      * Fork execution context for a specific task (for single-task executors)
      */

package/dist/src/core/TaskHandler.d.cts

@@ -20,6 +20,7 @@ export declare class TaskHandler<ID> {
     private matureTaskTimer;
     private heartbeatTimer;
     private readonly config;
+    private readonly flowMiddleware?;
     private readonly workerId;
     private readonly workerStartedAt;
     private enabledQueues;
@@ -27,6 +28,7 @@ export declare class TaskHandler<ID> {
     private workerStats;
     private totalProcessingMs;
     private readonly queueStats;
+    private readonly consumerStatsMap;
     constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined, config?: TaskHandlerConfig);
     private get lifecycleProvider();
     private get workerProvider();
@@ -54,6 +56,10 @@ export declare class TaskHandler<ID> {
     private startHeartbeat;
     private stopHeartbeat;
     private updateWorkerStats;
+    private registerConsumerIfNew;
+    private updateConsumerStats;
+    private getActiveConsumerStats;
+    private emitAllConsumersStopped;
     private emitLifecycleEvent;
     processMatureTasks(abortSignal?: AbortSignal): void;
     private buildTaskContext;

package/dist/src/core/TaskHandler.d.ts

@@ -20,6 +20,7 @@ export declare class TaskHandler<ID> {
     private matureTaskTimer;
     private heartbeatTimer;
     private readonly config;
+    private readonly flowMiddleware?;
     private readonly workerId;
     private readonly workerStartedAt;
     private enabledQueues;
@@ -27,6 +28,7 @@ export declare class TaskHandler<ID> {
     private workerStats;
     private totalProcessingMs;
     private readonly queueStats;
+    private readonly consumerStatsMap;
     constructor(messageQueue: IMessageQueue<ID>, taskQueuesManager: TaskQueuesManager<ID>, databaseAdapter: ITaskStorageAdapter<ID>, cacheAdapter: CacheProvider<any>, asyncTaskManager?: IAsyncTaskManager<ID> | undefined, notificationProvider?: ITaskNotificationProvider | undefined, config?: TaskHandlerConfig);
     private get lifecycleProvider();
     private get workerProvider();
@@ -54,6 +56,10 @@ export declare class TaskHandler<ID> {
     private startHeartbeat;
     private stopHeartbeat;
     private updateWorkerStats;
+    private registerConsumerIfNew;
+    private updateConsumerStats;
+    private getActiveConsumerStats;
+    private emitAllConsumersStopped;
     private emitLifecycleEvent;
     processMatureTasks(abortSignal?: AbortSignal): void;
     private buildTaskContext;

package/dist/src/core/TaskRunner.d.cts

@@ -6,7 +6,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { TaskStore } from './TaskStore';
 import { IAsyncTaskManager } from './async/async-task-manager';
-import { ITaskLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
+import { ITaskLifecycleProvider, IFlowLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
 import { IEntityProjectionProvider, EntityProjectionConfig } from './entity/IEntityProjectionProvider.js';
 import { FlowMiddleware } from './flow/FlowMiddleware.js';
 export interface AsyncTask<ID> {
@@ -15,7 +15,25 @@ export interface AsyncTask<ID> {
     startTime: number;
     actions: AsyncActions<ID>;
 }
+export interface TaskRunnerOptions<ID> {
+    messageQueue: IMessageQueue<ID>;
+    taskQueue: TaskQueuesManager<ID>;
+    taskStore: TaskStore<ID>;
+    cacheProvider: CacheProvider<any>;
+    generateId: () => ID;
+    lifecycleProvider?: ITaskLifecycleProvider;
+    lifecycleConfig?: TaskHandlerLifecycleConfig;
+    entityProjection?: IEntityProjectionProvider<ID>;
+    entityProjectionConfig?: EntityProjectionConfig;
+    flowMiddleware?: FlowMiddleware<ID>;
+    flowLifecycleProvider?: IFlowLifecycleProvider;
+    /** Process identity (hostname-pid-timestamp) for lifecycle events */
+    workerId?: string;
+}
 export declare class TaskRunner<ID> {
+    private readonly logger;
+    private lockManager;
+    private readonly taskStartTimes;
     private messageQueue;
     private taskQueue;
     private taskStore;
@@ -25,10 +43,9 @@ export declare class TaskRunner<ID> {
     private entityProjection?;
     private entityProjectionConfig?;
     private flowMiddleware?;
-    private readonly logger;
-    private lockManager;
-    private readonly taskStartTimes;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID, lifecycleProvider?: ITaskLifecycleProvider | undefined, lifecycleConfig?: TaskHandlerLifecycleConfig | undefined, entityProjection?: IEntityProjectionProvider<ID> | undefined, entityProjectionConfig?: EntityProjectionConfig | undefined, flowMiddleware?: FlowMiddleware<ID> | undefined);
+    private flowLifecycleProvider?;
+    private readonly workerId;
+    constructor(opts: TaskRunnerOptions<ID>);
     /**
      * Build ALS log store for a single task execution.
      * Runtime keys (task_id, task_type, worker_id) override user-supplied log_context.

package/dist/src/core/TaskRunner.d.ts

@@ -6,7 +6,7 @@ import { CacheProvider } from 'memoose-js';
 import { TaskQueuesManager } from './TaskQueuesManager';
 import { TaskStore } from './TaskStore';
 import { IAsyncTaskManager } from './async/async-task-manager';
-import { ITaskLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
+import { ITaskLifecycleProvider, IFlowLifecycleProvider, TaskHandlerLifecycleConfig } from './lifecycle.js';
 import { IEntityProjectionProvider, EntityProjectionConfig } from './entity/IEntityProjectionProvider.js';
 import { FlowMiddleware } from './flow/FlowMiddleware.js';
 export interface AsyncTask<ID> {
@@ -15,7 +15,25 @@ export interface AsyncTask<ID> {
     startTime: number;
     actions: AsyncActions<ID>;
 }
+export interface TaskRunnerOptions<ID> {
+    messageQueue: IMessageQueue<ID>;
+    taskQueue: TaskQueuesManager<ID>;
+    taskStore: TaskStore<ID>;
+    cacheProvider: CacheProvider<any>;
+    generateId: () => ID;
+    lifecycleProvider?: ITaskLifecycleProvider;
+    lifecycleConfig?: TaskHandlerLifecycleConfig;
+    entityProjection?: IEntityProjectionProvider<ID>;
+    entityProjectionConfig?: EntityProjectionConfig;
+    flowMiddleware?: FlowMiddleware<ID>;
+    flowLifecycleProvider?: IFlowLifecycleProvider;
+    /** Process identity (hostname-pid-timestamp) for lifecycle events */
+    workerId?: string;
+}
 export declare class TaskRunner<ID> {
+    private readonly logger;
+    private lockManager;
+    private readonly taskStartTimes;
     private messageQueue;
     private taskQueue;
     private taskStore;
@@ -25,10 +43,9 @@ export declare class TaskRunner<ID> {
     private entityProjection?;
     private entityProjectionConfig?;
     private flowMiddleware?;
-    private readonly logger;
-    private lockManager;
-    private readonly taskStartTimes;
-    constructor(messageQueue: IMessageQueue<ID>, taskQueue: TaskQueuesManager<ID>, taskStore: TaskStore<ID>, cacheProvider: CacheProvider<any>, generateId: () => ID, lifecycleProvider?: ITaskLifecycleProvider | undefined, lifecycleConfig?: TaskHandlerLifecycleConfig | undefined, entityProjection?: IEntityProjectionProvider<ID> | undefined, entityProjectionConfig?: EntityProjectionConfig | undefined, flowMiddleware?: FlowMiddleware<ID> | undefined);
+    private flowLifecycleProvider?;
+    private readonly workerId;
+    constructor(opts: TaskRunnerOptions<ID>);
     /**
      * Build ALS log store for a single task execution.
      * Runtime keys (task_id, task_type, worker_id) override user-supplied log_context.

package/dist/src/core/async/AsyncActions.d.cts

@@ -12,6 +12,7 @@ import { FlowMiddleware } from '../flow/FlowMiddleware.js';
 export interface AsyncLifecycleEmitter {
     onCompleted(task: CronTask<any>, result?: unknown): void;
     onFailed(task: CronTask<any>, error: Error, willRetry: boolean): void;
+    onScheduled?(task: CronTask<any>): void;
 }
 export declare class AsyncActions<ID = any> {
     private messageQueue;

package/dist/src/core/async/AsyncActions.d.ts

@@ -12,6 +12,7 @@ import { FlowMiddleware } from '../flow/FlowMiddleware.js';
 export interface AsyncLifecycleEmitter {
     onCompleted(task: CronTask<any>, result?: unknown): void;
     onFailed(task: CronTask<any>, error: Error, willRetry: boolean): void;
+    onScheduled?(task: CronTask<any>): void;
 }
 export declare class AsyncActions<ID = any> {
     private messageQueue;

package/dist/src/core/flow/FlowMiddleware.d.cts

@@ -1,6 +1,7 @@
 import { CronTask } from '../../adapters/types.js';
 import { IFlowBarrierProvider } from './IFlowBarrierProvider.js';
 import { EntityTaskProjection } from '../entity/IEntityProjectionProvider.js';
+import { IFlowLifecycleProvider } from '../lifecycle.js';
 export interface FlowPostProcessInput<ID> {
     successTasks: CronTask<ID>[];
     failedTasks: CronTask<ID>[];
@@ -12,7 +13,11 @@ export interface FlowPostProcessResult<ID> {
 export declare class FlowMiddleware<ID> {
     private readonly barrierProvider;
     private readonly generateId;
-    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID);
+    private readonly flowLifecycleProvider?;
+    private readonly workerId;
+    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID, flowLifecycleProvider?: IFlowLifecycleProvider | undefined, workerId?: string);
+    private emitFlowEvent;
+    private buildFlowContext;
     /**
      * Process completed tasks for flow orchestration.
      * Called from TaskHandler.postProcessTasks after markFailed/markSuccess.

package/dist/src/core/flow/FlowMiddleware.d.ts

@@ -1,6 +1,7 @@
 import { CronTask } from '../../adapters/types.js';
 import { IFlowBarrierProvider } from './IFlowBarrierProvider.js';
 import { EntityTaskProjection } from '../entity/IEntityProjectionProvider.js';
+import { IFlowLifecycleProvider } from '../lifecycle.js';
 export interface FlowPostProcessInput<ID> {
     successTasks: CronTask<ID>[];
     failedTasks: CronTask<ID>[];
@@ -12,7 +13,11 @@ export interface FlowPostProcessResult<ID> {
 export declare class FlowMiddleware<ID> {
     private readonly barrierProvider;
     private readonly generateId;
-    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID);
+    private readonly flowLifecycleProvider?;
+    private readonly workerId;
+    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID, flowLifecycleProvider?: IFlowLifecycleProvider | undefined, workerId?: string);
+    private emitFlowEvent;
+    private buildFlowContext;
     /**
      * Process completed tasks for flow orchestration.
      * Called from TaskHandler.postProcessTasks after markFailed/markSuccess.

package/dist/src/core/flow/IFlowBarrierProvider.d.cts

@@ -43,4 +43,8 @@ export interface IFlowBarrierProvider {
      * Check if a flow's barrier has been fully met (remaining = 0).
      */
     isComplete(flowId: string): Promise<boolean>;
+    /**
+     * Get the time when a flow's barrier was initialized.
+     */
+    getStartedAt(flowId: string): Promise<Date | null>;
 }

package/dist/src/core/flow/IFlowBarrierProvider.d.ts

@@ -43,4 +43,8 @@ export interface IFlowBarrierProvider {
      * Check if a flow's barrier has been fully met (remaining = 0).
      */
     isComplete(flowId: string): Promise<boolean>;
+    /**
+     * Get the time when a flow's barrier was initialized.
+     */
+    getStartedAt(flowId: string): Promise<Date | null>;
 }

package/dist/src/core/flow/InMemoryFlowBarrierProvider.d.cts

@@ -7,4 +7,5 @@ export declare class InMemoryFlowBarrierProvider implements IFlowBarrierProvider
     getStepResults(flowId: string): Promise<FlowStepResult[]>;
     markAborted(flowId: string): Promise<boolean>;
     isComplete(flowId: string): Promise<boolean>;
+    getStartedAt(flowId: string): Promise<Date | null>;
 }

package/dist/src/core/flow/InMemoryFlowBarrierProvider.d.ts

@@ -7,4 +7,5 @@ export declare class InMemoryFlowBarrierProvider implements IFlowBarrierProvider
     getStepResults(flowId: string): Promise<FlowStepResult[]>;
     markAborted(flowId: string): Promise<boolean>;
     isComplete(flowId: string): Promise<boolean>;
+    getStartedAt(flowId: string): Promise<Date | null>;
 }

package/dist/src/core/lifecycle.d.cts

@@ -1,4 +1,5 @@
 import { EntityProjectionConfig, IEntityProjectionProvider } from './entity/IEntityProjectionProvider.js';
+import { IFlowBarrierProvider } from './flow/IFlowBarrierProvider.js';
 export interface TaskContext {
     /** Unique task identifier */
     task_id: string;
@@ -16,8 +17,10 @@ export interface TaskContext {
     max_retries: number;
     /** When task was scheduled */
     scheduled_at: Date;
-    /** Worker processing this task */
+    /** Worker/server processing this task (hostname-pid-timestamp) */
     worker_id?: string;
+    /** Consumer stream identity (provider:queue or shard ID) — distinguishes M consumers on same worker */
+    consumer_id?: string;
     /** User-provided log correlation context (RFC-005) */
     log_context?: Record<string, string>;
 }
@@ -59,6 +62,26 @@ export interface ITaskLifecycleProvider {
     onTaskCancelled?(ctx: TaskContext & {
         reason: string;
     }): void | Promise<void>;
+    /** Called when a multi-task (batch) executor starts processing a task group */
+    onTaskBatchStarted?(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        consumer_id?: string;
+        started_at: Date;
+    }): void | Promise<void>;
+    /** Called when a multi-task (batch) executor finishes processing a task group */
+    onTaskBatchCompleted?(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        consumer_id?: string;
+        succeeded: string[];
+        failed: string[];
+        duration_ms: number;
+    }): void | Promise<void>;
 }
 export interface WorkerInfo {
     /** Unique worker identifier */
@@ -87,6 +110,30 @@ export interface WorkerStats {
         started_at: Date;
     };
 }
+export interface ConsumerInfo {
+    /** Consumer stream identity (provider:queue or shard ID) */
+    consumer_id: string;
+    /** Queue this consumer is bound to */
+    queue_id: string;
+    /** Worker/server hosting this consumer (hostname-pid-timestamp) */
+    worker_id: string;
+    /** When this consumer was first seen (first batch arrival) */
+    started_at: Date;
+}
+export interface ConsumerStats {
+    /** Consumer stream identity */
+    consumer_id: string;
+    /** Queue this consumer is bound to */
+    queue_id: string;
+    /** Total tasks processed by this consumer */
+    tasks_processed: number;
+    /** Successfully completed tasks */
+    tasks_succeeded: number;
+    /** Failed tasks */
+    tasks_failed: number;
+    /** When the last task was processed */
+    last_task_at?: Date;
+}
 export interface IWorkerLifecycleProvider {
     /** Called when a worker starts consuming tasks */
     onWorkerStarted?(info: WorkerInfo): void | Promise<void>;
@@ -95,6 +142,8 @@ export interface IWorkerLifecycleProvider {
         stats: WorkerStats;
         memory_usage_mb: number;
         cpu_percent?: number;
+        /** Per-consumer stats for SRE dashboard — identifies all active consumers on this worker */
+        active_consumers: ConsumerStats[];
     }): void | Promise<void>;
     /** Called when a worker stops */
     onWorkerStopped?(info: WorkerInfo & {
@@ -113,6 +162,50 @@ export interface IWorkerLifecycleProvider {
         failed: number;
         duration_ms: number;
     }): void | Promise<void>;
+    /** Called lazily on first batch arrival for a consumer — use for SRE consumer→worker mapping */
+    onConsumerStarted?(info: ConsumerInfo): void | Promise<void>;
+    /** Called when a consumer stops (worker shutdown) */
+    onConsumerStopped?(info: ConsumerInfo & {
+        reason: 'shutdown' | 'error' | 'idle_timeout';
+        stats: ConsumerStats;
+    }): void | Promise<void>;
+}
+export interface FlowContext {
+    flow_id: string;
+    total_steps: number;
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    failure_policy: 'continue' | 'abort';
+    entity?: {
+        id: string;
+        type: string;
+    };
+    /** Worker/server that emitted this event — for SRE dashboard correlation */
+    worker_id: string;
+    /** Consumer stream identity — for multi-consumer-per-worker setups */
+    consumer_id?: string;
+}
+export interface IFlowLifecycleProvider {
+    onFlowStarted?(ctx: FlowContext & {
+        started_at: Date;
+        step_types: string[];
+    }): void | Promise<void>;
+    onFlowCompleted?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_succeeded: number;
+        steps_failed: number;
+    }): void | Promise<void>;
+    onFlowAborted?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+        trigger_step_index: number;
+    }): void | Promise<void>;
+    onFlowTimedOut?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+    }): void | Promise<void>;
 }
 export interface TaskHandlerLifecycleConfig {
     /** Callback execution mode: 'sync' blocks, 'async' is fire-and-forget */
@@ -133,6 +226,8 @@ export interface TaskHandlerConfig {
     entityProjection?: IEntityProjectionProvider;
     /** RFC-003: Entity projection configuration */
     entityProjectionConfig?: EntityProjectionConfig;
-    /** RFC-002: Flow middleware for fan-out/fan-in orchestration */
-    flowMiddleware?: import('./flow/FlowMiddleware.js').FlowMiddleware<any>;
+    /** RFC-002: Flow barrier provider — TaskHandler assembles FlowMiddleware internally */
+    flowBarrierProvider?: IFlowBarrierProvider;
+    /** Flow lifecycle event provider */
+    flowLifecycleProvider?: IFlowLifecycleProvider;
 }

package/dist/src/core/lifecycle.d.ts

@@ -1,4 +1,5 @@
 import { EntityProjectionConfig, IEntityProjectionProvider } from './entity/IEntityProjectionProvider.js';
+import { IFlowBarrierProvider } from './flow/IFlowBarrierProvider.js';
 export interface TaskContext {
     /** Unique task identifier */
     task_id: string;
@@ -16,8 +17,10 @@ export interface TaskContext {
     max_retries: number;
     /** When task was scheduled */
     scheduled_at: Date;
-    /** Worker processing this task */
+    /** Worker/server processing this task (hostname-pid-timestamp) */
     worker_id?: string;
+    /** Consumer stream identity (provider:queue or shard ID) — distinguishes M consumers on same worker */
+    consumer_id?: string;
     /** User-provided log correlation context (RFC-005) */
     log_context?: Record<string, string>;
 }
@@ -59,6 +62,26 @@ export interface ITaskLifecycleProvider {
     onTaskCancelled?(ctx: TaskContext & {
         reason: string;
     }): void | Promise<void>;
+    /** Called when a multi-task (batch) executor starts processing a task group */
+    onTaskBatchStarted?(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        consumer_id?: string;
+        started_at: Date;
+    }): void | Promise<void>;
+    /** Called when a multi-task (batch) executor finishes processing a task group */
+    onTaskBatchCompleted?(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        consumer_id?: string;
+        succeeded: string[];
+        failed: string[];
+        duration_ms: number;
+    }): void | Promise<void>;
 }
 export interface WorkerInfo {
     /** Unique worker identifier */
@@ -87,6 +110,30 @@ export interface WorkerStats {
         started_at: Date;
     };
 }
+export interface ConsumerInfo {
+    /** Consumer stream identity (provider:queue or shard ID) */
+    consumer_id: string;
+    /** Queue this consumer is bound to */
+    queue_id: string;
+    /** Worker/server hosting this consumer (hostname-pid-timestamp) */
+    worker_id: string;
+    /** When this consumer was first seen (first batch arrival) */
+    started_at: Date;
+}
+export interface ConsumerStats {
+    /** Consumer stream identity */
+    consumer_id: string;
+    /** Queue this consumer is bound to */
+    queue_id: string;
+    /** Total tasks processed by this consumer */
+    tasks_processed: number;
+    /** Successfully completed tasks */
+    tasks_succeeded: number;
+    /** Failed tasks */
+    tasks_failed: number;
+    /** When the last task was processed */
+    last_task_at?: Date;
+}
 export interface IWorkerLifecycleProvider {
     /** Called when a worker starts consuming tasks */
     onWorkerStarted?(info: WorkerInfo): void | Promise<void>;
@@ -95,6 +142,8 @@ export interface IWorkerLifecycleProvider {
         stats: WorkerStats;
         memory_usage_mb: number;
         cpu_percent?: number;
+        /** Per-consumer stats for SRE dashboard — identifies all active consumers on this worker */
+        active_consumers: ConsumerStats[];
     }): void | Promise<void>;
     /** Called when a worker stops */
     onWorkerStopped?(info: WorkerInfo & {
@@ -113,6 +162,50 @@ export interface IWorkerLifecycleProvider {
         failed: number;
         duration_ms: number;
     }): void | Promise<void>;
+    /** Called lazily on first batch arrival for a consumer — use for SRE consumer→worker mapping */
+    onConsumerStarted?(info: ConsumerInfo): void | Promise<void>;
+    /** Called when a consumer stops (worker shutdown) */
+    onConsumerStopped?(info: ConsumerInfo & {
+        reason: 'shutdown' | 'error' | 'idle_timeout';
+        stats: ConsumerStats;
+    }): void | Promise<void>;
+}
+export interface FlowContext {
+    flow_id: string;
+    total_steps: number;
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    failure_policy: 'continue' | 'abort';
+    entity?: {
+        id: string;
+        type: string;
+    };
+    /** Worker/server that emitted this event — for SRE dashboard correlation */
+    worker_id: string;
+    /** Consumer stream identity — for multi-consumer-per-worker setups */
+    consumer_id?: string;
+}
+export interface IFlowLifecycleProvider {
+    onFlowStarted?(ctx: FlowContext & {
+        started_at: Date;
+        step_types: string[];
+    }): void | Promise<void>;
+    onFlowCompleted?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_succeeded: number;
+        steps_failed: number;
+    }): void | Promise<void>;
+    onFlowAborted?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+        trigger_step_index: number;
+    }): void | Promise<void>;
+    onFlowTimedOut?(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+    }): void | Promise<void>;
 }
 export interface TaskHandlerLifecycleConfig {
     /** Callback execution mode: 'sync' blocks, 'async' is fire-and-forget */
@@ -133,6 +226,8 @@ export interface TaskHandlerConfig {
     entityProjection?: IEntityProjectionProvider;
     /** RFC-003: Entity projection configuration */
     entityProjectionConfig?: EntityProjectionConfig;
-    /** RFC-002: Flow middleware for fan-out/fan-in orchestration */
-    flowMiddleware?: import('./flow/FlowMiddleware.js').FlowMiddleware<any>;
+    /** RFC-002: Flow barrier provider — TaskHandler assembles FlowMiddleware internally */
+    flowBarrierProvider?: IFlowBarrierProvider;
+    /** Flow lifecycle event provider */
+    flowLifecycleProvider?: IFlowLifecycleProvider;
 }

package/dist/src/providers/ConsoleHealthProvider.d.cts

@@ -1,5 +1,5 @@
-import { ITaskLifecycleProvider, IWorkerLifecycleProvider, TaskContext, TaskTiming, WorkerInfo, WorkerStats } from '../core/lifecycle.js';
-export declare class ConsoleHealthProvider implements ITaskLifecycleProvider, IWorkerLifecycleProvider {
+import { ITaskLifecycleProvider, IWorkerLifecycleProvider, IFlowLifecycleProvider, FlowContext, TaskContext, TaskTiming, WorkerInfo, WorkerStats, ConsumerInfo, ConsumerStats } from '../core/lifecycle.js';
+export declare class ConsoleHealthProvider implements ITaskLifecycleProvider, IWorkerLifecycleProvider, IFlowLifecycleProvider {
     private readonly prefix;
     constructor(prefix?: string);
     onTaskScheduled(ctx: TaskContext): void;
@@ -29,6 +29,7 @@ export declare class ConsoleHealthProvider implements ITaskLifecycleProvider, IW
     onWorkerHeartbeat(info: WorkerInfo & {
         stats: WorkerStats;
         memory_usage_mb: number;
+        active_consumers: ConsumerStats[];
     }): void;
     onWorkerStopped(info: WorkerInfo & {
         reason: 'shutdown' | 'error' | 'idle_timeout';
@@ -44,4 +45,43 @@ export declare class ConsoleHealthProvider implements ITaskLifecycleProvider, IW
         failed: number;
         duration_ms: number;
     }): void;
+    onConsumerStarted(info: ConsumerInfo): void;
+    onConsumerStopped(info: ConsumerInfo & {
+        reason: string;
+        stats: ConsumerStats;
+    }): void;
+    onTaskBatchStarted(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        started_at: Date;
+    }): void;
+    onTaskBatchCompleted(ctx: {
+        task_type: string;
+        queue_id: string;
+        tasks: TaskContext[];
+        worker_id: string;
+        succeeded: string[];
+        failed: string[];
+        duration_ms: number;
+    }): void;
+    onFlowStarted(ctx: FlowContext & {
+        started_at: Date;
+        step_types: string[];
+    }): void;
+    onFlowCompleted(ctx: FlowContext & {
+        duration_ms: number;
+        steps_succeeded: number;
+        steps_failed: number;
+    }): void;
+    onFlowAborted(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+        trigger_step_index: number;
+    }): void;
+    onFlowTimedOut(ctx: FlowContext & {
+        duration_ms: number;
+        steps_completed: number;
+    }): void;
 }