/**
 * Pipeline State Machine - Core Logic
 *
 * Implements the finite state machine for pipeline lifecycle management.
 * Handles state transitions, prerequisite validation, and transition history.
 *
 * State Machine States:
 *   not_started → in_progress → completed
 *                        ↓
 *                   blocked/failed
 *                        ↓
 *                    skipped
 *
 * @task T4800 - Implement Canonical SQLite Pipeline State Machine
 * @epic T4798 - Lifecycle persistence improvements
 * @audit T4799 - Unified state machine replaces scattered logic
 * @depends T4801 - Schema design
 * @depends stages.ts - Stage definitions and transition rules
 */
import type { Stage, StageStatus } from './stages.js';
/**
 * Prerequisite check result.
 *
 * @task T4800
 */
export interface PrereqCheck {
    /** Whether all prerequisites are met */
    met: boolean;
    /** List of prerequisite stages */
    prerequisites: Stage[];
    /** Stages that are completed or skipped */
    completed: Stage[];
    /** Stages that are pending or blocked */
    pending: Stage[];
    /** Stages that failed */
    failed: Stage[];
    /** Blocking issues preventing progression */
    blockers: Array<{
        stage: Stage;
        reason: string;
        severity: 'error' | 'warning' | 'info';
    }>;
    /** Whether the check can be overridden with force */
    canForce: boolean;
    /** Human-readable summary */
    summary: string;
}
/**
 * Transition validation result.
 *
 * @task T4800
 */
export interface TransitionValidation {
    /** Whether the transition is valid */
    valid: boolean;
    /** Source stage */
    from: Stage;
    /** Target stage */
    to: Stage;
    /** Whether prerequisites are met */
    prerequisitesMet: boolean;
    /** Whether the transition rule allows it */
    ruleAllowed: boolean;
    /** Whether force is required */
    requiresForce: boolean;
    /** List of validation errors */
    errors: string[];
    /** List of warnings */
    warnings: string[];
    /** Prerequisite check details */
    prereqCheck?: PrereqCheck;
}
/**
 * Stage state snapshot for state machine.
 *
 * @task T4800
 */
export interface StageState {
    stage: Stage;
    status: StageStatus;
    startedAt?: Date;
    completedAt?: Date;
    assignedAgent?: string;
    notes?: string;
}
/**
 * State machine context for a pipeline.
 *
 * @task T4800
 */
export interface StateMachineContext {
    pipelineId: string;
    currentStage: Stage;
    stages: Record<Stage, StageState>;
    transitionCount: number;
    version: number;
}
/**
 * State transition request.
 *
 * @task T4800
 */
export interface StateTransition {
    from: Stage;
    to: Stage;
    reason?: string;
    initiatedBy: string;
    force?: boolean;
    skipValidation?: boolean;
}
/**
 * State transition result.
 *
 * @task T4800
 */
export interface StateTransitionResult {
    success: boolean;
    transition: StateTransition;
    previousState: StageState;
    newState: StageState;
    context: StateMachineContext;
    timestamp: Date;
    errors?: string[];
}
/**
 * Check if prerequisites are met for a stage.
 *
 * Validates that all prerequisite stages are in an acceptable state
 * (completed or skipped) for the target stage to proceed.
 *
 * @param targetStage - The stage to check prerequisites for
 * @param currentStages - Current state of all stages
 * @throws {CleoError} If validation fails
 * @returns Promise resolving to PrereqCheck result
 *
 * @example
 * ```typescript
 * const check = await checkPrerequisites('implement', {
 *   research: { status: 'completed' },
 *   spec: { status: 'completed' },
 *   decompose: { status: 'completed' },
 *   // ... other stages
 * });
 * if (check.met) {
 *   console.log('Ready to implement');
 * }
 * ```
 *
 * @task T4800
 * @depends T4801 - Requires pipeline_stages table
 */
export declare function checkPrerequisites(targetStage: Stage, currentStages: Record<Stage, StageState>): Promise<PrereqCheck>;
/**
 * Validate a stage transition.
 *
 * Comprehensive validation that checks both transition rules and prerequisites.
 * This is the core state machine validation logic.
 *
 * @param transition - The transition to validate
 * @param context - Current state machine context
 * @throws {CleoError} If validation fails unexpectedly
 * @returns Promise resolving to TransitionValidation
 *
 * @example
 * ```typescript
 * const validation = await validateTransition(
 *   { from: 'spec', to: 'implement', initiatedBy: 'agent-001' },
 *   pipelineContext
 * );
 * if (!validation.valid) {
 *   console.log(validation.errors);
 * }
 * ```
 *
 * @task T4800
 */
