@orbytautomation/engine 0.1.0

package/dist/graph/TopologicalSorter.js

@@ -0,0 +1,213 @@
+/**
+ * TopologicalSorter
+ *
+ * Performs topological sorting on a dependency graph using Kahn's algorithm.
+ * This is what makes parallel execution possible.
+ *
+ * Purpose:
+ * - Convert DAG into execution phases
+ * - Group independent steps into phases (parallelization!)
+ * - Ensure dependencies are satisfied before execution
+ * - This is "the moment Orbyt becomes real" - we go from sequential to parallel
+ *
+ * Algorithm: Kahn's Algorithm (BFS-based)
+ * 1. Start with all nodes that have no dependencies (in-degree = 0)
+ * 2. Remove them and their edges, collect them as Phase 1
+ * 3. Find new nodes with in-degree = 0 (Phase 2)
+ * 4. Repeat until all nodes are processed
+ *
+ * Result: [['validate'], ['process', 'lint'], ['upload']]
+ *         Phase 1: validate (runs alone)
+ *         Phase 2: process and lint (run in parallel!)
+ *         Phase 3: upload (runs after both complete)
+ *
+ * What it does NOT do:
+ * - Does NOT execute steps (that's StepExecutor's job)
+ * - Does NOT manage state (that's ExecutionState's job)
+ * - Does NOT add retries (that's StepExecutor's job)
+ */
+import { WorkflowValidationError } from '@dev-ecosystem/core';
+import { DependencyResolver } from './DependencyResolver.js';
+/**
+ * Performs topological sorting to determine execution order.
+ * Pure function - takes validated graph, returns execution phases.
+ */
+export class TopologicalSorter {
+    /**
+     * Sort the dependency graph into execution phases using Kahn's algorithm.
+     *
+     * This is BFS-based and naturally groups independent steps into phases.
+     *
+     * @param graph - The dependency graph (must be acyclic)
+     * @returns Topological sort result with execution phases
+     * @throws WorkflowValidationError if graph contains cycles
+     */
+    static sort(graph) {
+        // Calculate in-degrees (number of dependencies for each node)
+        const inDegrees = DependencyResolver.calculateInDegrees(graph);
+        // Track which nodes have been processed
+        const processed = new Set();
+        // Store phases
+        const phases = [];
+        // Map of stepId → phase number
+        const stepPhases = new Map();
+        // Kahn's algorithm
+        let currentPhaseIndex = 0;
+        while (processed.size < graph.nodes.size) {
+            // Find all nodes with in-degree 0 (ready to execute)
+            const currentPhase = [];
+            for (const [stepId, inDegree] of inDegrees) {
+                if (inDegree === 0 && !processed.has(stepId)) {
+                    currentPhase.push(stepId);
+                }
+            }
+            // If no nodes are ready but we haven't processed everything,
+            // there must be a cycle
+            if (currentPhase.length === 0 && processed.size < graph.nodes.size) {
+                const remaining = Array.from(graph.nodes.keys()).filter((id) => !processed.has(id));
+                throw new WorkflowValidationError('Cannot create execution plan: circular dependency detected during topological sort', {
+                    remainingSteps: remaining,
+                    hint: 'Use CycleDetector.detectAndThrow() before calling TopologicalSorter.sort()',
+                });
+            }
+            // Process current phase
+            for (const stepId of currentPhase) {
+                processed.add(stepId);
+                stepPhases.set(stepId, currentPhaseIndex);
+                // Reduce in-degree of all dependents
+                const dependents = graph.reverseDependencies.get(stepId) || [];
+                for (const dependent of dependents) {
+                    const currentInDegree = inDegrees.get(dependent);
+                    inDegrees.set(dependent, currentInDegree - 1);
+                }
+            }
+            if (currentPhase.length > 0) {
+                phases.push(currentPhase);
+                currentPhaseIndex++;
+            }
+        }
+        return {
+            phases: phases.map((phase) => Object.freeze([...phase])),
+            phaseCount: phases.length,
+            stepPhases,
+        };
+    }
+    /**
+     * Sort using DFS-based algorithm (alternative to Kahn's).
+     * This produces a valid topological order but doesn't naturally
+     * group into phases like Kahn's does.
+     *
+     * Use this if you need a single linear order rather than phases.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs in topological order
+     */
+    static sortLinear(graph) {
+        const visited = new Set();
+        const result = [];
+        const visit = (nodeId) => {
+            if (visited.has(nodeId)) {
+                return;
+            }
+            visited.add(nodeId);
+            // Visit all dependencies first
+            const dependencies = graph.adjacencyList.get(nodeId) || [];
+            for (const dependency of dependencies) {
+                visit(dependency);
+            }
+            // Add to result after visiting dependencies
+            result.push(nodeId);
+        };
+        // Visit all nodes
+        for (const nodeId of graph.nodes.keys()) {
+            visit(nodeId);
+        }
+        return result;
+    }
+    /**
+     * Calculate the critical path through the dependency graph.
+     * The critical path is the longest path from entry to exit points.
+     *
+     * This is useful for:
+     * - Estimating minimum workflow execution time
+     * - Identifying bottlenecks
+     * - Optimizing parallelization
+     *
+     * @param graph - The dependency graph
+     * @param stepDurations - Map of stepId → estimated duration (ms)
+     * @returns Critical path information
+     */
+    static calculateCriticalPath(graph, stepDurations) {
+        const sortResult = this.sort(graph);
+        const earliestStart = new Map();
+        const latestStart = new Map();
+        // Forward pass: calculate earliest start times
+        for (const phase of sortResult.phases) {
+            for (const stepId of phase) {
+                const dependencies = graph.adjacencyList.get(stepId) || [];
+                if (dependencies.length === 0) {
+                    earliestStart.set(stepId, 0);
+                }
+                else {
+                    let maxEarliest = 0;
+                    for (const dep of dependencies) {
+                        const depEarliest = earliestStart.get(dep);
+                        const depDuration = stepDurations.get(dep) || 0;
+                        maxEarliest = Math.max(maxEarliest, depEarliest + depDuration);
+                    }
+                    earliestStart.set(stepId, maxEarliest);
+                }
+            }
+        }
+        // Find maximum earliest start (workflow end time)
+        let workflowDuration = 0;
+        for (const [stepId, earliest] of earliestStart) {
+            const duration = stepDurations.get(stepId) || 0;
+            workflowDuration = Math.max(workflowDuration, earliest + duration);
+        }
+        // Backward pass: calculate latest start times
+        const exitPoints = DependencyResolver.getExitPoints(graph);
+        for (const exitPoint of exitPoints) {
+            const duration = stepDurations.get(exitPoint) || 0;
+            latestStart.set(exitPoint, workflowDuration - duration);
+        }
+        // Process phases in reverse
+        for (let i = sortResult.phases.length - 1; i >= 0; i--) {
+            for (const stepId of sortResult.phases[i]) {
+                if (latestStart.has(stepId)) {
+                    continue; // Already set as exit point
+                }
+                const dependents = graph.reverseDependencies.get(stepId) || [];
+                const duration = stepDurations.get(stepId) || 0;
+                let minLatest = workflowDuration;
+                for (const dependent of dependents) {
+                    const dependentLatest = latestStart.get(dependent);
+                    minLatest = Math.min(minLatest, dependentLatest);
+                }
+                latestStart.set(stepId, minLatest - duration);
+            }
+        }
+        // Calculate slack (float) for each step
+        const slack = new Map();
+        for (const stepId of graph.nodes.keys()) {
+            const earliest = earliestStart.get(stepId);
+            const latest = latestStart.get(stepId);
+            slack.set(stepId, latest - earliest);
+        }
+        // Find critical path (steps with zero slack)
+        const criticalPath = [];
+        for (const [stepId, slackValue] of slack) {
+            if (slackValue === 0) {
+                criticalPath.push(stepId);
+            }
+        }
+        return {
+            criticalPath,
+            workflowDuration,
+            earliestStart,
+            latestStart,
+            slack,
+        };
+    }
+}
+//# sourceMappingURL=TopologicalSorter.js.map

