diff --git a/src/dispatch/types.ts b/src/dispatch/types.ts index 137774f..4d5fb65 100644 --- a/src/dispatch/types.ts +++ b/src/dispatch/types.ts @@ -1,8 +1,8 @@ /** * Dispatch Module Types * - * Port interface for task dispatch management. - * DispatchManager is the PORT. Implementations are ADAPTERS. + * Port interfaces for task and phase dispatch management. + * DispatchManager and PhaseDispatchManager are PORTS. Implementations are ADAPTERS. * * This follows the same hexagonal architecture pattern as EventBus and AgentManager: * - Interface defines the contract (port) @@ -116,3 +116,107 @@ export interface DispatchManager { blocked: Array<{ taskId: string; reason: string }>; }>; } + +// ============================================================================= +// Phase Dispatch Domain Types +// ============================================================================= + +/** + * Represents a phase queued for dispatch. + * Phases are dispatched when all dependencies complete. + */ +export interface QueuedPhase { + /** Unique identifier for the phase */ + phaseId: string; + /** Initiative this phase belongs to */ + initiativeId: string; + /** When the phase was queued */ + queuedAt: Date; + /** Phase IDs that must complete before this phase can be dispatched */ + dependsOn: string[]; +} + +/** + * Result of a phase dispatch operation. + * Success means phase was dispatched; failure means dispatch couldn't happen. + */ +export interface PhaseDispatchResult { + /** Whether the phase was successfully dispatched */ + success: boolean; + /** ID of the phase that was dispatched */ + phaseId: string; + /** Reason why dispatch failed (only present on failure) */ + reason?: string; +} + +// ============================================================================= +// PhaseDispatchManager Port Interface +// ============================================================================= + +/** + * PhaseDispatchManager Port Interface + * + * Manages phase dispatch queue with dependency ordering. + * Enables queuing and dispatching phases based on their dependencies. + * + * Follows exact patterns from DispatchManager for tasks. + */ +export interface PhaseDispatchManager { + /** + * Queue a phase for dispatch. + * Phase will be dispatched when all dependencies complete. + * + * @param phaseId - ID of the phase to queue + */ + queuePhase(phaseId: string): Promise; + + /** + * Get next dispatchable phase. + * Returns phase with all dependencies complete. + * Returns null if no phases ready. + * + * @returns Next dispatchable phase or null + */ + getNextDispatchablePhase(): Promise; + + /** + * Dispatch next available phase. + * Finds next ready phase and dispatches it. + * Returns dispatch result. + * + * @returns Result of the dispatch operation + */ + dispatchNextPhase(): Promise; + + /** + * Mark a phase as complete. + * Triggers re-evaluation of dependent phases. + * + * @param phaseId - ID of the completed phase + */ + completePhase(phaseId: string): Promise; + + /** + * Mark a phase as blocked. + * Phase will not be dispatched until unblocked. + * + * @param phaseId - ID of the phase to block + * @param reason - Reason for blocking + */ + blockPhase(phaseId: string, reason: string): Promise; + + /** + * Get current phase queue state. + * Returns all queued phases with their dispatch readiness. + * + * @returns Queue state with queued, ready, and blocked phases + */ + getPhaseQueueState(): Promise<{ + /** All queued phases */ + queued: QueuedPhase[]; + /** Phases ready for dispatch (all dependencies complete) */ + ready: QueuedPhase[]; + /** Phases that are blocked */ + blocked: Array<{ phaseId: string; reason: string }>; + }>; +}