export declare function validateTransition(transition: StateTransition, context: StateMachineContext): Promise<TransitionValidation>;
/**
 * Execute a state transition.
 *
 * Applies the transition to the state machine context, updating stage statuses
 * and returning the new state. This function does NOT persist to database -
 * that is handled by the pipeline module.
 *
 * @param transition - The transition to execute
 * @param context - Current state machine context
 * @throws {CleoError} If transition is invalid
 * @returns Promise resolving to StateTransitionResult
 *
 * @example
 * ```typescript
 * const result = await executeTransition(
 *   { from: 'spec', to: 'implement', initiatedBy: 'agent-001' },
 *   pipelineContext
 * );
 * if (result.success) {
 *   console.log(`Transitioned to ${result.newState.stage}`);
 * }
 * ```
 *
 * @task T4800
 */
export declare function executeTransition(transition: StateTransition, context: StateMachineContext): Promise<StateTransitionResult>;
/**
 * Set the status of a stage.
 *
 * Updates stage status with validation of allowed state transitions.
 *
 * @param stage - The stage to update
 * @param status - The new status
 * @param context - Current state machine context
 * @throws {CleoError} If status transition is invalid
 * @returns Updated StageState
 *
 * @task T4800
 */
export declare function setStageStatus(stage: Stage, status: StageStatus, context: StateMachineContext): StageState;
/**
 * Get the status of a stage.
 *
 * @param stage - The stage to check
 * @param context - Current state machine context
 * @returns The stage status
 *
 * @task T4800
 */
export declare function getStageStatus(stage: Stage, context: StateMachineContext): StageStatus;
/**
 * Check if a status transition is valid.
 *
 * State transitions:
 *   not_started → in_progress, skipped
 *   in_progress → completed, blocked, failed
 *   blocked     → in_progress
 *   failed      → in_progress (retry)
 *   completed   → (no transition - use force to override)
 *   skipped     → (no transition)
 *
 * @param from - Current status
 * @param to - Target status
 * @returns Object with valid flag and reason
 *
 * @task T4800
 */
export declare function isValidStatusTransition(from: StageStatus, to: StageStatus): {
    valid: boolean;
    reason?: string;
};
/**
 * Create initial state machine context for a pipeline.
 *
 * @param pipelineId - The pipeline/task ID
 * @param assignedAgent - Optional agent to assign
 * @returns Initial StateMachineContext
 *
 * @task T4800
 */
export declare function createInitialContext(pipelineId: string, assignedAgent?: string): StateMachineContext;
/**
 * Get stages that can be transitioned to from the current stage.
 *
 * @param context - Current state machine context
 * @param includeForce - Whether to include transitions that require force
 * @returns Array of valid next stages
 *
 * @task T4800
 */
export declare function getValidNextStages(context: StateMachineContext, includeForce?: boolean): Stage[];
/**
 * Get the current stage state.
 *
 * @param context - State machine context
 * @returns Current StageState
 *
 * @task T4800
 */
export declare function getCurrentStageState(context: StateMachineContext): StageState;
/**
 * Check if the pipeline is in a terminal state.
 *
 * @param context - State machine context
 * @returns True if in release stage and completed
 *
 * @task T4800
 */
export declare function isTerminalState(context: StateMachineContext): boolean;
/**
 * Check if the pipeline is blocked.
 *
 * @param context - State machine context
 * @returns True if current stage is blocked
 *
 * @task T4800
 */
export declare function isBlocked(context: StateMachineContext): boolean;
/**
 * Validate multiple transitions.
 *
 * @param transitions - Array of transitions to validate
 * @param context - State machine context
 * @returns Array of validation results
 *
 * @task T4800
 */
export declare function validateTransitions(transitions: StateTransition[], context: StateMachineContext): Promise<TransitionValidation[]>;
/**
 * Check if a stage can be skipped.
 *
 * @param stage - The stage to check
 * @returns True if stage is skippable
 *
 * @task T4800
 */
export declare function canSkipStage(stage: Stage): boolean;
/**
 * Skip a stage with validation.
 *
 * @param stage - The stage to skip
 * @param reason - Reason for skipping
 * @param context - State machine context
 * @throws {CleoError} If stage cannot be skipped
 * @returns Updated StageState
 *
 * @task T4800
 */
export declare function skipStage(stage: Stage, reason: string, context: StateMachineContext): StageState;
//# sourceMappingURL=state-machine.d.ts.map