@orbytautomation/engine 0.2.4 → 0.3.0

package/dist/errors/FieldRegistry.js

@@ -11,53 +11,61 @@
 /**
  * Valid fields at workflow root level
  * MUST stay in sync with OrbytWorkflowSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const ROOT_FIELDS = [
-    // Core required fields
-    'version',
-    'kind',
-    'workflow',
-    // Configuration fields
-    'metadata',
-    'annotations',
-    'triggers',
-    'secrets',
-    'inputs',
-    'context',
-    'defaults',
-    'policies',
-    'permissions',
-    'resources',
-    'outputs',
-    'on',
-    'usage',
+    // Core required fields (REQUIRED)
+    'version', // Schema version (semantic versioning)
+    'kind', // Type of executable (workflow, pipeline, job, playbook, automation)
+    'workflow', // Core workflow execution definition
+    // Optional metadata & documentation
+    'metadata', // Human-readable metadata
+    'annotations', // Zero-impact annotations for tooling
+    // Execution configuration
+    'triggers', // Execution triggers (manual, cron, event, webhook)
+    'secrets', // External secret references
+    'inputs', // Runtime parameters
+    'context', // Runtime environment context
+    'defaults', // Default settings for all steps
+    'policies', // Execution policies
+    'permissions', // Security permissions
+    'resources', // Resource constraints (future)
+    // Outputs & hooks
+    'outputs', // Final workflow outputs returned to caller
+    'on', // Lifecycle hooks (success, failure, always) - future
+    // Usage tracking
+    'usage', // Usage tracking configuration (production)
     // Production-ready universal fields
-    'strategy',
-    'profiles',
-    'compliance',
-    'provenance',
-    'execution',
-    'outputsSchema',
-    'telemetry',
-    'accounting',
-    'compatibility',
-    'failurePolicy',
-    'rollback',
-    'governance',
+    'strategy', // Execution strategy (production)
+    'profiles', // Environment-specific profiles (future)
+    // Future-safe fields
+    'compliance', // Compliance metadata (future)
+    'provenance', // Provenance tracking (future: AI-generated workflows)
+    'execution', // Execution strategy (future: multi-environment)
+    'outputsSchema', // Output schema for validation (future)
+    'telemetry', // Telemetry controls (future)
+    'accounting', // Cost and usage accounting (future)
+    'compatibility', // Version compatibility (future)
+    'failurePolicy', // Failure semantics (future)
+    'rollback', // Rollback configuration (future)
+    'governance', // Governance metadata (future: enterprise)
 ];
 /**
  * Valid fields in metadata object
+ * MUST stay in sync with MetadataSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const METADATA_FIELDS = [
-    'name',
-    'description',
-    'tags',
-    'owner',
-    'version',
-    'createdAt',
-    'updatedAt',
-    'v1',
-    'future',
+    'name', // Human-readable workflow name
+    'description', // Detailed workflow description
+    'tags', // Categorization tags
+    'owner', // Owner team or individual
+    'version', // Workflow version (not schema version)
+    'createdAt', // Creation timestamp
+    'updatedAt', // Last update timestamp
+    // Version tracking flags (future-safe)
+    'v1', // Marks workflow as using v1 features
+    'future', // Marks workflow as using future/experimental features
 ];
 /**
  * Valid fields in workflow body
@@ -68,62 +76,72 @@ export const WORKFLOW_FIELDS = [
 /**
  * Valid fields in step definition
  * MUST stay in sync with StepSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const STEP_FIELDS = [
     // Core required fields
-    'id',
-    'uses',
-    // Common fields
-    'name',
-    'with',
-    'when',
-    'needs',
-    'retry',
-    'timeout',
-    'continueOnError',
-    'outputs',
-    'env',
-    'usage',
+    'id', // Unique step identifier (must start with letter)
+    'uses', // Action to execute (namespace.action format)
+    // Common optional fields
+    'name', // Human-readable step name
+    'with', // Adapter-specific input parameters
+    'when', // Conditional execution expression
+    'needs', // Explicit step dependencies
+    'retry', // Step-specific retry config
+    'timeout', // Step execution timeout (e.g., '30s', '5m')
+    'continueOnError', // Continue workflow even if step fails
+    'outputs', // Map step outputs to named values
+    'env', // Environment variables for this step
+    // Usage tracking (production)
+    'usage', // Usage tracking override (per-step billing)
     // Production-ready universal fields
-    'ref',
-    'requires',
-    'hints',
-    'contracts',
-    'profiles',
-    'onFailure',
-    'telemetry',
-    'rollback',
+    'ref', // Versioned step reference (e.g., @^1)
+    'requires', // Capability requirements (future)
+    'hints', // Execution hints for optimization (future)
+    'contracts', // Data contracts for validation (future)
+    'profiles', // Environment-specific profiles (future)
+    'onFailure', // Failure handling configuration (future)
+    'telemetry', // Telemetry configuration (future)
+    'rollback', // Step-level rollback logic (future)
 ];
 /**
  * Valid fields in secrets config
+ * MUST stay in sync with SecretsSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const SECRETS_FIELDS = [
-    'vault',
-    'keys',
+    'vault', // Secret vault provider (default: 'vaulta')
+    'keys', // Map of logical names to provider-specific secret paths
 ];
 /**
  * Valid fields in context config
+ * MUST stay in sync with ContextSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const CONTEXT_FIELDS = [
-    'env',
-    'platform',
-    'workspace',
+    'env', // Environment (local, dev, staging, prod)
+    'platform', // Platform identifier
+    'workspace', // Workspace path
 ];
 /**
  * Valid fields in defaults config
+ * MUST stay in sync with DefaultsSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const DEFAULTS_FIELDS = [
-    'retry',
-    'timeout',
-    'adapter',
+    'retry', // Default retry configuration
+    'timeout', // Default step timeout (e.g., '30s')
+    'adapter', // Default adapter
 ];
 /**
  * Valid fields in policies config
+ * MUST stay in sync with PoliciesSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const POLICIES_FIELDS = [
-    'failure',
-    'concurrency',
-    'sandbox',
+    'failure', // Failure policy (stop, continue, isolate)
+    'concurrency', // Max concurrent steps
+    'sandbox', // Sandbox level (none, basic, strict)
 ];
 /**
  * Valid fields in permissions config
@@ -134,11 +152,13 @@ export const PERMISSIONS_FIELDS = [
 ];
 /**
  * Valid fields in retry config
+ * MUST stay in sync with RetryConfigSchema in @dev-ecosystem/core
+ * Last synced: 2026-02-15
  */
 export const RETRY_FIELDS = [
-    'max',
-    'backoff',
-    'delay',
+    'max', // Maximum retry attempts
+    'backoff', // Backoff strategy (linear, exponential)
+    'delay', // Initial delay in milliseconds
 ];
 /**
  * Valid fields in usage tracking config
@@ -162,6 +182,84 @@ export const STEP_USAGE_FIELDS = [
     'unit',
     'weight',
 ];
+// ============================================================================
+// RESERVED/INTERNAL FIELDS (Engine-controlled, users cannot set these)
+// ============================================================================
+/**
+ * Reserved workflow-level fields (engine-controlled, NEVER user-set)
+ * These fields would trigger SecurityError if found in user YAML
+ * MUST stay in sync with RESERVED_WORKFLOW_FIELDS in security/ReservedFields.ts
+ * Last synced: 2026-02-15
+ */
+export const RESERVED_WORKFLOW_FIELDS = [
+    '_internal', // Internal execution context
+    '_identity', // Execution identity (executionId, runId, traceId)
+    '_ownership', // Ownership context (userId, workspaceId, subscriptionId)
+    '_billing', // Billing context (billingId, pricingTier, costCalculated)
+    '_usage', // Usage tracking counters
+    '_audit', // Audit trail fields
+    '_system', // System fields
+    '_engine', // Engine metadata
+    '_execution', // Execution context (internal)
+    '_runtime', // Runtime context (internal)
+    '_security', // Security context
+    '_metadata', // Internal metadata
+];
+/**
+ * Reserved context fields (engine-controlled, users cannot set in context)
+ * MUST stay in sync with RESERVED_CONTEXT_FIELDS in security/ReservedFields.ts
+ * Last synced: 2026-02-15
+ */
+export const RESERVED_CONTEXT_FIELDS = [
+    '_internal',
+    '_identity',
+    '_ownership',
+    '_billing',
+    '_usage',
+    '_audit',
+    '_system',
+    '_engine',
+    '_security',
+    'executionId',
+    'runId',
+    'traceId',
+    'userId',
+    'workspaceId',
+    'subscriptionId',
+    'subscriptionTier',
+    'billingId',
+    'billingMode',
+    'pricingTier',
+    'pricingModel',
+    'billingSnapshot',
+];
+/**
+ * Reserved step fields (engine-controlled, users cannot set in steps)
+ * MUST stay in sync with RESERVED_STEP_FIELDS in security/ReservedFields.ts
+ * Last synced: 2026-02-15
+ */
+export const RESERVED_STEP_FIELDS = [
+    '_internal',
+    '_billing',
+    '_usage',
+    '_audit',
+    'executionId',
+    'runId',
+    'stepExecutionId',
+];
+/**
+ * Reserved annotation prefixes (engine-controlled namespaces)
+ * MUST stay in sync with RESERVED_ANNOTATION_PREFIXES in security/ReservedFields.ts
+ * Last synced: 2026-02-15
+ */
+export const RESERVED_ANNOTATION_PREFIXES = [
+    'engine.',
+    'system.',
+    'internal.',
+    'billing.',
+    'audit.',
+    'security.',
+];
 /**
  * Field registry map - maps path prefixes to valid fields
  */

