@supergrowthai/tq 1.0.11 → 1.0.13

package/dist/src/core/async/async-task-manager.d.ts

@@ -1,4 +1,13 @@
 import { CronTask } from '../../adapters';
+/**
+ * Result returned from shutdown() describing what happened during grace period
+ */
+export interface ShutdownResult {
+    /** Number of tasks that completed during the grace period */
+    completedDuringGrace: number;
+    /** Task IDs that were still running when grace period expired */
+    abandonedTaskIds: string[];
+}
 /**
  * Interface for managing async tasks that exceed timeout thresholds
  * Implementation should be in tq package to access executor configs
@@ -8,18 +17,27 @@ export interface IAsyncTaskManager<T = any, ID = any> {
      * Hand off a running task to async management
      * @param message The message that is still being processed
      * @param runningPromise The promise of the still-running task
-     * @returns true if accepted, false if queue is full
+     * @param taskTimeout Optional per-task timeout override in ms
+     * @returns true if accepted, false if queue is full or duplicate
      */
-    handoffTask(message: CronTask<ID>, runningPromise: Promise<void>): boolean;
+    handoffTask(message: CronTask<ID>, runningPromise: Promise<void>, taskTimeout?: number): boolean;
     /**
      * Gracefully shutdown the async task manager
+     * Waits for in-flight promises up to grace period, then returns status
      */
-    shutdown(abortSignal?: AbortSignal): Promise<void>;
+    shutdown(abortSignal?: AbortSignal): Promise<ShutdownResult>;
     isHandedOff(taskId: ID): boolean;
     canAcceptTask(): boolean;
     getMetrics(): {
         activeTaskCount: number;
         totalHandedOff: number;
+        totalCompleted: number;
+        totalRejected: number;
+        totalTimedOut: number;
+        oldestTaskMs: number;
+        utilizationPercent: number;
+        maxTasks: number;
         [key: string]: unknown;
     };
+    resetCounters(): void;
 }

package/dist/src/core/async/retry-utils.d.cts

@@ -0,0 +1,15 @@
+import { CronTask } from '../../adapters';
+export interface RetryDecision<ID = any> {
+    action: 'retry' | 'fail';
+    retryTask?: CronTask<ID>;
+}
+/**
+ * Compute whether a failed task should be retried and produce the retry-ready task.
+ *
+ * Mirrors the logic in TaskHandler.postProcessTasks() but usable from the async path.
+ *
+ * @param task       The failed task
+ * @param maxRetries Maximum retry attempts for this task type
+ * @returns RetryDecision — either { action: 'retry', retryTask } or { action: 'fail' }
+ */
+export declare function computeRetryDecision<ID>(task: CronTask<ID>, maxRetries: number): RetryDecision<ID>;

package/dist/src/core/async/retry-utils.d.ts

@@ -0,0 +1,15 @@
+import { CronTask } from '../../adapters';
+export interface RetryDecision<ID = any> {
+    action: 'retry' | 'fail';
+    retryTask?: CronTask<ID>;
+}
+/**
+ * Compute whether a failed task should be retried and produce the retry-ready task.
+ *
+ * Mirrors the logic in TaskHandler.postProcessTasks() but usable from the async path.
+ *
+ * @param task       The failed task
+ * @param maxRetries Maximum retry attempts for this task type
+ * @returns RetryDecision — either { action: 'retry', retryTask } or { action: 'fail' }
+ */
+export declare function computeRetryDecision<ID>(task: CronTask<ID>, maxRetries: number): RetryDecision<ID>;

package/dist/src/core/base/interfaces.d.cts

@@ -1,5 +1,7 @@
 import { CronTask } from '../../adapters';
 import { MessageType, TypedMessage } from '@supergrowthai/mq';
+import { Logger } from '@supergrowthai/utils';
+import { StartFlowInput } from '../flow/types.js';
 /**
  * Type helper to extract the correct CronTask type based on message type
  */
@@ -12,11 +14,17 @@ interface IBaseExecutor {
         handoffTimeout: number;
         maxConcurrentAsync?: number;
     };
