/**
 * Canonical SQLite Pipeline State Machine
 *
 * Main pipeline operations for the unified RCASD-IVTR+C lifecycle.
 * Replaces the scattered _manifest.json approach with a transactional
 * Drizzle ORM implementation using tasks.db.
 *
 * Pipeline Stages (9 stages):
 *   Research → Consensus → ADR → Spec → Decompose → Implement → Verify → Test → Release
 *
 * @task T4800 - Implement Canonical SQLite Pipeline State Machine
 * @epic T4798 - Lifecycle persistence improvements
 * @audit T4799 - Three incompatible implementations unified
 * @depends T4801 - Schema design (lifecycle_pipelines, pipeline_stages tables)
 * @task T4912 - Pipeline Validation & Tests (SQLite wiring implementation)
 */
import type { PipelineStatus } from '@cleocode/contracts';
import type { Stage, StageStatus } from './stages.js';
/**
 * Pipeline entity representing a task's lifecycle state.
 *
 * @task T4800
 * @audit T4799 - Unified pipeline structure replaces scattered manifests
 */
export interface Pipeline {
    /** Unique identifier (task ID format: T####) */
    id: string;
    /** Current stage in the pipeline */
    currentStage: Stage;
    /** When the pipeline was created */
    createdAt: Date;
    /** When the pipeline was last updated */
    updatedAt: Date;
    /** Overall pipeline status */
    status: PipelineStatus;
    /** Whether the pipeline is currently active (not completed/cancelled) */
    isActive: boolean;
    /** When the pipeline completed (if applicable) */
    completedAt?: Date;
    /** Cancellation reason (if cancelled) */
    cancelledReason?: string;
    /** Number of stage transitions made */
    transitionCount: number;
    /** Version for optimistic locking */
    version: number;
}
export type { PipelineStatus };
/**
 * Pipeline stage record linking pipeline to individual stages.
 *
 * @task T4800
 * @depends T4801 - Requires pipeline_stages table
 */
export interface PipelineStageRecord {
    /** Unique identifier */
    id?: string;
    /** Reference to the pipeline */
    pipelineId: string;
    /** Stage name */
    stage: Stage;
    /** Stage status */
    status: StageStatus;
    /** When the stage was started */
    startedAt?: Date;
    /** When the stage was completed */
    completedAt?: Date;
    /** Stage duration in milliseconds (computed) */
    durationMs?: number;
    /** Assigned agent for this stage */
    assignedAgent?: string;
    /** Stage-specific metadata/notes */
    notes?: string;
    /** Stage order in pipeline */
    order: number;
}
/**
 * Pipeline transition record for audit trail.
 *
 * @task T4800
 * @depends T4801 - Requires pipeline_transitions table
 */
export interface PipelineTransition {
    /** Unique identifier */
    id?: string;
    /** Pipeline reference */
    pipelineId: string;
    /** From stage */
    fromStage: Stage;
    /** To stage */
    toStage: Stage;
    /** When the transition occurred */
    transitionedAt: Date;
    /** Agent/user who initiated the transition */
    transitionedBy: string;
    /** Reason for the transition */
    reason?: string;
    /** Whether prerequisites were checked */
    prerequisitesChecked: boolean;
    /** Any validation errors that occurred */
    validationErrors?: string[];
}
/**
 * Options for initializing a pipeline.
 *
 * @task T4800
 */
export interface InitializePipelineOptions {
    /** Starting stage (defaults to 'research') */
    startStage?: Stage;
    /** Initial status (defaults to 'active') */
    initialStatus?: PipelineStatus;
    /** Assigning agent */
    assignedAgent?: string;
}
/**
 * Options for advancing pipeline stage.
 *
 * @task T4800
 */
export interface AdvanceStageOptions {
    /** Target stage to advance to */
    toStage: Stage;
    /** Reason for the advancement */
    reason?: string;
    /** Agent/user initiating the transition */
    initiatedBy: string;
    /** Whether to skip prerequisite check (emergency only) */
    skipPrerequisites?: boolean;
    /** Whether to force transition even if blocked */
    force?: boolean;
}
/**
 * Pipeline query options.
 *
 * @task T4800
 */
export interface PipelineQueryOptions {
    /** Filter by status */
    status?: PipelineStatus;
    /** Filter by current stage */
    currentStage?: Stage;
    /** Filter by active state */
    isActive?: boolean;
    /** Limit results */
    limit?: number;
    /** Offset for pagination */
    offset?: number;
    /** Order by (default: createdAt desc) */
    orderBy?: 'createdAt' | 'updatedAt' | 'currentStage';
    /** Order direction */
    order?: 'asc' | 'desc';
}
/**
 * Initialize a new pipeline for a task.
 *
 * Creates a new pipeline record in the database with all 9 stages initialized
 * to 'not_started' status. The pipeline starts at the research stage by default.
 *
 * @param taskId - The task ID (e.g., 'T4800')
 * @param options - Optional configuration
 * @throws {CleoError} If pipeline already exists or database operation fails
 * @returns Promise resolving to the created Pipeline
 *
 * @example
 * ```typescript
 * const pipeline = await initializePipeline('T4800', {
 *   startStage: 'research',
 *   assignedAgent: 'agent-001'
 * });
 * console.log(`Pipeline initialized: ${pipeline.id}`);
 * ```
 *
 * @task T4800
 * @audit T4799 - Replaces scattered _manifest.json creation
 * @task T4912 - Implemented SQLite wiring
 */