package/dist/graph/TopologicalSorter.js.map

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

package/dist/graph/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Graph Analysis Utilities
+ *
+ * Tools for analyzing workflow dependency graphs:
+ * - DependencyResolver: Build graph from workflow steps
+ * - CycleDetector: Validate no circular dependencies
+ * - TopologicalSorter: Generate execution phases for parallelization
+ *
+ * These work together to create valid execution plans.
+ */
+export * from './DependencyGraph.js';
+export * from './DependencyResolver.js';
+export * from './CycleDetector.js';
+export * from './TopologicalSorter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/graph/index.js

@@ -0,0 +1,15 @@
+/**
+ * Graph Analysis Utilities
+ *
+ * Tools for analyzing workflow dependency graphs:
+ * - DependencyResolver: Build graph from workflow steps
+ * - CycleDetector: Validate no circular dependencies
+ * - TopologicalSorter: Generate execution phases for parallelization
+ *
+ * These work together to create valid execution plans.
+ */
+export * from './DependencyGraph.js';
+export * from './DependencyResolver.js';
+export * from './CycleDetector.js';
+export * from './TopologicalSorter.js';
+//# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/guards/ResourceGuard.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Resource Guard
+ *
+ * Future security and resource limiting layer.
+ * Currently provides basic checks, will be extended for:
+ * - Permission policies
+ * - Resource limits (CPU, memory, network)
+ * - Sandbox enforcement
+ *
+ * @module guards
+ */
+import type { ParsedStep } from '../parser/StepParser.js';
+/**
+ * Permission policy for workflow execution
+ */
+export interface PermissionPolicy {
+    /** Allow network access */
+    allowNetwork?: boolean;
+    /** Allow file system access */
+    allowFileSystem?: boolean;
+    /** Allow shell command execution */
+    allowShell?: boolean;
+    /** Allowed adapter types */
+    allowedAdapters?: string[];
+    /** Blocked adapter types */
+    blockedAdapters?: string[];
+    /** Maximum step timeout (ms) */
+    maxStepTimeout?: number;
+    /** Maximum workflow timeout (ms) */
+    maxWorkflowTimeout?: number;
+}
+/**
+ * Resource and permission guard
+ */
+export declare class ResourceGuard {
+    private policy;
+    constructor(policy?: Partial<PermissionPolicy>);
+    /**
+     * Validate step against permission policy
+     *
+     * @param step - Step to validate
+     * @throws {Error} If step violates policy
+     */
+    validateStep(step: ParsedStep): void;
+    /**
+     * Check if adapter type is allowed
+     */
+    private checkAdapterPermission;
+    /**
+     * Check timeout limits
+     */
+    private checkTimeout;
+    /**
+     * Parse timeout string to milliseconds
+     */
+    private parseTimeoutString;
+    /**
+     * Check network access permission
+     */
+    private checkNetworkAccess;
+    /**
+     * Check file system access permission
+     */
+    private checkFileSystemAccess;
+    /**
+     * Check shell execution permission
+     */
+    private checkShellAccess;
+    /**
+     * Validate workflow-level resource limits
+     *
+     * @param steps - All workflow steps
+     * @param workflowTimeout - Total workflow timeout
+     * @throws {Error} If workflow exceeds limits
+     */
+    validateWorkflow(steps: ParsedStep[], workflowTimeout?: number): void;
+    /**
+     * Get current policy
+     */
+    getPolicy(): PermissionPolicy;
+    /**
+     * Create a restrictive policy (for untrusted workflows)
+     */
+    static restrictivePolicy(): PermissionPolicy;
+    /**
+     * Create a permissive policy (for trusted workflows)
+     */
+    static permissivePolicy(): PermissionPolicy;
+}
+//# sourceMappingURL=ResourceGuard.d.ts.map