+    /** Optional static partition key for ordering guarantees (e.g., return payload.user_id) */
+    getPartitionKey?: (task: CronTask<any>) => string;
 }
 export type ExecutorActions<ID = any> = {
     addTasks(task: CronTask<ID>[]): void;
-    fail(task: CronTask<ID>): void;
-    success(task: CronTask<ID>): void;
+    fail(task: CronTask<ID>, error?: Error | string, meta?: Record<string, unknown>): void;
+    success(task: CronTask<ID>, result?: unknown): void;
+    /** Fan-out/fan-in flow orchestration (RFC-002) */
+    startFlow(input: StartFlowInput): string;
+    /** Child logger scoped to this task's log_context (RFC-005) */
+    readonly log: Logger;
 };
 export interface IMultiTaskExecutor<ID = any, T extends MessageType = MessageType> extends IBaseExecutor {
     multiple: true;

package/dist/src/core/base/interfaces.d.ts

@@ -1,5 +1,7 @@
 import { CronTask } from '../../adapters';
 import { MessageType, TypedMessage } from '@supergrowthai/mq';
+import { Logger } from '@supergrowthai/utils';
+import { StartFlowInput } from '../flow/types.js';
 /**
  * Type helper to extract the correct CronTask type based on message type
  */
@@ -12,11 +14,17 @@ interface IBaseExecutor {
         handoffTimeout: number;
         maxConcurrentAsync?: number;
     };
+    /** Optional static partition key for ordering guarantees (e.g., return payload.user_id) */
+    getPartitionKey?: (task: CronTask<any>) => string;
 }
 export type ExecutorActions<ID = any> = {
     addTasks(task: CronTask<ID>[]): void;
-    fail(task: CronTask<ID>): void;
-    success(task: CronTask<ID>): void;
+    fail(task: CronTask<ID>, error?: Error | string, meta?: Record<string, unknown>): void;
+    success(task: CronTask<ID>, result?: unknown): void;
+    /** Fan-out/fan-in flow orchestration (RFC-002) */
+    startFlow(input: StartFlowInput): string;
+    /** Child logger scoped to this task's log_context (RFC-005) */
+    readonly log: Logger;
 };
 export interface IMultiTaskExecutor<ID = any, T extends MessageType = MessageType> extends IBaseExecutor {
     multiple: true;

package/dist/src/core/entity/IEntityProjectionProvider.d.cts

@@ -0,0 +1,45 @@
+import { CronTask } from '../../adapters/types.js';
+export type EntityTaskProjectionStatus = 'scheduled' | 'processing' | 'executed' | 'failed';
+export interface EntityTaskProjection<ID = any> {
+    task_id: ID;
+    entity_id: string;
+    entity_type: string;
+    task_type: string;
+    queue_id: string;
+    status: EntityTaskProjectionStatus;
+    payload?: unknown;
+    error?: string;
+    result?: unknown;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Provider interface for persisting entity-task projections.
+ * Implementations might write to a database table, cache, or external service.
+ */
+export interface IEntityProjectionProvider<ID = any> {
+    upsertProjections(entries: EntityTaskProjection<ID>[]): Promise<void>;
+}
+/**
+ * Configuration for entity projection behavior.
+ */
+export interface EntityProjectionConfig {
+    /** Include task payload in projection (default: false for performance) */
+    includePayload?: boolean;
+}
+/**
+ * Sync entity projections to the provider. Non-fatal — logs and continues on error.
+ */
+export declare function syncProjections<ID>(projections: EntityTaskProjection<ID>[], provider: IEntityProjectionProvider<ID> | undefined, logger: {
+    error(msg: string): void;
+}): Promise<void>;
+/**
+ * Build a single projection entry from a CronTask and target status.
+ * Returns null if the task has no entity binding.
+ * Throws if entity is present but task has no ID — fail-fast for developer errors.
+ */
+export declare function buildProjection<ID>(task: CronTask<ID>, status: EntityTaskProjectionStatus, options?: {
+    includePayload?: boolean;
+    error?: string;
+    result?: unknown;
+}): EntityTaskProjection<ID> | null;

package/dist/src/core/entity/IEntityProjectionProvider.d.ts

@@ -0,0 +1,45 @@
+import { CronTask } from '../../adapters/types.js';
+export type EntityTaskProjectionStatus = 'scheduled' | 'processing' | 'executed' | 'failed';
+export interface EntityTaskProjection<ID = any> {
+    task_id: ID;
+    entity_id: string;
+    entity_type: string;
+    task_type: string;
+    queue_id: string;
+    status: EntityTaskProjectionStatus;
+    payload?: unknown;
+    error?: string;
+    result?: unknown;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Provider interface for persisting entity-task projections.
+ * Implementations might write to a database table, cache, or external service.
+ */
+export interface IEntityProjectionProvider<ID = any> {
+    upsertProjections(entries: EntityTaskProjection<ID>[]): Promise<void>;
+}
+/**
+ * Configuration for entity projection behavior.
+ */
+export interface EntityProjectionConfig {
+    /** Include task payload in projection (default: false for performance) */
+    includePayload?: boolean;
+}
+/**
+ * Sync entity projections to the provider. Non-fatal — logs and continues on error.
+ */
+export declare function syncProjections<ID>(projections: EntityTaskProjection<ID>[], provider: IEntityProjectionProvider<ID> | undefined, logger: {
+    error(msg: string): void;
+}): Promise<void>;
+/**
+ * Build a single projection entry from a CronTask and target status.
+ * Returns null if the task has no entity binding.
+ * Throws if entity is present but task has no ID — fail-fast for developer errors.
+ */
+export declare function buildProjection<ID>(task: CronTask<ID>, status: EntityTaskProjectionStatus, options?: {
+    includePayload?: boolean;
+    error?: string;
+    result?: unknown;
+}): EntityTaskProjection<ID> | null;

package/dist/src/core/entity/index.d.cts

@@ -0,0 +1 @@
+export * from './IEntityProjectionProvider.js';

package/dist/src/core/entity/index.d.ts

@@ -0,0 +1 @@
+export * from './IEntityProjectionProvider.js';

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

@@ -0,0 +1,26 @@
+import { CronTask } from '../../adapters/types.js';
+import { IFlowBarrierProvider } from './IFlowBarrierProvider.js';
+import { EntityTaskProjection } from '../entity/IEntityProjectionProvider.js';
+export interface FlowPostProcessInput<ID> {
+    successTasks: CronTask<ID>[];
+    failedTasks: CronTask<ID>[];
+}
+export interface FlowPostProcessResult<ID> {
+    joinTasks: CronTask<ID>[];
+    projections: EntityTaskProjection<ID>[];
+}
+export declare class FlowMiddleware<ID> {
+    private readonly barrierProvider;
+    private readonly generateId;
+    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID);
+    /**
+     * Process completed tasks for flow orchestration.
+     * Called from TaskHandler.postProcessTasks after markFailed/markSuccess.
+     *
+     * @param input Categorized terminal tasks — success and final-failed (no retries left)
+     * @returns Join tasks to dispatch and entity projections to sync
+     */
+    onPostProcess(input: FlowPostProcessInput<ID>): Promise<FlowPostProcessResult<ID>>;
+    private buildStepResults;
+    private buildJoinTask;
+}

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

@@ -0,0 +1,26 @@
+import { CronTask } from '../../adapters/types.js';
+import { IFlowBarrierProvider } from './IFlowBarrierProvider.js';
+import { EntityTaskProjection } from '../entity/IEntityProjectionProvider.js';
+export interface FlowPostProcessInput<ID> {
+    successTasks: CronTask<ID>[];
+    failedTasks: CronTask<ID>[];
+}
+export interface FlowPostProcessResult<ID> {
+    joinTasks: CronTask<ID>[];
+    projections: EntityTaskProjection<ID>[];
+}
+export declare class FlowMiddleware<ID> {
+    private readonly barrierProvider;
+    private readonly generateId;
+    constructor(barrierProvider: IFlowBarrierProvider, generateId: () => ID);
+    /**
+     * Process completed tasks for flow orchestration.
+     * Called from TaskHandler.postProcessTasks after markFailed/markSuccess.
+     *
+     * @param input Categorized terminal tasks — success and final-failed (no retries left)
+     * @returns Join tasks to dispatch and entity projections to sync
+     */
+    onPostProcess(input: FlowPostProcessInput<ID>): Promise<FlowPostProcessResult<ID>>;
+    private buildStepResults;
+    private buildJoinTask;
+}

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

@@ -0,0 +1,46 @@
+import { FlowStepResult } from './types.js';
+/** Result of a batchDecrementAndCheck call */
+export interface BarrierDecrementResult {
+    /**
+     * Number of steps remaining after this decrement.
+     * 0 = barrier met (all steps done).
+     * -1 = flow was already aborted or completed (late arrival).
+     */
+    remaining: number;
+}
+/**
+ * Provider interface for flow barrier operations.
+ * Implementations must guarantee HSETNX-style dedup:
+ * a step_index can only decrement the counter once.
+ */
+export interface IFlowBarrierProvider {
+    /**
+     * Initialize a barrier for a new flow.
+     * @param flowId Unique flow identifier
+     * @param totalSteps Total number of steps to wait for
+     */
+    initBarrier(flowId: string, totalSteps: number): Promise<void>;
+    /**
+     * Record step results and decrement the barrier.
+     * Uses HSETNX semantics: duplicate step_index submissions are ignored
+     * (counter only decrements by the number of genuinely new steps).
+     *
+     * @param flowId Flow identifier
+     * @param results Step results to record
+     * @returns remaining count (0 = complete, -1 = aborted/already complete)
+     */
+    batchDecrementAndCheck(flowId: string, results: FlowStepResult[]): Promise<BarrierDecrementResult>;
+    /**
+     * Get all recorded step results for a flow.
+     */
+    getStepResults(flowId: string): Promise<FlowStepResult[]>;
+    /**
+     * Mark a flow as aborted. Returns true if this is the first abort call.
+     * Subsequent calls return false (idempotent).
+     */
+    markAborted(flowId: string): Promise<boolean>;
+    /**
+     * Check if a flow's barrier has been fully met (remaining = 0).
+     */
+    isComplete(flowId: string): Promise<boolean>;
+}

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

@@ -0,0 +1,46 @@
+import { FlowStepResult } from './types.js';
+/** Result of a batchDecrementAndCheck call */
+export interface BarrierDecrementResult {
+    /**
+     * Number of steps remaining after this decrement.
+     * 0 = barrier met (all steps done).
+     * -1 = flow was already aborted or completed (late arrival).
+     */
+    remaining: number;
+}
+/**
+ * Provider interface for flow barrier operations.
+ * Implementations must guarantee HSETNX-style dedup:
+ * a step_index can only decrement the counter once.
+ */
+export interface IFlowBarrierProvider {
+    /**
+     * Initialize a barrier for a new flow.
+     * @param flowId Unique flow identifier
+     * @param totalSteps Total number of steps to wait for
+     */
+    initBarrier(flowId: string, totalSteps: number): Promise<void>;
+    /**
+     * Record step results and decrement the barrier.
+     * Uses HSETNX semantics: duplicate step_index submissions are ignored
+     * (counter only decrements by the number of genuinely new steps).
+     *
+     * @param flowId Flow identifier
+     * @param results Step results to record
+     * @returns remaining count (0 = complete, -1 = aborted/already complete)
+     */
+    batchDecrementAndCheck(flowId: string, results: FlowStepResult[]): Promise<BarrierDecrementResult>;
+    /**
+     * Get all recorded step results for a flow.
+     */
+    getStepResults(flowId: string): Promise<FlowStepResult[]>;
+    /**
+     * Mark a flow as aborted. Returns true if this is the first abort call.
+     * Subsequent calls return false (idempotent).
+     */
+    markAborted(flowId: string): Promise<boolean>;
+    /**
+     * Check if a flow's barrier has been fully met (remaining = 0).
+     */
+    isComplete(flowId: string): Promise<boolean>;
+}

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

@@ -0,0 +1,10 @@
+import { FlowStepResult } from './types.js';
+import { BarrierDecrementResult, IFlowBarrierProvider } from './IFlowBarrierProvider.js';
+export declare class InMemoryFlowBarrierProvider implements IFlowBarrierProvider {
+    private readonly barriers;
+    initBarrier(flowId: string, totalSteps: number): Promise<void>;
+    batchDecrementAndCheck(flowId: string, results: FlowStepResult[]): Promise<BarrierDecrementResult>;
+    getStepResults(flowId: string): Promise<FlowStepResult[]>;
+    markAborted(flowId: string): Promise<boolean>;
+    isComplete(flowId: string): Promise<boolean>;
+}

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

@@ -0,0 +1,10 @@
+import { FlowStepResult } from './types.js';
+import { BarrierDecrementResult, IFlowBarrierProvider } from './IFlowBarrierProvider.js';
+export declare class InMemoryFlowBarrierProvider implements IFlowBarrierProvider {
+    private readonly barriers;
+    initBarrier(flowId: string, totalSteps: number): Promise<void>;
+    batchDecrementAndCheck(flowId: string, results: FlowStepResult[]): Promise<BarrierDecrementResult>;
+    getStepResults(flowId: string): Promise<FlowStepResult[]>;
+    markAborted(flowId: string): Promise<boolean>;
+    isComplete(flowId: string): Promise<boolean>;
+}

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

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './IFlowBarrierProvider.js';
+export * from './InMemoryFlowBarrierProvider.js';
+export * from './FlowMiddleware.js';

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

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './IFlowBarrierProvider.js';
+export * from './InMemoryFlowBarrierProvider.js';
+export * from './FlowMiddleware.js';

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

@@ -0,0 +1,82 @@
+/**
+ * RFC-002: Flow Orchestration Types
+ *
+ * Fan-out/fan-in flow orchestration for task queues.
+ * An executor calls actions.startFlow(steps, config) to dispatch N parallel
+ * step tasks, a barrier tracks their completion, and a join task is dispatched
+ * when all steps finish.
+ */
+/** Metadata attached to step/join/timeout tasks via metadata.flow_meta */
+export interface FlowMeta {
+    /** Unique identifier for this flow instance */
+    flow_id: string;
+    /** Index of this step within the flow (0-based) */
+    step_index: number;
+    /** Total number of steps in the flow */
+    total_steps: number;
+    /** Join task configuration — dispatched when barrier is met */
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    /** What happens when a step fails */
+    failure_policy: 'continue' | 'abort';
+    /** True on the join task itself */
+    is_join?: boolean;
+    /** True on timeout sentinel tasks */
+    is_timeout?: boolean;
+    /** Entity binding for flow-level projection */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Result of a single flow step, stored in the barrier */
+export interface FlowStepResult {
+    step_index: number;
+    status: 'success' | 'fail';
+    result?: unknown;
+    error?: string;
+}
+/** Aggregated results delivered to the join task via payload.flow_results */
+export interface FlowResults {
+    flow_id: string;
+    steps: FlowStepResult[];
+    /** True if the flow was aborted due to failure_policy: 'abort' */
+    aborted?: boolean;
+    /** True if the flow timed out before all steps completed */
+    timed_out?: boolean;
+}
+/** A single step in a flow */
+export interface FlowStep {
+    type: string;
+    queue_id: string;
+    payload: unknown;
+    /** Optional entity binding for this step */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Configuration for startFlow */
+export interface StartFlowConfig {
+    /** Join task configuration */
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    /** What happens when a step fails: 'continue' (default) or 'abort' */
+    failure_policy?: 'continue' | 'abort';
+    /** Optional timeout in ms — dispatches a sentinel task */
+    timeout_ms?: number;
+    /** Optional entity binding for flow-level projection (task_id = flow_id) */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Input to actions.startFlow() */
+export interface StartFlowInput {
+    steps: FlowStep[];
+    config: StartFlowConfig;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * RFC-002: Flow Orchestration Types
+ *
+ * Fan-out/fan-in flow orchestration for task queues.
+ * An executor calls actions.startFlow(steps, config) to dispatch N parallel
+ * step tasks, a barrier tracks their completion, and a join task is dispatched
+ * when all steps finish.
+ */
+/** Metadata attached to step/join/timeout tasks via metadata.flow_meta */
+export interface FlowMeta {
+    /** Unique identifier for this flow instance */
+    flow_id: string;
+    /** Index of this step within the flow (0-based) */
+    step_index: number;
+    /** Total number of steps in the flow */
+    total_steps: number;
+    /** Join task configuration — dispatched when barrier is met */
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    /** What happens when a step fails */
+    failure_policy: 'continue' | 'abort';
+    /** True on the join task itself */
+    is_join?: boolean;
+    /** True on timeout sentinel tasks */
+    is_timeout?: boolean;
+    /** Entity binding for flow-level projection */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Result of a single flow step, stored in the barrier */
+export interface FlowStepResult {
+    step_index: number;
+    status: 'success' | 'fail';
+    result?: unknown;
+    error?: string;
+}
+/** Aggregated results delivered to the join task via payload.flow_results */
+export interface FlowResults {
+    flow_id: string;
+    steps: FlowStepResult[];
+    /** True if the flow was aborted due to failure_policy: 'abort' */
+    aborted?: boolean;
+    /** True if the flow timed out before all steps completed */
+    timed_out?: boolean;
+}
+/** A single step in a flow */
+export interface FlowStep {
+    type: string;
+    queue_id: string;
+    payload: unknown;
+    /** Optional entity binding for this step */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Configuration for startFlow */
+export interface StartFlowConfig {
+    /** Join task configuration */
+    join: {
+        type: string;
+        queue_id: string;
+    };
+    /** What happens when a step fails: 'continue' (default) or 'abort' */
+    failure_policy?: 'continue' | 'abort';
+    /** Optional timeout in ms — dispatches a sentinel task */
+    timeout_ms?: number;
+    /** Optional entity binding for flow-level projection (task_id = flow_id) */
+    entity?: {
+        id: string;
+        type: string;
+    };
+}
+/** Input to actions.startFlow() */
+export interface StartFlowInput {
+    steps: FlowStep[];
+    config: StartFlowConfig;
+}

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

@@ -1,7 +1,4 @@
-/**
- * Task Queue Lifecycle Types
- * Provides interfaces for task and worker lifecycle callbacks
- */
+import { EntityProjectionConfig, IEntityProjectionProvider } from './entity/IEntityProjectionProvider.js';
 export interface TaskContext {
     /** Unique task identifier */
     task_id: string;
@@ -21,6 +18,8 @@ export interface TaskContext {
     scheduled_at: Date;
     /** Worker processing this task */
     worker_id?: string;
+    /** User-provided log correlation context (RFC-005) */
+    log_context?: Record<string, string>;
 }
 export interface TaskTiming {
     /** Time spent waiting in queue (ms) */
@@ -130,4 +129,10 @@ export interface TaskHandlerConfig {
     workerProvider?: IWorkerLifecycleProvider;
     /** Lifecycle callback configuration */
     lifecycle?: TaskHandlerLifecycleConfig;
+    /** RFC-003: Entity-task projection provider */
+    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>;
 }

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

@@ -1,7 +1,4 @@
-/**
- * Task Queue Lifecycle Types
- * Provides interfaces for task and worker lifecycle callbacks
- */
+import { EntityProjectionConfig, IEntityProjectionProvider } from './entity/IEntityProjectionProvider.js';
 export interface TaskContext {
     /** Unique task identifier */
     task_id: string;
@@ -21,6 +18,8 @@ export interface TaskContext {
     scheduled_at: Date;
     /** Worker processing this task */
     worker_id?: string;
+    /** User-provided log correlation context (RFC-005) */
+    log_context?: Record<string, string>;
 }
 export interface TaskTiming {
     /** Time spent waiting in queue (ms) */
@@ -130,4 +129,10 @@ export interface TaskHandlerConfig {
     workerProvider?: IWorkerLifecycleProvider;
     /** Lifecycle callback configuration */
     lifecycle?: TaskHandlerLifecycleConfig;
+    /** RFC-003: Entity-task projection provider */
+    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>;
 }

package/dist/src/core/log-context.d.cts

@@ -0,0 +1,10 @@
+export type LogStore = Record<string, string>;
+/**
+ * Run a function within an ALS scope carrying the given log context store.
+ * The store is available via getLogContext() inside the callback and cleared after.
+ */
+export declare function runWithLogContext<T>(store: LogStore, fn: () => T): T;
+/**
+ * Read the current ALS log context store (undefined outside a runWithLogContext scope).
+ */
+export declare function getLogContext(): LogStore | undefined;

package/dist/src/core/log-context.d.ts

@@ -0,0 +1,10 @@
+export type LogStore = Record<string, string>;
+/**
+ * Run a function within an ALS scope carrying the given log context store.
+ * The store is available via getLogContext() inside the callback and cleared after.
+ */
+export declare function runWithLogContext<T>(store: LogStore, fn: () => T): T;
+/**
+ * Read the current ALS log context store (undefined outside a runWithLogContext scope).
+ */
+export declare function getLogContext(): LogStore | undefined;