package/dist/errors/FieldRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"FieldRegistry.js","sourceRoot":"","sources":["../../src/errors/FieldRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,uBAAuB;IACvB,SAAS;IACT,MAAM;IACN,UAAU;IAEV,uBAAuB;IACvB,UAAU;IACV,aAAa;IACb,UAAU;IACV,SAAS;IACT,QAAQ;IACR,SAAS;IACT,UAAU;IACV,UAAU;IACV,aAAa;IACb,WAAW;IACX,SAAS;IACT,IAAI;IACJ,OAAO;IAEP,oCAAoC;IACpC,UAAU;IACV,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,eAAe;IACf,WAAW;IACX,YAAY;IACZ,eAAe;IACf,eAAe;IACf,UAAU;IACV,YAAY;CACJ,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM;IACN,aAAa;IACb,MAAM;IACN,OAAO;IACP,SAAS;IACT,WAAW;IACX,WAAW;IACX,IAAI;IACJ,QAAQ;CACA,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO;CACC,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,uBAAuB;IACvB,IAAI;IACJ,MAAM;IAEN,gBAAgB;IAChB,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,SAAS;IACT,iBAAiB;IACjB,SAAS;IACT,KAAK;IACL,OAAO;IAEP,oCAAoC;IACpC,KAAK;IACL,UAAU;IACV,OAAO;IACP,WAAW;IACX,UAAU;IACV,WAAW;IACX,WAAW;IACX,UAAU;CACF,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO;IACP,MAAM;CACE,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK;IACL,UAAU;IACV,WAAW;CACH,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO;IACP,SAAS;IACT,SAAS;CACD,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS;IACT,aAAa;IACb,SAAS;CACD,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI;IACJ,SAAS;CACD,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK;IACL,SAAS;IACT,OAAO;CACC,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,SAAS;IACT,MAAM;CACE,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,UAAU;IACV,MAAM;IACN,QAAQ;CACA,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsC;IAC/D,MAAM,EAAE,WAAW;IACnB,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE,eAAe;IAC3B,gBAAgB,EAAE,WAAW;IAC7B,SAAS,EAAE,cAAc;IACzB,SAAS,EAAE,cAAc;IACzB,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE,eAAe;IAC3B,aAAa,EAAE,kBAAkB;IACjC,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;IACrB,YAAY,EAAE,iBAAiB;CAChC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,0BAA0B;IAC1B,IAAI,IAAI,IAAI,cAAc,EAAE,CAAC;QAC3B,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAC3C,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,0CAA0C;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAC3D,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;YAC/B,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,4CAA4C;IAC5C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,IAAY;IACtD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,WAAW,CAAC,QAAQ,CAAC,KAAY,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"FieldRegistry.js","sourceRoot":"","sources":["../../src/errors/FieldRegistry.ts"],"names":[],"mappings":"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"}

package/dist/errors/OrbytError.d.ts

@@ -4,37 +4,72 @@
  * Foundation for all Orbyt errors with diagnostic capabilities.
  * Provides structured error information for CLI, UI, and AI integrations.
  *
+ * ARCHITECTURE:
+ * - Error codes (ORB-XX-NNN): Structured codes for error identification
+ * - Exit codes (from @dev-ecosystem/core): Process exit codes for shell scripts
+ * - Severity levels: ERROR, WARNING, INFO
+ * - Context + hints: Help users debug and fix issues
+ *
  * @module errors
  */
+import { ExitCodes } from '@dev-ecosystem/core';
 import { OrbytErrorCode, ErrorSeverity } from './ErrorCodes.js';
 /**
  * Diagnostic error information
+ * Contains all data needed to understand and debug an error
  */
 export interface OrbytErrorDiagnostic {
-    /** Stable error code */
+    /** Structured error code (e.g., ORB-S-001) */
     code: OrbytErrorCode;
     /** Human-readable error message */
     message: string;
+    /** Process exit code from ecosystem-core (for CLI) */
+    exitCode?: ExitCodes;
     /** Path to the error location (e.g., "workflow.steps[2].uses") */
     path?: string;
     /** Optional suggestion for fixing the error */
     hint?: string;
-    /** Error severity */
+    /** Error severity (ERROR, WARNING, INFO) */
     severity: ErrorSeverity;
-    /** Additional context data */
+    /** Additional context data for debugging */
     context?: Record<string, any>;
 }
 /**
  * Base error class for all Orbyt errors
+ *
+ * Provides rich diagnostic information including:
+ * - Structured error code
+ * - Exit code for process termination
+ * - Location in workflow where error occurred
+ * - Hints for fixing the error
+ * - Additional context for debugging
+ *
+ * @example
+ * ```typescript
+ * throw new OrbytError({
+ *   code: OrbytErrorCode.SCHEMA_MISSING_FIELD,
+ *   message: 'Missing required field "version"',
+ *   exitCode: ExitCodes.INVALID_SCHEMA,
+ *   path: 'workflow',
+ *   hint: 'Add "version: 1.0" to your workflow definition',
+ *   severity: ErrorSeverity.ERROR,
+ * });
+ * ```
  */
 export declare class OrbytError extends Error {
     /** Error diagnostic information */
     readonly diagnostic: OrbytErrorDiagnostic;
+    /** Timestamp when error occurred */
+    readonly timestamp: Date;
     constructor(diagnostic: OrbytErrorDiagnostic);
     /**
      * Get the error code
      */
     get code(): OrbytErrorCode;
+    /**
+     * Get the exit code for process termination
+     */
+    get exitCode(): ExitCodes;
     /**
      * Get the error path (where it occurred)
      */
@@ -47,13 +82,60 @@ export declare class OrbytError extends Error {
      * Get error severity
      */
     get severity(): ErrorSeverity;
+    /**
+     * Get detailed error description
+     */
+    get description(): string;
+    /**
+     * Check if this is a user-fixable error
+     * @returns True if user can fix by changing workflow
+     */
+    get isUserError(): boolean;
+    /**
+     * Check if this error is retryable
+     * @returns True if retry might succeed
+     */
+    get isRetryable(): boolean;
+    /**
+     * Get error category (Schema, Validation, Execution, Runtime)
+     */
+    get category(): string;
     /**
      * Format error as string for logging/display
+     * Includes all diagnostic information in a readable format
+     *
+     * @returns Formatted error string
      */
     toString(): string;
+    /**
+     * Format error as detailed string with full diagnostic info
+     * Used for verbose logging and debugging
+     *
+     * @returns Detailed formatted error string with box drawing
+     */
+    toDetailedString(): string;
+    /**
+     * Get human-readable description of exit code
+     */
+    getExitCodeDescription(): string;
     /**
      * Convert to JSON for structured logging
+     * Suitable for sending to logging services, APIs, or storing in databases
+     *
+     * @returns JSON representation of error
      */
     toJSON(): object;
+    /**
+     * Create a simplified error object for CLI display
+     * Contains only essential information for user-facing output
+     *
+     * @returns Simplified error object
+     */
+    toSimpleObject(): {
+        code: string;
+        message: string;
+        hint?: string;
+        path?: string;
+    };
 }
 //# sourceMappingURL=OrbytError.d.ts.map

package/dist/errors/OrbytError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrbytError.d.ts","sourceRoot":"","sources":["../../src/errors/OrbytError.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAoB,MAAM,iBAAiB,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,IAAI,EAAE,cAAc,CAAC;IAErB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAEhB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,qBAAqB;IACrB,QAAQ,EAAE,aAAa,CAAC;IAExB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,mCAAmC;IACnC,SAAgB,UAAU,EAAE,oBAAoB,CAAC;gBAErC,UAAU,EAAE,oBAAoB;IAW5C;;OAEG;IACH,IAAI,IAAI,IAAI,cAAc,CAEzB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED;;OAEG;IACH,QAAQ,IAAI,MAAM;IAgBlB;;OAEG;IACH,MAAM,IAAI,MAAM;CAWjB"}
+{"version":3,"file":"OrbytError.d.ts","sourceRoot":"","sources":["../../src/errors/OrbytError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EACL,cAAc,EACd,aAAa,EAOd,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,cAAc,CAAC;IAErB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAEhB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,QAAQ,EAAE,aAAa,CAAC;IAExB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,mCAAmC;IACnC,SAAgB,UAAU,EAAE,oBAAoB,CAAC;IAEjD,oCAAoC;IACpC,SAAgB,SAAS,EAAE,IAAI,CAAC;gBAEpB,UAAU,EAAE,oBAAoB;IAkB5C;;OAEG;IACH,IAAI,IAAI,IAAI,cAAc,CAEzB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,SAAS,CAExB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;OAGG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;OAKG;IACH,QAAQ,IAAI,MAAM;IAoBlB;;;;;OAKG;IACH,gBAAgB,IAAI,MAAM;IAyC1B;;OAEG;IACH,sBAAsB,IAAI,MAAM;IAUhC;;;;;OAKG;IACH,MAAM,IAAI,MAAM;IAkBhB;;;;;OAKG;IACH,cAAc,IAAI;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf;CAQF"}