package/dist/guards/ResourceGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceGuard.d.ts","sourceRoot":"","sources":["../../src/guards/ResourceGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,+BAA+B;IAC/B,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,oCAAoC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,4BAA4B;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oCAAoC;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAeD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAIlD;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyB1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI;IAgBrE;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,gBAAgB;IAY5C;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,gBAAgB;CAG5C"}

package/dist/guards/ResourceGuard.js

@@ -0,0 +1,177 @@
+/**
+ * Resource Guard
+ *
+ * Future security and resource limiting layer.
+ * Currently provides basic checks, will be extended for:
+ * - Permission policies
+ * - Resource limits (CPU, memory, network)
+ * - Sandbox enforcement
+ *
+ * @module guards
+ */
+/**
+ * Default permission policy (permissive)
+ */
+const DEFAULT_POLICY = {
+    allowNetwork: true,
+    allowFileSystem: true,
+    allowShell: true,
+    allowedAdapters: undefined, // Allow all
+    blockedAdapters: [],
+    maxStepTimeout: 30 * 60 * 1000, // 30 minutes
+    maxWorkflowTimeout: 2 * 60 * 60 * 1000, // 2 hours
+};
+/**
+ * Resource and permission guard
+ */
+export class ResourceGuard {
+    policy;
+    constructor(policy = {}) {
+        this.policy = { ...DEFAULT_POLICY, ...policy };
+    }
+    /**
+     * Validate step against permission policy
+     *
+     * @param step - Step to validate
+     * @throws {Error} If step violates policy
+     */
+    validateStep(step) {
+        this.checkAdapterPermission(step);
+        this.checkTimeout(step);
+        this.checkNetworkAccess(step);
+        this.checkFileSystemAccess(step);
+        this.checkShellAccess(step);
+    }
+    /**
+     * Check if adapter type is allowed
+     */
+    checkAdapterPermission(step) {
+        const { adapter } = step;
+        const { allowedAdapters, blockedAdapters } = this.policy;
+        // Check blocked list first
+        if (blockedAdapters && blockedAdapters.includes(adapter)) {
+            throw new Error(`Step '${step.id}': adapter '${adapter}' is blocked by policy`);
+        }
+        // Check allowed list if defined
+        if (allowedAdapters && !allowedAdapters.includes(adapter)) {
+            throw new Error(`Step '${step.id}': adapter '${adapter}' is not in allowed list. ` +
+                `Allowed: ${allowedAdapters.join(', ')}`);
+        }
+    }
+    /**
+     * Check timeout limits
+     */
+    checkTimeout(step) {
+        const { maxStepTimeout } = this.policy;
+        if (maxStepTimeout && step.timeout) {
+            const timeoutMs = this.parseTimeoutString(step.timeout);
+            if (timeoutMs > maxStepTimeout) {
+                throw new Error(`Step '${step.id}': timeout ${timeoutMs}ms exceeds policy limit ${maxStepTimeout}ms`);
+            }
+        }
+    }
+    /**
+     * Parse timeout string to milliseconds
+     */
+    parseTimeoutString(timeout) {
+        const match = timeout.match(/^([0-9]+)(ms|s|m|h|d)$/);
+        if (!match) {
+            return 30000; // Default 30s
+        }
+        const value = parseInt(match[1], 10);
+        const unit = match[2];
+        switch (unit) {
+            case 'ms':
+                return value;
+            case 's':
+                return value * 1000;
+            case 'm':
+                return value * 60 * 1000;
+            case 'h':
+                return value * 60 * 60 * 1000;
+            case 'd':
+                return value * 24 * 60 * 60 * 1000;
+            default:
+                return 30000;
+        }
+    }
+    /**
+     * Check network access permission
+     */
+    checkNetworkAccess(step) {
+        if (this.policy.allowNetwork === false) {
+            const networkAdapters = ['http', 'webhook', 'api'];
+            if (networkAdapters.includes(step.adapter)) {
+                throw new Error(`Step '${step.id}': network access not allowed by policy`);
+            }
+        }
+    }
+    /**
+     * Check file system access permission
+     */
+    checkFileSystemAccess(step) {
+        if (this.policy.allowFileSystem === false) {
+            const fsAdapters = ['fs', 'file'];
+            if (fsAdapters.includes(step.adapter)) {
+                throw new Error(`Step '${step.id}': file system access not allowed by policy`);
+            }
+        }
+    }
+    /**
+     * Check shell execution permission
+     */
+    checkShellAccess(step) {
+        if (this.policy.allowShell === false) {
+            const shellAdapters = ['shell', 'cli', 'exec'];
+            if (shellAdapters.includes(step.adapter)) {
+                throw new Error(`Step '${step.id}': shell execution not allowed by policy`);
+            }
+        }
+    }
+    /**
+     * Validate workflow-level resource limits
+     *
+     * @param steps - All workflow steps
+     * @param workflowTimeout - Total workflow timeout
+     * @throws {Error} If workflow exceeds limits
+     */
+    validateWorkflow(steps, workflowTimeout) {
+        // Check workflow timeout
+        if (this.policy.maxWorkflowTimeout && workflowTimeout) {
+            if (workflowTimeout > this.policy.maxWorkflowTimeout) {
+                throw new Error(`Workflow timeout ${workflowTimeout}ms exceeds policy limit ${this.policy.maxWorkflowTimeout}ms`);
+            }
+        }
+        // Validate each step
+        for (const step of steps) {
+            this.validateStep(step);
+        }
+    }
+    /**
+     * Get current policy
+     */
+    getPolicy() {
+        return { ...this.policy };
+    }
+    /**
+     * Create a restrictive policy (for untrusted workflows)
+     */
+    static restrictivePolicy() {
+        return {
+            allowNetwork: false,
+            allowFileSystem: false,
+            allowShell: false,
+            allowedAdapters: ['plugin'], // Only plugins
+            blockedAdapters: ['shell', 'cli', 'exec', 'fs'],
+            maxStepTimeout: 5 * 60 * 1000, // 5 minutes
+            maxWorkflowTimeout: 15 * 60 * 1000, // 15 minutes
+        };
+    }
+    /**
+     * Create a permissive policy (for trusted workflows)
+     */
+    static permissivePolicy() {
+        return DEFAULT_POLICY;
+    }
+}
+//# sourceMappingURL=ResourceGuard.js.map

