@mxf-dev/core 1.0.0

package/dist/types/ControlLoopTypes.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * ControlLoopTypes.ts
+ *
+ * Defines all types and interfaces used by the Control Loop component.
+ * This file centralizes the type definitions to ensure consistency across
+ * the Control Loop implementation.
+ */
+import { AgentId } from './Agent.js';
+/**
+ * Enum representing the possible states of the control loop
+ */
+export declare enum ControlLoopStateEnum {
+    IDLE = "idle",// Control loop is initialized but not running
+    INITIALIZING = "initializing",// Control loop is initializing
+    RUNNING = "running",// Control loop is actively running
+    OBSERVING = "observing",// Currently processing observations
+    REASONING = "reasoning",// Currently generating reasoning
+    PLANNING = "planning",// Currently creating a plan
+    EXECUTING = "executing",// Currently executing a plan
+    REFLECTING = "reflecting",// Currently reflecting on execution
+    PAUSED = "paused",// Control loop is paused
+    ERROR = "error",// Control loop encountered an error
+    DEGRADED = "degraded"
+}
+/**
+ * Configuration options for the control loop
+ */
+export interface ControlLoopConfig {
+    maxObservations?: number;
+    cycleInterval?: number;
+    errorRecovery?: ErrorRecoveryConfig;
+    reinforcement?: ReinforcementConfig;
+}
+/**
+ * Error recovery configuration
+ */
+export interface ErrorRecoveryConfig {
+    maxConsecutiveErrors?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    enableAutoHealing?: boolean;
+}
+/**
+ * Reinforcement learning configuration
+ */
+export interface ReinforcementConfig {
+    enabled: boolean;
+    learningRate?: number;
+    maxEpisodes?: number;
+    networkType?: string;
+    hiddenLayers?: number[];
+    activationFunction?: string;
+    batchSize?: number;
+}
+/**
+ * Training instance for reinforcement learning
+ */
+export interface TrainingInstance {
+    id: string;
+    agentId: AgentId;
+    state: any;
+    action: any;
+    reward: number;
+    nextState: any;
+    timestamp: number;
+}
+/**
+ * Represents an observation from the environment
+ */
+export interface Observation {
+    id: string;
+    agentId: AgentId;
+    source: string;
+    content: any;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Represents reasoning based on observations
+ */
+export interface Reasoning {
+    id: string;
+    agentId: AgentId;
+    content: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Status of a plan action
+ */
+export type ActionStatus = 'pending' | 'executing' | 'completed' | 'failed' | 'aborted' | 'skipped';
+/**
+ * Represents an action in a plan
+ */
+export interface PlanAction {
+    id: string;
+    description: string;
+    action: string;
+    parameters: any;
+    priority: number;
+    dependencies?: string[];
+    timestamp?: number;
+    status: ActionStatus;
+    result?: any;
+    error?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Represents a plan to achieve a goal
+ */
+export interface Plan {
+    id: string;
+    agentId: AgentId;
+    reasoningId: string;
+    actions: PlanAction[];
+    timestamp: number;
+    goal: string;
+    description: string;
+    createdAt: Date;
+    completedAt?: Date;
+    status: 'created' | 'executing' | 'completed' | 'failed' | 'aborted';
+    metadata?: Record<string, any>;
+}
+/**
+ * Represents reflection on a plan execution
+ */
+export interface Reflection {
+    id: string;
+    agentId: AgentId;
+    planId: string;
+    success: boolean;
+    insights: string[];
+    improvements: string[];
+    metadata?: Record<string, any>;
+    timestamp: number;
+}
+/**
+ * Represents a control loop event
+ */
+export interface ControlLoopEvent {
+    type: string;
+    data: any;
+    timestamp: number;
+}
+//# sourceMappingURL=ControlLoopTypes.d.ts.map

package/dist/types/ControlLoopTypes.d.ts.map

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

package/dist/types/ControlLoopTypes.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Enum representing the possible states of the control loop
+ */
+export var ControlLoopStateEnum;
+(function (ControlLoopStateEnum) {
+    ControlLoopStateEnum["IDLE"] = "idle";
+    ControlLoopStateEnum["INITIALIZING"] = "initializing";
+    ControlLoopStateEnum["RUNNING"] = "running";
+    ControlLoopStateEnum["OBSERVING"] = "observing";
+    ControlLoopStateEnum["REASONING"] = "reasoning";
+    ControlLoopStateEnum["PLANNING"] = "planning";
+    ControlLoopStateEnum["EXECUTING"] = "executing";
+    ControlLoopStateEnum["REFLECTING"] = "reflecting";
+    ControlLoopStateEnum["PAUSED"] = "paused";
+    ControlLoopStateEnum["ERROR"] = "error";
+    ControlLoopStateEnum["DEGRADED"] = "degraded"; // Control loop is in degraded mode
+})(ControlLoopStateEnum || (ControlLoopStateEnum = {}));
+//# sourceMappingURL=ControlLoopTypes.js.map

package/dist/types/ControlLoopTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControlLoopTypes.js","sourceRoot":"","sources":["../../src/types/ControlLoopTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH;;GAEG;AACH,MAAM,CAAN,IAAY,oBAYX;AAZD,WAAY,oBAAoB;IAC5B,qCAAa,CAAA;IACb,qDAA6B,CAAA;IAC7B,2CAAmB,CAAA;IACnB,+CAAuB,CAAA;IACvB,+CAAuB,CAAA;IACvB,6CAAqB,CAAA;IACrB,+CAAuB,CAAA;IACvB,iDAAyB,CAAA;IACzB,yCAAiB,CAAA;IACjB,uCAAe,CAAA;IACf,6CAAqB,CAAA,CAAU,mCAAmC;AACtE,CAAC,EAZW,oBAAoB,KAApB,oBAAoB,QAY/B"}

package/dist/types/DagTypes.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Task DAG Types
+ *
+ * Defines interfaces and types for the Task Directed Acyclic Graph (DAG) system.
+ * The DAG enforces task dependencies with cycle detection and execution ordering.
+ *
+ * Key concepts:
+ * - TaskDag: The complete graph structure for a channel
+ * - TaskDagNode: Individual task nodes with dependency information
+ * - TaskDagEdge: Directed edges representing dependencies
+ * - TopologicalResult: Result of topological sort operations
+ */
+import { TaskStatus } from './TaskTypes.js';
+import { ChannelId } from './ChannelContext.js';
+/**
+ * A node in the Task DAG representing a single task
+ */
+export interface TaskDagNode {
+    /** The task ID (matches ChannelTask.id) */
+    taskId: string;
+    /** Current status of the task */
+    status: TaskStatus;
+    /** Task IDs that this task depends on (incoming edges) */
+    dependsOn: string[];
+    /** Task IDs that depend on this task (outgoing edges) */
+    blockedBy: string[];
+    /** Computed in-degree for topological sorting */
+    inDegree: number;
+    /** Computed out-degree for graph analysis */
+    outDegree: number;
+    /** Whether this task is currently ready to execute (all dependencies satisfied) */
+    isReady: boolean;
+    /** Timestamp when the node was added to the DAG */
+    addedAt: number;
+    /** Timestamp when the node was last updated */
+    updatedAt: number;
+}
+/**
+ * A directed edge in the Task DAG representing a dependency relationship
+ */
+export interface TaskDagEdge {
+    /** Unique identifier for the edge */
+    id: string;
+    /** The task that must complete first (source/dependency) */
+    fromTaskId: string;
+    /** The task that depends on the source (target/dependent) */
+    toTaskId: string;
+    /** Optional label describing the dependency type */
+    label?: string;
+    /** Timestamp when the edge was created */
+    createdAt: number;
+}
+/**
+ * The complete Task DAG structure for a channel
+ */
+export interface TaskDag {
+    /** The channel this DAG belongs to */
+    channelId: ChannelId;
+    /** Map of task IDs to their DAG nodes */
+    nodes: Map<string, TaskDagNode>;
+    /** Map of edge IDs to their definitions */
+    edges: Map<string, TaskDagEdge>;
+    /** Adjacency list for efficient traversal (taskId -> dependent taskIds) */
+    adjacencyList: Map<string, Set<string>>;
+    /** Reverse adjacency list (taskId -> dependency taskIds) */
+    reverseAdjacencyList: Map<string, Set<string>>;
+    /** Timestamp when the DAG was created */
+    createdAt: number;
+    /** Timestamp when the DAG was last modified */
+    updatedAt: number;
+    /** Version number for optimistic concurrency */
+    version: number;
+}
+/**
+ * Result of a topological sort operation
+ */
+export interface TopologicalResult {
+    /** Whether the sort was successful (no cycles detected) */
+    success: boolean;
+    /** Topologically sorted list of task IDs */
+    order: string[];
+    /** Tasks that are currently ready to execute */
+    readyTasks: string[];
+    /** Tasks that are blocked by incomplete dependencies */
+    blockedTasks: string[];
+    /** Tasks that have been completed */
+    completedTasks: string[];
+    /** Execution levels (tasks at same level can run in parallel) */
+    levels: string[][];
+    /** Critical path (longest dependency chain) */
+    criticalPath: string[];
+    /** Error message if sort failed */
+    error?: string;
+}
+/**
+ * Result of cycle detection
+ */
+export interface CycleDetectionResult {
+    /** Whether a cycle was detected */
+    hasCycle: boolean;
+    /** The cycle path if found (list of task IDs forming the cycle) */
+    cyclePath?: string[];
+    /** Human-readable description of the cycle */
+    cycleDescription?: string;
+}
+/**
+ * Result of DAG validation
+ */
+export interface DagValidationResult {
+    /** Whether the DAG is valid */
+    isValid: boolean;
+    /** List of validation errors */
+    errors: DagValidationError[];
+    /** List of validation warnings */
+    warnings: DagValidationWarning[];
+    /** Statistics about the DAG */
+    stats: DagStats;
+}
+/**
+ * A validation error in the DAG
+ */
+export interface DagValidationError {
+    /** Error code */
+    code: DagErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Related task IDs */
+    taskIds?: string[];
+    /** Related edge IDs */
+    edgeIds?: string[];
+}
+/**
+ * A validation warning in the DAG
+ */
+export interface DagValidationWarning {
+    /** Warning code */
+    code: DagWarningCode;
+    /** Human-readable warning message */
+    message: string;
+    /** Related task IDs */
+    taskIds?: string[];
+}
+/**
+ * Statistics about a DAG
+ */
+export interface DagStats {
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Total number of edges */
+    edgeCount: number;
+    /** Number of root nodes (no dependencies) */
+    rootCount: number;
+    /** Number of leaf nodes (no dependents) */
+    leafCount: number;
+    /** Maximum depth of the DAG */
+    maxDepth: number;
+    /** Average in-degree */
+    averageInDegree: number;
+    /** Average out-degree */
+    averageOutDegree: number;
+    /** Number of ready tasks */
+    readyTaskCount: number;
+    /** Number of blocked tasks */
+    blockedTaskCount: number;
+    /** Number of completed tasks */
+    completedTaskCount: number;
+}
+/**
+ * Error codes for DAG validation
+ */
+export declare enum DagErrorCode {
+    /** A cycle was detected in the graph */
+    CYCLE_DETECTED = "CYCLE_DETECTED",
+    /** An edge references a non-existent task */
+    MISSING_NODE = "MISSING_NODE",
+    /** Duplicate edge detected */
+    DUPLICATE_EDGE = "DUPLICATE_EDGE",
+    /** Self-referential dependency */
+    SELF_DEPENDENCY = "SELF_DEPENDENCY",
+    /** Invalid task status transition based on dependencies */
+    INVALID_STATUS_TRANSITION = "INVALID_STATUS_TRANSITION"
+}
+/**
+ * Warning codes for DAG validation
+ */
+export declare enum DagWarningCode {
+    /** Task has an unusually high number of dependencies */
+    HIGH_IN_DEGREE = "HIGH_IN_DEGREE",
+    /** Task has an unusually high number of dependents */
+    HIGH_OUT_DEGREE = "HIGH_OUT_DEGREE",
+    /** Long dependency chain detected */
+    LONG_CHAIN = "LONG_CHAIN",
+    /** Orphaned node (no edges) */
+    ORPHANED_NODE = "ORPHANED_NODE"
+}
+/**
+ * Configuration for the Task DAG system
+ */
+export interface DagConfig {
+    /** Whether the DAG system is enabled */
+    enabled: boolean;
+    /** Cache TTL in milliseconds */
+    cacheTtlMs: number;
+    /** Timeout for cycle detection operations in milliseconds */
+    cycleCheckTimeoutMs: number;
+    /** Whether to enforce DAG validation on task status changes */
+    enforceOnStatusChange: boolean;
+    /** Maximum allowed in-degree before warning */
+    maxInDegreeWarning: number;
+    /** Maximum allowed out-degree before warning */
+    maxOutDegreeWarning: number;
+    /** Maximum allowed chain length before warning */
+    maxChainLengthWarning: number;
+    /** Whether to emit events for DAG changes */
+    emitEvents: boolean;
+    /** Whether to log debug information */
+    debug: boolean;
+    /** Maximum allowed limit for ready tasks queries (hard cap) */
+    maxReadyTasksLimit: number;
+    /** Default limit for ready tasks queries when not specified */
+    defaultReadyTasksLimit: number;
+}
+/**
+ * Default DAG configuration values
+ */
+export declare const DEFAULT_DAG_CONFIG: DagConfig;
+/**
+ * Environment variable names for DAG configuration
+ */
+export declare const DAG_ENV_VARS: {
+    readonly ENABLED: "TASK_DAG_ENABLED";
+    readonly CACHE_TTL_MS: "DAG_CACHE_TTL_MS";
+    readonly CYCLE_CHECK_TIMEOUT_MS: "DAG_CYCLE_CHECK_TIMEOUT_MS";
+    readonly ENFORCE_ON_STATUS_CHANGE: "DAG_ENFORCE_ON_STATUS_CHANGE";
+    readonly MAX_IN_DEGREE_WARNING: "DAG_MAX_IN_DEGREE_WARNING";
+    readonly MAX_OUT_DEGREE_WARNING: "DAG_MAX_OUT_DEGREE_WARNING";
+    readonly MAX_CHAIN_LENGTH_WARNING: "DAG_MAX_CHAIN_LENGTH_WARNING";
+    readonly EMIT_EVENTS: "DAG_EMIT_EVENTS";
+    readonly DEBUG: "DAG_DEBUG";
+    readonly MAX_READY_TASKS_LIMIT: "DAG_MAX_READY_TASKS_LIMIT";
+    readonly DEFAULT_READY_TASKS_LIMIT: "DAG_DEFAULT_READY_TASKS_LIMIT";
+};
+/**
+ * Request to add a dependency between tasks
+ */
+export interface AddDependencyRequest {
+    /** The task that will depend on another */
+    dependentTaskId: string;
+    /** The task that must complete first */
+    dependencyTaskId: string;
+    /** Optional label for the dependency */
+    label?: string;
+}
+/**
+ * Request to remove a dependency between tasks
+ */
+export interface RemoveDependencyRequest {
+    /** The task that depends on another */
+    dependentTaskId: string;
+    /** The task that is a dependency */
+    dependencyTaskId: string;
+}
+/**
+ * Result of adding a dependency
+ */
+export interface AddDependencyResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The created edge, if successful */
+    edge?: TaskDagEdge;
+    /** Error message if failed */
+    error?: string;
+    /** Error code if failed */
+    errorCode?: DagErrorCode;
+    /** Cycle path if a cycle would be created */
+    cyclePath?: string[];
+}
+/**
+ * Options for getting ready tasks
+ */
+export interface GetReadyTasksOptions {
+    /** Filter by specific task IDs */
+    taskIds?: string[];
+    /** Maximum number of tasks to return */
+    limit?: number;
+    /** Sort by a specific field */
+    sortBy?: 'addedAt' | 'priority';
+    /** Sort direction */
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Options for getting execution order
+ */
+export interface GetExecutionOrderOptions {
+    /** Whether to include completed tasks */
+    includeCompleted?: boolean;
+    /** Whether to include blocked tasks */
+    includeBlocked?: boolean;
+    /** Filter by specific task statuses */
+    statuses?: TaskStatus[];
+}
+//# sourceMappingURL=DagTypes.d.ts.map

package/dist/types/DagTypes.d.ts.map

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

package/dist/types/DagTypes.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * Error codes for DAG validation
+ */
+export var DagErrorCode;
+(function (DagErrorCode) {
+    /** A cycle was detected in the graph */
+    DagErrorCode["CYCLE_DETECTED"] = "CYCLE_DETECTED";
+    /** An edge references a non-existent task */
+    DagErrorCode["MISSING_NODE"] = "MISSING_NODE";
+    /** Duplicate edge detected */
+    DagErrorCode["DUPLICATE_EDGE"] = "DUPLICATE_EDGE";
+    /** Self-referential dependency */
+    DagErrorCode["SELF_DEPENDENCY"] = "SELF_DEPENDENCY";
+    /** Invalid task status transition based on dependencies */
+    DagErrorCode["INVALID_STATUS_TRANSITION"] = "INVALID_STATUS_TRANSITION";
+})(DagErrorCode || (DagErrorCode = {}));
+/**
+ * Warning codes for DAG validation
+ */
+export var DagWarningCode;
+(function (DagWarningCode) {
+    /** Task has an unusually high number of dependencies */
+    DagWarningCode["HIGH_IN_DEGREE"] = "HIGH_IN_DEGREE";
+    /** Task has an unusually high number of dependents */
+    DagWarningCode["HIGH_OUT_DEGREE"] = "HIGH_OUT_DEGREE";
+    /** Long dependency chain detected */
+    DagWarningCode["LONG_CHAIN"] = "LONG_CHAIN";
+    /** Orphaned node (no edges) */
+    DagWarningCode["ORPHANED_NODE"] = "ORPHANED_NODE";
+})(DagWarningCode || (DagWarningCode = {}));
+/**
+ * Default DAG configuration values
+ */
+export const DEFAULT_DAG_CONFIG = {
+    enabled: false,
+    cacheTtlMs: 60000, // 1 minute
+    cycleCheckTimeoutMs: 50, // 50ms for performance
+    enforceOnStatusChange: true,
+    maxInDegreeWarning: 10,
+    maxOutDegreeWarning: 10,
+    maxChainLengthWarning: 20,
+    emitEvents: true,
+    debug: false,
+    maxReadyTasksLimit: 100,
+    defaultReadyTasksLimit: 10,
+};
+/**
+ * Environment variable names for DAG configuration
+ */
+export const DAG_ENV_VARS = {
+    ENABLED: 'TASK_DAG_ENABLED',
+    CACHE_TTL_MS: 'DAG_CACHE_TTL_MS',
+    CYCLE_CHECK_TIMEOUT_MS: 'DAG_CYCLE_CHECK_TIMEOUT_MS',
+    ENFORCE_ON_STATUS_CHANGE: 'DAG_ENFORCE_ON_STATUS_CHANGE',
+    MAX_IN_DEGREE_WARNING: 'DAG_MAX_IN_DEGREE_WARNING',
+    MAX_OUT_DEGREE_WARNING: 'DAG_MAX_OUT_DEGREE_WARNING',
+    MAX_CHAIN_LENGTH_WARNING: 'DAG_MAX_CHAIN_LENGTH_WARNING',
+    EMIT_EVENTS: 'DAG_EMIT_EVENTS',
+    DEBUG: 'DAG_DEBUG',
+    MAX_READY_TASKS_LIMIT: 'DAG_MAX_READY_TASKS_LIMIT',
+    DEFAULT_READY_TASKS_LIMIT: 'DAG_DEFAULT_READY_TASKS_LIMIT',
+};
+//# sourceMappingURL=DagTypes.js.map

package/dist/types/DagTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DagTypes.js","sourceRoot":"","sources":["../../src/types/DagTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiOH;;GAEG;AACH,MAAM,CAAN,IAAY,YAeX;AAfD,WAAY,YAAY;IACpB,wCAAwC;IACxC,iDAAiC,CAAA;IAEjC,6CAA6C;IAC7C,6CAA6B,CAAA;IAE7B,8BAA8B;IAC9B,iDAAiC,CAAA;IAEjC,kCAAkC;IAClC,mDAAmC,CAAA;IAEnC,2DAA2D;IAC3D,uEAAuD,CAAA;AAC3D,CAAC,EAfW,YAAY,KAAZ,YAAY,QAevB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACtB,wDAAwD;IACxD,mDAAiC,CAAA;IAEjC,sDAAsD;IACtD,qDAAmC,CAAA;IAEnC,qCAAqC;IACrC,2CAAyB,CAAA;IAEzB,+BAA+B;IAC/B,iDAA+B,CAAA;AACnC,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAwCD;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAc;IACzC,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK,EAAE,WAAW;IAC9B,mBAAmB,EAAE,EAAE,EAAE,uBAAuB;IAChD,qBAAqB,EAAE,IAAI;IAC3B,kBAAkB,EAAE,EAAE;IACtB,mBAAmB,EAAE,EAAE;IACvB,qBAAqB,EAAE,EAAE;IACzB,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,KAAK;IACZ,kBAAkB,EAAE,GAAG;IACvB,sBAAsB,EAAE,EAAE;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,OAAO,EAAE,kBAAkB;IAC3B,YAAY,EAAE,kBAAkB;IAChC,sBAAsB,EAAE,4BAA4B;IACpD,wBAAwB,EAAE,8BAA8B;IACxD,qBAAqB,EAAE,2BAA2B;IAClD,sBAAsB,EAAE,4BAA4B;IACpD,wBAAwB,EAAE,8BAA8B;IACxD,WAAW,EAAE,iBAAiB;IAC9B,KAAK,EAAE,WAAW;IAClB,qBAAqB,EAAE,2BAA2B;IAClD,yBAAyB,EAAE,+BAA+B;CACpD,CAAC"}