@cleocode/core 2026.3.42 → 2026.3.43

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * RCASD-IVTR pipeline lifecycle - stage transitions and gate enforcement.
+ *
+ * CANONICAL EXPORTS: `stages.ts` is the single source of truth for stage
+ * definitions, ordering, prerequisites, and transition rules. This file
+ * re-exports canonical types and provides SQLite-native lifecycle operations
+ * backed by `lifecycle_pipelines`, `lifecycle_stages`, and
+ * `lifecycle_gate_results` tables.
+ *
+ * @task T4467
+ * @task T4800 - Unified lifecycle barrel export
+ * @task T4798 - RCASD rename (Phase 1: code-only, no disk paths)
+ * @epic T4454
+ */
+import { LIFECYCLE_STAGE_STATUSES } from '../store/tasks-schema.js';
+export { CONTRIBUTION_STAGE, checkTransition, DECISION_STAGES, DELIVERY_STAGES, EXECUTION_STAGES, FIRST_STAGE, getDependents, getNextStage, getPrerequisites, getPreviousStage, getSkippableStages, getStageOrder, getStagesBetween, getStagesByCategory, isPrerequisite, isStageAfter, isStageBefore, isValidStage, isValidStageStatus, LAST_STAGE, PIPELINE_STAGES, PLANNING_STAGES, STAGE_COUNT, STAGE_DEFINITIONS as CANONICAL_STAGE_DEFINITIONS, STAGE_ORDER, STAGE_PREREQUISITES as CANONICAL_PREREQUISITES, type Stage, type StageCategory, type StageDefinition, type StageStatus, VALIDATION_STAGES, validateStage, } from './stages.js';
+import type { Stage } from './stages.js';
+/** Lifecycle enforcement modes. */
+export type EnforcementMode = 'strict' | 'advisory' | 'off';
+/** Gate data within a stage. */
+export interface GateData {
+    status: 'passed' | 'failed' | 'pending';
+    agent?: string;
+    notes?: string;
+    reason?: string;
+    timestamp?: string;
+}
+/** Stage data in an on-disk manifest. */
+export interface ManifestStageData {
+    status: (typeof LIFECYCLE_STAGE_STATUSES)[number];
+    completedAt?: string;
+    skippedAt?: string;
+    skippedReason?: string;
+    artifacts?: string[];
+    notes?: string;
+    gates?: Record<string, GateData>;
+}
+/**
+ * Canonical RCASD manifest-shaped interface for compatibility payloads.
+ * Lifecycle persistence is SQLite-native; this shape is used for API
+ * responses that present stage+gate state in a manifest-like structure.
+ *
+ * Stage keys use full canonical names matching the DB CHECK constraint:
+ * research, consensus, architecture_decision, specification, decomposition,
+ * implementation, validation, testing, release.
+ *
+ * @task T4798
+ */
+export interface RcasdManifest {
+    epicId: string;
+    title?: string;
+    stages: Record<string, ManifestStageData>;
+}
+/** Gate check result. */
+export interface GateCheckResult {
+    allowed: boolean;
+    mode: EnforcementMode;
+    missingPrerequisites: string[];
+    currentStage: string;
+    message: string;
+}
+/** Stage transition result. */
+export interface StageTransitionResult {
+    epicId: string;
+    stage: string;
+    previousStatus: string;
+    newStatus: string;
+    timestamp: string;
+}
+/**
+ * Get the current lifecycle state for an epic.
+ * @task T4467
+ */
+export declare function getLifecycleState(epicId: string, cwd?: string): Promise<RcasdManifest>;
+/**
+ * Start a lifecycle stage.
+ * @task T4467
+ */
+export declare function startStage(epicId: string, stage: string, cwd?: string): Promise<StageTransitionResult>;
+/**
+ * Complete a lifecycle stage.
+ * @task T4467
+ */
+export declare function completeStage(epicId: string, stage: string, artifacts?: string[], cwd?: string): Promise<StageTransitionResult>;
+/**
+ * Skip a lifecycle stage.
+ * @task T4467
+ */
+export declare function skipStage(epicId: string, stage: string, reason: string, cwd?: string): Promise<StageTransitionResult>;
+/**
+ * Check lifecycle gate before starting a stage.
+ * @task T4467
+ */
+export declare function checkGate(epicId: string, targetStage: string, cwd?: string): Promise<GateCheckResult>;
+/**
+ * Get lifecycle status for an epic from SQLite.
+ * Returns stage progress, current/next stage, and blockers.
+ * @task T4801 - SQLite-native implementation
+ */
+export declare function getLifecycleStatus(epicId: string, cwd?: string): Promise<{
+    epicId: string;
+    title?: string;
+    currentStage: Stage | null;
+    stages: Array<{
+        stage: string;
+        status: string;
+        completedAt?: string;
+        notes?: string;
+        outputFile?: string;
+        provenanceChain?: Record<string, unknown>;
+    }>;
+    nextStage: Stage | null;
+    blockedOn: string[];
+    initialized: boolean;
+}>;
+/** History entry for stage transitions. */
+export interface LifecycleHistoryEntry {
+    stage: string;
+    action: string;
+    timestamp: string;
+    notes?: string;
+}
+/**
+ * Get lifecycle history for an epic.
+ * Returns stage transitions and gate events sorted by timestamp.
+ * SQLite-native implementation - queries lifecycle_stages and lifecycle_gate_results tables.
+ * @task T4785
+ * @task T4801
+ */
+export declare function getLifecycleHistory(epicId: string, cwd?: string): Promise<{
+    epicId: string;
+    history: LifecycleHistoryEntry[];
+}>;
+/**
+ * Get all gate statuses for an epic.
+ * @task T4785
+ */
+export declare function getLifecycleGates(epicId: string, cwd?: string): Promise<Record<string, Record<string, GateData>>>;
+/**
+ * Get prerequisites for a target stage.
+ * Pure data function, no I/O.
+ * @task T4785
+ */
+export declare function getStagePrerequisites(targetStage: string): {
+    prerequisites: string[];
+    stageInfo: {
+        stage: string;
+        name: string;
+        description: string;
+        order: number;
+    } | undefined;
+};
+/**
+ * Check if a stage's prerequisites are met for an epic.
+ * @task T4785
+ */
+export declare function checkStagePrerequisites(epicId: string, targetStage: string, cwd?: string): Promise<{
+    epicId: string;
+    targetStage: string;
+    valid: boolean;
+    canProgress: boolean;
+    missingPrerequisites: string[];
+    issues: Array<{
+        stage: string;
+        severity: string;
+        message: string;
+    }>;
+}>;
+/**
+ * Record a stage status transition (progress/record).
+ * SQLite-native implementation - T4801
+ * @task T4785
+ * @task T4801
+ */
+export declare function recordStageProgress(epicId: string, stage: string, status: string, notes?: string, cwd?: string): Promise<{
+    epicId: string;
+    stage: string;
+    status: string;
+    timestamp: string;
+}>;
+/**
+ * Skip a stage with a reason (engine-compatible).
+ * @task T4785
+ */
+export declare function skipStageWithReason(epicId: string, stage: string, reason: string, cwd?: string): Promise<{
+    epicId: string;
+    stage: string;
+    reason: string;
+    timestamp: string;
+}>;
+/**
+ * Reset a stage to pending (emergency).
+ * @task T4785
+ */
+export declare function resetStage(epicId: string, stage: string, reason: string, cwd?: string): Promise<{
+    epicId: string;
+    stage: string;
+    reason: string;
+}>;
+/**
+ * Mark a gate as passed.
+ * SQLite-native implementation - T4801
+ * @task T4785
+ * @task T4801
+ */
+export declare function passGate(epicId: string, gateName: string, agent?: string, notes?: string, cwd?: string): Promise<{
+    epicId: string;
+    gateName: string;
+    timestamp: string;
+}>;
+/**
+ * Mark a gate as failed.
+ * SQLite-native implementation - T4801
+ * @task T4785
+ * @task T4801
+ */
+export declare function failGate(epicId: string, gateName: string, reason?: string, cwd?: string): Promise<{
+    epicId: string;
+    gateName: string;
+    reason?: string;
+    timestamp: string;
+}>;
+/**
+ * List all epic IDs that have lifecycle data.
+ * @task T4785
+ */
+export declare function listEpicsWithLifecycle(cwd?: string): Promise<string[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/pipeline.d.ts

@@ -0,0 +1,335 @@
+/**
+ * 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 (unused, for API compatibility)
+ * @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

package/dist/lifecycle/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/lifecycle/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMtD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IAEX,oCAAoC;IACpC,YAAY,EAAE,KAAK,CAAC;IAEpB,oCAAoC;IACpC,SAAS,EAAE,IAAI,CAAC;IAEhB,yCAAyC;IACzC,SAAS,EAAE,IAAI,CAAC;IAEhB,8BAA8B;IAC9B,MAAM,EAAE,cAAc,CAAC;IAEvB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAElB,kDAAkD;IAClD,WAAW,CAAC,EAAE,IAAI,CAAC;IAEnB,yCAAyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IAExB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAGD,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IAEnB,iBAAiB;IACjB,KAAK,EAAE,KAAK,CAAC;IAEb,mBAAmB;IACnB,MAAM,EAAE,WAAW,CAAC;IAEpB,iCAAiC;IACjC,SAAS,CAAC,EAAE,IAAI,CAAC;IAEjB,mCAAmC;IACnC,WAAW,CAAC,EAAE,IAAI,CAAC;IAEnB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,iBAAiB;IACjB,SAAS,EAAE,KAAK,CAAC;IAEjB,eAAe;IACf,OAAO,EAAE,KAAK,CAAC;IAEf,mCAAmC;IACnC,cAAc,EAAE,IAAI,CAAC;IAErB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IAEvB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,oBAAoB,EAAE,OAAO,CAAC;IAE9B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,KAAK,CAAC;IAEnB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,cAAc,CAAC;IAE/B,sBAAsB;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,OAAO,EAAE,KAAK,CAAC;IAEf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IAEpB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,KAAK,CAAC;IAErB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;IAErD,sBAAsB;IACtB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,QAAQ,CAAC,CA4EnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAqC1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4H9F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAepE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAoG3F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDlF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;CACzC,CAAC,CA6DD;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiCtF"}