package/dist/guards/ResourceGuard.js.map

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

package/dist/guards/StepGuard.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Step Guard
+ *
+ * Validates individual step configurations:
+ * - Step structure validation
+ * - Input parameter validation
+ * - Timeout validation
+ * - Retry policy validation
+ *
+ * @module guards
+ */
+import type { ParsedStep } from '../parser/StepParser.js';
+/**
+ * Step validation guard
+ */
+export declare class StepGuard {
+    /**
+     * Validate a single step
+     *
+     * @param step - Step to validate
+     * @param availableSteps - Set of all step IDs in workflow
+     * @throws {Error} If validation fails
+     */
+    static validate(step: ParsedStep, availableSteps: Set<string>): void;
+    /**
+     * Validate required fields
+     *
+     * @param step - Step to validate
+     * @throws {Error} If required fields missing
+     */
+    private static validateRequired;
+    /**
+     * Validate timeout values
+     *
+     * @param step - Step to validate
+     * @throws {Error} If timeout invalid
+     */
+    private static validateTimeout;
+    /**
+     * Validate retry policy
+     *
+     * @param step - Step to validate
+     * @throws {Error} If retry policy invalid
+     */
+    private static validateRetryPolicy;
+    /**
+     * Validate step dependencies exist
+     *
+     * @param step - Step to validate
+     * @param availableSteps - Set of all step IDs
+     * @throws {Error} If dependency doesn't exist
+     */
+    private static validateDependencies;
+    /**
+     * Validate variable references in step inputs
+     *
+     * @param step - Step to validate
+     * @param availableSteps - Set of all step IDs
+     * @throws {Error} If variable references unknown step
+     */
+    private static validateVariableReferences;
+    /**
+     * Validate adapter-specific requirements
+     *
+     * @param step - Step to validate
+     * @throws {Error} If adapter requirements not met
+     */
+    static validateAdapterRequirements(step: ParsedStep): void;
+    /**
+     * Validate HTTP adapter requirements
+     */
+    private static validateHttpAdapter;
+    /**
+     * Validate shell adapter requirements
+     */
+    private static validateShellAdapter;
+    /**
+     * Validate CLI adapter requirements
+     */
+    private static validateCliAdapter;
+    /**
+     * Check if step has any conditional execution
+     *
+     * @param step - Step to check
+     * @returns True if step has 'when' condition
+     */
+    static isConditional(step: ParsedStep): boolean;
+    /**
+     * Check if step is retryable
+     *
+     * @param step - Step to check
+     * @returns True if step has retry policy configured
+     */
+    static isRetryable(step: ParsedStep): boolean;
+}
+//# sourceMappingURL=StepGuard.d.ts.map

package/dist/guards/StepGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepGuard.d.ts","sourceRoot":"","sources":["../../src/guards/StepGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D;;GAEG;AACH,qBAAa,SAAS;IACpB;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAQpE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAiB9B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkBlC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAoBnC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAczC;;;;;OAKG;IACH,MAAM,CAAC,2BAA2B,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAkB1D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAWlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAQnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAQjC;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAI/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;CAG9C"}