export declare function initializePipeline(taskId: string, options?: InitializePipelineOptions): Promise<Pipeline>;
/**
 * Retrieve a pipeline by task ID.
 *
 * Returns the complete pipeline state including current stage and status.
 * Returns null if no pipeline exists for the given task ID.
 *
 * @param taskId - The task ID (e.g., 'T4800')
 * @throws {CleoError} If database query fails
 * @returns Promise resolving to Pipeline or null
 *
 * @example
 * ```typescript
 * const pipeline = await getPipeline('T4800');
 * if (pipeline) {
 *   console.log(`Current stage: ${pipeline.currentStage}`);
 * }
 * ```
 *
 * @task T4800
 * @audit T4799 - Replaces JSON manifest reading
 * @task T4912 - Implemented SQLite wiring
 */
export declare function getPipeline(taskId: string): Promise<Pipeline | null>;
/**
 * Advance a pipeline to the next stage.
 *
 * Performs atomic stage transition with prerequisite checking and audit logging.
 * Validates the transition is allowed, updates stage statuses, and records
 * the transition in the audit trail.
 *
 * @param taskId - The task ID
 * @param options - Advance options including target stage and reason
 * @throws {CleoError} If transition is invalid or prerequisites not met
 * @returns Promise resolving when transition is complete
 *
 * @example
 * ```typescript
 * await advanceStage('T4800', {
 *   toStage: 'consensus',
 *   reason: 'Research completed, moving to consensus',
 *   initiatedBy: 'agent-001'
 * });
 * ```
 *
 * @task T4800
 * @audit T4799 - Replaces manual manifest updates with transactional approach
 * @task T4912 - Implemented SQLite wiring
 */
export declare function advanceStage(taskId: string, options: AdvanceStageOptions): Promise<void>;
/**
 * Get the current stage of a pipeline.
 *
 * Convenience method to quickly check which stage a task is currently in.
 *
 * @param taskId - The task ID
 * @throws {CleoError} If database query fails
 * @returns Promise resolving to the current Stage
 *
 * @example
 * ```typescript
 * const currentStage = await getCurrentStage('T4800');
 * if (currentStage === 'validation') {
 *   console.log('Task is in verification');
 * }
 * ```
 *
 * @task T4800
 * @audit T4799 - Replaces JSON manifest stage lookup
 * @task T4912 - Implemented SQLite wiring
 */
export declare function getCurrentStage(taskId: string): Promise<Stage>;
/**
 * List pipelines with optional filtering.
 *
 * @param options - Query options for filtering and pagination
 * @throws {CleoError} If database query fails
 * @returns Promise resolving to array of Pipelines
 *
 * @example
 * ```typescript
 * const activePipelines = await listPipelines({
 *   status: 'active',
 *   limit: 10
 * });
 * ```
 *
 * @task T4800
 * @task T4912 - Implemented SQLite wiring
 */
export declare function listPipelines(options?: PipelineQueryOptions): Promise<Pipeline[]>;
/**
 * Complete a pipeline (mark all stages done).
 *
 * Marks the pipeline as completed and sets the completion timestamp.
 * Only valid when the pipeline is in the 'release' stage.
 *
 * @param taskId - The task ID
 * @param reason - Optional completion reason, stored in the final stage's notes
 * @throws {CleoError} If pipeline not found or not in releasable state
 * @returns Promise resolving when complete
 *
 * @task T4800
 * @task T4912 - Implemented SQLite wiring
 */
export declare function completePipeline(taskId: string, reason?: string): Promise<void>;
/**
 * Cancel a pipeline before completion.
 *
 * Marks the pipeline as cancelled (user-initiated). Once cancelled,
 * the pipeline cannot be resumed (a new one must be created).
 * Use this for deliberate user decisions to abandon a pipeline.
 * System-forced terminations should use the 'aborted' status directly.
 *
 * @param taskId - The task ID
 * @param reason - Reason for cancellation
 * @throws {CleoError} If pipeline not found or already completed
 * @returns Promise resolving when cancelled
 *
 * @task T4800
 * @task T4912 - Implemented SQLite wiring
 */
export declare function cancelPipeline(taskId: string, reason: string): Promise<void>;
/**
 * Check if a pipeline exists for a task.
 *
 * @param taskId - The task ID
 * @returns Promise resolving to boolean
 *
 * @task T4800
 * @task T4912 - Implemented SQLite wiring
 */
export declare function pipelineExists(taskId: string): Promise<boolean>;
/**
 * Get pipeline statistics.
 *
 * Returns aggregate counts of pipelines by status and stage.
 *
 * @throws {CleoError} If database query fails
 * @returns Promise resolving to statistics object
 *
 * @task T4800
 * @task T4912 - Implemented SQLite wiring
 */
export declare function getPipelineStatistics(): Promise<{
    total: number;
    byStatus: Record<PipelineStatus, number>;
    byStage: Partial<Record<Stage, number>>;
}>;
/**
 * Get all stages for a pipeline.
 *
 * @param taskId - The task ID
 * @returns Promise resolving to array of stage records
 *
 * @task T4912
 */
export declare function getPipelineStages(taskId: string): Promise<PipelineStageRecord[]>;
//# sourceMappingURL=pipeline.d.ts.map