import { tags } from "typia";
import { AutoBeOpenApi } from "../openapi/AutoBeOpenApi";
import { CamelCasePattern } from "../typings/CamelCasePattern";
/**
 * AST type system for programmatic E2E test function generation through AI
 * function calling.
 *
 * This namespace defines a comprehensive Abstract Syntax Tree structure that
 * enables AI agents to construct complete E2E test functions at the AST level.
 * Each type corresponds to specific TypeScript language constructs, allowing
 * precise control over generated test code while maintaining type safety and
 * business logic accuracy.
 *
 * ## Core Purpose
 *
 * The system is designed for systematic generation where AI function calls
 * build test scenarios step-by-step, mapping business requirements to
 * executable code. Instead of generating raw TypeScript strings, AI agents
 * construct structured AST objects that represent:
 *
 * - Complete test function flows with proper data dependencies
 * - Realistic API call sequences with captured responses
 * - Comprehensive validation using TestValidator assertions
 * - Complex business logic with conditional flows and error handling
 *
 * ## Architecture Overview
 *
 * - **IFunction**: Root container representing complete test functions
 * - **Statements**: Building blocks for test logic (API operations, expressions,
 *   conditionals)
 * - **Expressions**: Value computations, API calls, data access, and validations
 * - **Literals**: Direct values for realistic business data
 * - **Random Generators**: Dynamic test data creation with business constraints
 * - **Predicates**: TestValidator assertions for comprehensive validation
 *
 * ## Business Context
 *
 * In E2E testing, this typically maps to complete business scenarios like:
 *
 * - Customer purchase workflows (registration → product selection → payment →
 *   confirmation)
 * - Seller product management (authentication → product creation → inventory
 *   management)
 * - Multi-role interactions (seller creates product → customer purchases → admin
 *   processes)
 *
 * Each generated function represents a realistic business workflow with proper
 * data flow, where API responses from earlier steps provide inputs for
 * subsequent operations, creating authentic test scenarios that mirror
 * real-world application usage.
 *
 * @author Samchon
 * @note This namespace documentation is excluded from AI function calling schemas
 */
export declare namespace AutoBeTest {
    /**
     * Root interface representing a complete E2E test function.
     *
     * This serves as the top-level container for all statements that comprise a
     * test function. Each statement in the array represents a logical step in the
     * test scenario, enabling systematic construction of complex business
     * workflows through AI function calling.
     *
     * The generation process follows a three-stage approach: planning, drafting,
     * and AST construction. This ensures that AI agents create well-structured,
     * comprehensive test functions through deliberate design phases.
     *
     * In the context of E2E testing, this typically maps to complete business
     * scenarios like "customer purchase flow" or "seller product management",
     * where each statement handles one aspect of the workflow.
     */
    interface IFunction {
        /**
         * Strategic plan for implementing the test scenario.
         *
         * This field requires AI agents to think through the test implementation
         * strategy before generating actual statements. It should analyze the given
         * scenario and determine the optimal approach for creating a comprehensive
         * test function.
         *
         * The plan should address:
         *
         * - Key business entities and their relationships that need to be tested
         * - Sequence of operations required to achieve the test scenario
         * - Data dependencies between different test steps
         * - Validation points where business rules should be verified
         * - Error conditions and edge cases that should be tested
         * - Overall test structure and organization
         *
         * This planning step ensures that the generated statements follow a logical
         * progression and create a realistic, comprehensive test scenario that
         * properly validates the business workflow.
         */
        plan: string;
        /**
         * Draft TypeScript code implementation of the test function.
         *
         * This field contains a preliminary TypeScript implementation of the test
         * function based on the strategic plan. The draft serves as an intermediate
         * step between planning and AST construction, allowing AI agents to:
         *
         * - Visualize the actual code structure before AST generation
         * - Ensure proper TypeScript syntax and API usage patterns
         * - Validate the logical flow and data dependencies
         * - Identify any missing components or validation steps
         * - Refine the approach before committing to AST statements
         *
         * The draft should be complete, executable TypeScript code that represents
         * the full test function implementation. This code will then be analyzed
         * and converted into the corresponding AST statements structure.
         *
         * **⚠️ CRITICAL: Avoid TypeScript features that complicate AST conversion!
         * ⚠️**
         *
         * **❌ AVOID**: Template literals, destructuring, for/while loops, switch
         * statements, try/catch blocks, spread operators, arrow functions without
         * blocks
         *
         * **✅ USE**: Simple property access, explicit API operations, array methods
         * (arrayMap, arrayForEach), predicate functions, clear if/else chains
         */
        draft: string;
        /**
         * Array of statements that comprise the test function body.
         *
         * Each statement represents a discrete step in the test scenario, typically
         * corresponding to business actions like API calls, validations, or state
         * transitions. The order is significant as it reflects the logical flow of
         * the business process.
         *
         * These statements should be generated by analyzing and converting the
         * draft TypeScript code into structured AST representations, ensuring that
         * the implementation follows the predetermined approach and creates a
         * complete data flow chain representing the business scenario.
         *
         * **⚠️ CRITICAL: Convert unsupported TypeScript features to AutoBeTest AST
         * equivalents! ⚠️**
         *
         * - Template literals → String concatenation with IBinaryExpression
         * - Destructuring → Separate IPropertyAccessExpression statements
         * - Loops → IArrayForEachExpression/IArrayMapExpression
         * - Switch statements → Nested IIfStatement chains
         * - Try/catch → IErrorPredicate for error testing
         *
         * **🚨 CRITICAL: DO NOT PUT EXPRESSIONS DIRECTLY IN STATEMENTS ARRAY! 🚨**
         *
         * This array ONLY accepts `IStatement` types. If you need to execute an
         * expression (like predicates, function calls, etc.), you MUST wrap it in
         * `IExpressionStatement`:
         *
         * **❌ WRONG - Expression directly in statements array**:
         *
         * ```typescript
         * statements: [
         *   { type: "apiOperateStatement", ... },
         *   { type: "equalPredicate", ... }  // ❌ This is IExpression, not IStatement!
         * ]
         * ```
         *
         * **✅ CORRECT - Expression wrapped in IExpressionStatement**:
         *
         * ```typescript
         * statements: [
         *   { type: "apiOperateStatement", ... },
         *   {
         *     type: "expressionStatement",  // ✅ Statement wrapper
         *     expression: {
         *       type: "equalPredicate", ... // ✅ Expression properly contained
         *     }
         *   }
         * ]
         * ```
         *
         * **Statement Types (can go directly in array)**:
         *
         * - `IApiOperateStatement`
         * - `IExpressionStatement`
         * - `IIfStatement`
         * - `IReturnStatement`
         * - `IThrowStatement`
         *
         * **Expression Types (must be wrapped in IExpressionStatement)**:
         *
         * - `IEqualPredicate`, `IConditionalPredicate`, `IErrorPredicate`, etc.
         * - `ICallExpression`
         * - All literal types and random generators
         * - Any other `IExpression` type
         *
         * AI function calling strategy: Build statements by parsing the draft code
         * and converting each logical operation into appropriate AST statement
         * types, maintaining the data dependencies and business logic flow
         * established in the draft. Always verify that you're using statement
         * types, not expression types directly.
         */
        statements: IStatement[] & tags.MinItems<1>;
    }
    /**
     * Union type representing all possible statement types in test functions.
     *
     * Statements are the building blocks of test function logic, each serving
     * specific purposes in the E2E testing context:
     *
     * - IApiOperateStatement: Primary mechanism for all SDK API operations with
     *   automatic response handling and data capture
     * - IExpressionStatement: Execute utility functions and validations without
     *   value capture
     * - IIfStatement: Handle conditional business logic (prefer predicates for
     *   validation)
     * - IReturnStatement: Function termination (rarely used in tests)
     * - IThrowStatement: Explicit error scenarios
     *
     * Note: IBlockStatement is intentionally excluded from this union as it
     * should only be used in special contexts (like if/else branches) rather than
     * as a general statement type in the main function flow.
     *
     * AI selection strategy: Choose statement type based on the business action
     * being performed. Use IApiOperateStatement for all API operations with
     * automatic data capture, predicates for validations, and other statement
     * types for specific non-API needs.
     */
    type IStatement = IApiOperateStatement | IExpressionStatement | IIfStatement | IReturnStatement | IThrowStatement;
    /**
     * Block for grouping statements in specific structural contexts.
     *
     * **SPECIAL USE ONLY**: This type represents a block of statements and should
     * only be used in specific contexts where statement grouping is structurally
     * required:
     *
     * - If/else statement branches
     *
     *   - {@link IIfStatement.thenStatement}
     *   - {@link IIfStatement.elseStatement}
     * - Arrow function bodies: {@link IArrowFunction.body}
     * - Other contexts requiring explicit block scoping
     *
     * Unlike a block statement, this is not a statement itself but a structural
     * container for statements. For normal test function flow, use individual
     * statements directly rather than wrapping them in blocks.
     *
     * **Updated for API-first workflow**: Blocks can now contain
     * `IApiOperateStatement` for API operations with automatic data capture,
     * predicate expressions for validations, and other statement types as needed
     * within conditional logic or function bodies.
     *
     * AI function calling restriction: Do not use for general statement grouping
     * in main function flow. Reserve for structural requirements only
     * (conditional branches, function bodies).
     */
    interface IBlock {
        /** Type discriminator. */
        type: "block";
        /**
         * Nested statements within this block.
         *
         * Each statement represents a step within the grouped operation. Can
         * include any valid statement type:
         *
         * - `IApiOperateStatement` for API operations with automatic data capture
         *   within conditional logic
         * - Predicate expressions for validations within blocks
         * - Other statement types as needed for the block's purpose
         *
         * Maintains the same ordering significance as the root function's
         * statements array.
         *
         * **🚨 CRITICAL: DO NOT PUT EXPRESSIONS DIRECTLY IN STATEMENTS ARRAY! 🚨**
         *
         * This array ONLY accepts `IStatement` types. If you need to execute an
         * expression (like predicates, function calls, etc.), you MUST wrap it in
         * `IExpressionStatement`:
         *
         * **❌ WRONG - Expression directly in statements array**:
         *
         * ```typescript
         * statements: [
         *   { type: "apiOperateStatement", ... },
         *   { type: "conditionalPredicate", ... }  // ❌ This is IExpression, not IStatement!
         * ]
         * ```
         *
         * **✅ CORRECT - Expression wrapped in IExpressionStatement**:
         *
         * ```typescript
         * statements: [
         *   { type: "apiOperateStatement", ... },
         *   {
         *     type: "expressionStatement",  // ✅ Statement wrapper
         *     expression: {
         *       type: "conditionalPredicate", ... // ✅ Expression properly contained
         *     }
         *   }
         * ]
         * ```
         *
         * **Statement Types (can go directly in array)**:
         *
         * - `IApiOperateStatement`
         * - `IExpressionStatement`
         * - `IIfStatement`
         * - `IReturnStatement`
         * - `IThrowStatement`
         *
         * **Expression Types (must be wrapped in IExpressionStatement)**:
         *
         * - `IEqualPredicate`, `IConditionalPredicate`, etc.
         * - `ICallExpression`
         * - All literal types and random generators
         * - Any other `IExpression` type
         *
         * Example business context - Block: "Premium Customer Workflow"
         *
         * - API operation: Verify premium status (with automatic data capture)
         * - API operation: Access exclusive content (with automatic data capture)
         * - Predicate: Validate premium features are available (wrapped in
         *   expressionStatement)
         * - API operation: Log premium usage (with automatic data capture)
         */
        statements: IStatement[] & tags.MinItems<1>;
    }
    /**
     * API operation statement for SDK function calls with automatic response
     * handling and data capture.
     *
     * This statement type handles the complete lifecycle of API operations
     * including:
     *
     * 1. Executing API function calls through the SDK
     * 2. Automatically capturing the response in a variable (when variableName is
     *    provided)
     * 3. Performing runtime type assertion using typia.assert<T>() for type safety
     *
     * This is the primary mechanism for all API interactions in E2E test
     * scenarios, providing integrated data capture that eliminates the need for
     * separate variable declarations.
     *
     * The statement automatically handles the complex pattern of API calling,
     * response capturing, and type validation that is essential for robust E2E
     * testing.
     *
     * AI function calling importance: Use this for ALL SDK API operations to
     * ensure proper response handling, automatic data capture, and type safety in
     * business test scenarios.
     */
    interface IApiOperateStatement {
        /** Type discriminator. */
        type: "apiOperateStatement";
        /**
         * API endpoint specification defining the operation to be called.
         *
         * Contains the HTTP method and path information that identifies which
         * specific API operation from the OpenAPI specification should be invoked.
         * This corresponds to operations defined in the AutoBeOpenApi.IDocument.
         *
         * The endpoint determines the expected parameter types, request body
         * schema, and response body schema for proper type validation.
         */
        endpoint: AutoBeOpenApi.IEndpoint;
        /**
         * Single argument object for the API function call.
         *
         * **CRITICAL**: All API functions accept exactly one object parameter that
         * contains all necessary data for the operation. This argument object is
         * constructed based on the API operation's specification and follows a
         * standardized structure.
         *
         * **⚠️ CRITICAL AI RESTRICTION: This MUST be an AST expression, NOT a JSON
         * value! ⚠️** **❌ WRONG: { "name": "John", "age": 30 } (raw JSON object)**
         * **✅ CORRECT: IObjectLiteralExpression with proper AST structure**
         *
         * **Object Structure Rules:**
         *
         * The argument object is constructed by combining path parameters and
         * request body data according to the following rules based on the target
         * {@link AutoBeOpenApi.IOperation}:
         *
         * 1. **Path Parameters**: Each parameter from
         *    `AutoBeOpenApi.IOperation.parameters` becomes a property in the
         *    argument object, where:
         *
         *    - Property name: `AutoBeOpenApi.IParameter.name`
         *    - Property value: Expression matching `AutoBeOpenApi.IParameter.schema`
         *    - Example: `{ saleId: "uuid-string", customerId: "another-uuid" }`
         * 2. **Request Body**: If `AutoBeOpenApi.IOperation.requestBody` exists:
         *
         *    - Add a `body` property containing the request body data
         *    - Value type: Object literal matching the requestBody's typeName schema
         *    - Example: `{ body: { name: "Product Name", price: 99.99 } }`
         * 3. **Combined Structure**: When both path parameters and request body exist:
         *
         *    ```typescript
         *    {
         *      // Path parameters as individual properties
         *      "saleId": "uuid-value",
         *      "customerId": "another-uuid",
         *      // Request body as 'body' property
         *      "body": {
         *        "name": "Updated Product",
         *        "price": 149.99,
         *        "description": "Enhanced product description"
         *      }
         *    }
         *    ```
         *
         * **Special Cases:**
         *
         * - **No Parameters**: When `parameters` is empty array AND `requestBody` is
         *   null, set this to `null` (the API function requires no arguments)
         * - **Only Path Parameters**: When `requestBody` is null but `parameters`
         *   exist, create object with only path parameter properties
         * - **Only Request Body**: When `parameters` is empty but `requestBody`
         *   exists, create object with only the `body` property
         *
         * **AI Construction Strategy:**
         *
         * 1. Analyze the target `AutoBeOpenApi.IOperation` specification
         * 2. Extract all path parameters and create corresponding object properties
         * 3. If request body exists, add it as the `body` property
         * 4. Ensure all property values match the expected types from OpenAPI schema
         * 5. Use realistic business data that reflects actual API usage patterns
         *
         * **Type Safety Requirements:**
         *
         * - Path parameter values must match their schema types (string, integer,
         *   etc.)
         * - Request body structure must exactly match the referenced schema type
         * - All required properties must be included with valid values
         * - Optional properties can be omitted or included based on test scenario
         *   needs
         *
         * **Business Context Examples:**
         *
         * ```typescript
         * // GET /customers/{customerId}/orders/{orderId} (no request body)
         * {
         *   customerId: "cust-123",
         *   orderId: "order-456"
         * }
         *
         * // POST /customers (only request body)
         * {
         *   body: {
         *     name: "John Doe",
         *     email: "john@example.com",
         *     phone: "+1-555-0123"
         *   }
         * }
         *
         * // PUT /customers/{customerId}/orders/{orderId} (both path params and body)
         * {
         *   customerId: "cust-123",
         *   orderId: "order-456",
         *   body: {
         *     status: "shipped",
         *     trackingNumber: "TRACK123",
         *     estimatedDelivery: "2024-12-25"
         *   }
         * }
         *
         * // GET /health (no parameters or body)
         * null
         * ```
         */
        argument?: IObjectLiteralExpression | null;
        /**
         * Optional variable name for capturing the API response with automatic data
         * handling.
         *
         * **Conditional Usage:**
         *
         * - `string`: When API operation returns data that needs to be captured
         *
         *   - Creates: `const variableName: ApiResponseType =
         *       typia.assert<ResponseType>(await api.operation(...))`
         *   - The response is automatically type-validated using typia.assert
         *   - Variable can be referenced in subsequent test steps for data flow
         * - `null`: When API operation returns void or response is not needed
         *
         *   - Creates: `await api.operation(...)`
         *   - No variable assignment or type assertion is performed
         *   - Typically used for operations like delete, logout, or fire-and-forget
         *       calls
         *
         * **AI Decision Logic:**
         *
         * - Set to meaningful variable name when the response contains business data
         *   needed for subsequent operations
         * - Set to null when the operation is void or side-effect only
         * - Consider if subsequent test steps need to reference the response data for
         *   business logic or validations
         *
         * Variable naming should follow business domain conventions (e.g.,
         * "customer", "order", "product") rather than technical naming. This
         * automatic data capture eliminates the need for separate variable
         * declaration statements.
         */
        variableName?: (string & CamelCasePattern) | null;
    }
    /**
     * Expression statement for executing utility operations without value
     * capture.
     *
     * **IMPORTANT: For API operations, use `IApiOperateStatement` instead.** This
     * statement type is primarily for utility operations that don't require
     * capturing return values, and where the operation's side effect or
     * validation is more important than its return value.
     *
     * Common E2E testing scenarios:
     *
     * - Validation assertions using TestValidator predicates (when not using
     *   predicate expressions)
     * - Utility function calls (console.log, debugging functions)
     * - Non-API side-effect operations
     * - Cleanup operations that don't involve API calls
     *
     * **Note**: For most validation cases, prefer using predicate expressions
     * (IEqualPredicate, IConditionalPredicate, etc.) instead of expression
     * statements with TestValidator calls.
     *
     * AI function calling usage: Select when the business action's execution is
     * the goal, not data capture, and when the operation is NOT an API call.
     */
    interface IExpressionStatement {
        /** Type discriminator. */
        type: "expressionStatement";
        /**
         * The expression to be executed as a statement.
         *
         * **Should NOT contain API function calls** - use `IApiOperateStatement`
         * for those instead.
         *
         * Typically represents utility operations:
         *
         * - TestValidator function calls (though predicates are preferred)
         * - Console operations for debugging
         * - Non-API utility function invocations
         * - Side-effect operations that don't involve the API
         *
         * The expression's result is discarded, making this suitable for
         * void-returning operations or when return values are not needed for
         * subsequent test steps.
         *
         * Most commonly contains ICallExpression for utility invocations.
         */
        expression: IExpression;
    }
    /**
     * Conditional statement for business rule-based test flow control.
     *
     * Enables test scenarios to branch based on runtime conditions or business
     * rules. This should be used for genuine business logic branching where
     * different test paths are needed based on data state or business
     * conditions.
     *
     * **IMPORTANT: For validation purposes, prefer predicate expressions
     * instead:**
     *
     * - Use `IEqualPredicate` instead of `if (x === y) throw new Error(...)`
     * - Use `INotEqualPredicate` instead of `if (x !== y) throw new Error(...)`
     * - Use `IConditionalPredicate` instead of `if (!condition) throw new
     *   Error(...)`
     * - Use `IErrorPredicate` instead of `if` blocks that only contain error
     *   throwing
     *
     * **Only use IIfStatement when:**
     *
     * - Different business logic paths are needed (not just validation)
     * - Complex conditional workflows that can't be expressed as simple predicates
     * - Actor-based or feature-flag dependent test scenarios
     * - Multi-step conditional operations where predicates are insufficient
     *
     * Business scenarios requiring conditional logic:
     *
     * - Actor-based test flows (premium vs regular customers)
     * - Feature availability testing with different user journeys
     * - Optional business process steps based on entity state
     * - Complex workflow branching that involves multiple operations per branch
     *
     * AI function calling strategy: First consider if the validation can be
     * handled by predicate expressions. Use IIfStatement only when genuine
     * business logic branching is required that cannot be expressed through
     * predicates.
     */
    interface IIfStatement {
        /** Type discriminator. */
        type: "ifStatement";
        /**
         * Boolean expression determining which branch to execute.
         *
         * Typically evaluates business conditions like user roles, feature flags,
         * data states, or validation results. Should represent meaningful business
         * logic rather than arbitrary technical conditions.
         *
         * Examples:
         *
         * - Customer.role === "premium"
         * - Product.status === "available"
         * - Order.payment_status === "completed"
         */
        condition: IExpression;
        /**
         * Block to execute when condition is true.
         *
         * Contains the primary business flow for the conditional scenario. Should
         * represent the main path or expected behavior when the business condition
         * is met.
         */
        thenStatement: IBlock;
        /**
         * Optional alternative block for when condition is false.
         *
         * Can be another IIfStatement for chained conditions (else-if) or IBlock
         * for alternative business flow. May be null when no alternative action is
         * needed.
         *
         * Business context: Represents fallback behavior, alternative user
         * journeys, or error handling paths.
         */
        elseStatement?: IBlock | IIfStatement | null;
    }
    /**
     * Return statement for function termination.
     *
     * Rarely used in E2E test functions since they typically return void. May be
     * used in helper functions or when test functions need to return specific
     * data for chaining or validation purposes.
     *
     * **Note**: Most E2E test functions should complete naturally without
     * explicit return statements, as they represent complete business workflow
     * testing rather than value-returning operations.
     *
     * AI function calling usage: Generally avoid in main test functions. Consider
     * only for special cases where test result data needs to be returned to
     * calling context, such as helper functions within arrow function
     * expressions.
     */
    interface IReturnStatement {
        /** Type discriminator. */
        type: "returnStatement";
        /**
         * Expression representing the value to be returned.
         *
         * Should evaluate to the appropriate return type expected by the function
         * signature. In test contexts, typically void or validation result
         * objects.
         *
         * Can reference previously captured data from API operations or computed
         * values, but should not contain direct API calls.
         */
        expression: IExpression;
    }
    /**
     * Explicit error throwing for test failure scenarios.
     *
     * Used for custom error conditions or when specific business rule violations
     * should cause immediate test termination with descriptive error messages.
     *
     * **IMPORTANT: For most validation scenarios, prefer predicate expressions:**
     *
     * - Use `IEqualPredicate` instead of manual equality checks with throw
     * - Use `IConditionalPredicate` instead of condition checks with throw
     * - Use `IErrorPredicate` for testing expected error conditions
     *
     * **Only use IThrowStatement when:**
     *
     * - Custom error handling logic that can't be expressed as predicates
     * - Complex business rule violations requiring custom error messages
     * - Exceptional cases where predicate expressions are insufficient
     *
     * E2E testing scenarios:
     *
     * - Custom validation failures with specific business context
     * - Unexpected state conditions that should halt test execution
     * - Complex error conditions requiring detailed diagnostic information
     *
     * AI function calling usage: Use sparingly, primarily for business logic
     * violations that require explicit error reporting and cannot be handled by
     * the standard predicate validation system.
     */
    interface IThrowStatement {
        /** Type discriminator. */
        type: "throwStatement";
        /**
         * Expression that evaluates to the error to be thrown.
         *
         * Typically an Error object construction with descriptive message
         * explaining the business context of the failure. Should provide clear
         * information about what business condition caused the error.
         *
         * Should NOT involve API calls - use IApiOperateStatement for API
         * operations that are expected to throw errors, and IErrorPredicate for
         * testing expected API error conditions.
         *
         * Example: new Error("Customer verification failed: invalid email format")
         */
        expression: IExpression;
    }
    /**
     * Union type encompassing all possible expressions in test scenarios.
     *
     * Expressions represent values, computations, and operations that can be used
     * within statements. This comprehensive set covers all necessary constructs
     * for building complex E2E test scenarios:
     *
     * **Basic constructs:**
     *
     * - Identifiers: Variable references
     * - Property/Element access: Object navigation
     * - Function calls: Utility invocations (NOT API calls - use
     *   IApiOperateStatement)
     * - Literals: Direct values
     *
     * **Advanced constructs:**
     *
     * - Random generators: Test data creation
     * - Operators: Logical and arithmetic operations
     * - Arrow functions: Callback definitions
     * - Predicates: TestValidator validation operations (preferred over manual
     *   validation)
     *
     * **Note**: API function calls should NOT be represented as expressions. Use
     * `IApiOperateStatement` for all SDK API operations instead.
     *
     * AI selection strategy: Choose expression type based on the specific
     * operation needed in the business scenario. For API calls, always use the
     * dedicated statement type rather than call expressions.
     */
    type IExpression = IBooleanLiteral | INumericLiteral | IStringLiteral | IArrayLiteralExpression | IObjectLiteralExpression | INullLiteral | IUndefinedKeyword | IIdentifier | IPropertyAccessExpression | IElementAccessExpression | ITypeOfExpression | IPrefixUnaryExpression | IPostfixUnaryExpression | IBinaryExpression | IArrowFunction | ICallExpression | INewExpression | IArrayFilterExpression | IArrayForEachExpression | IArrayMapExpression | IArrayRepeatExpression | IPickRandom | ISampleRandom | IBooleanRandom | IIntegerRandom | INumberRandom | IStringRandom | IPatternRandom | IFormatRandom | IKeywordRandom | IEqualPredicate | INotEqualPredicate | IConditionalPredicate | IErrorPredicate;
    /**
     * Boolean literal for true/false values.
     *
     * Represents direct boolean values used in conditions, flags, and business
     * rule specifications. Common in test scenarios for setting feature flags,
     * validation states, and binary business decisions.
     *
     * E2E testing usage:
     *
     * - Feature flags (enabled: true/false)
     * - Business state flags (active, verified, completed)
     * - Validation parameters for API operations
     * - Configuration options for test scenarios
     *
     * **Note**: Often used as arguments in `IApiOperateStatement` for boolean
     * parameters, or in conditional expressions for business logic.
     */
    interface IBooleanLiteral {
        /** Type discriminator. */
        type: "booleanLiteral";
        /**
         * The boolean value (true or false).
         *
         * Should represent meaningful business states rather than arbitrary
         * true/false values. Consider the business context when selecting the value
         * based on the intended test scenario.
         */
        value: boolean;
    }
    /**
     * Numeric literal for number values.
     *
     * Represents direct numeric values including integers, decimals, and
     * floating-point numbers. Essential for business data like quantities,
     * prices, scores, and identifiers used in test scenarios.
     *
     * E2E testing scenarios:
     *
     * - Product quantities and prices for API operation parameters
     * - Score values and ratings in business validations
     * - Pagination parameters (page, limit) for API calls
     * - Business thresholds and limits for conditional logic
     * - Mathematical calculations with captured data
     *
     * **Note**: Commonly used as arguments in `IApiOperateStatement` for numeric
     * parameters, or in comparisons with captured API response data.
     */
    interface INumericLiteral {
        /** Type discriminator. */
        type: "numericLiteral";
        /**
         * The numeric value.
         *
         * Can be integer or floating-point number. Should represent realistic
         * business values appropriate for the test scenario context (e.g.,
         * reasonable prices, quantities, scores).
         *
         * AI consideration: Use business-appropriate values rather than arbitrary
         * numbers (e.g., 10000 for price instead of 12345.67).
         */
        value: number;
    }
    /**
     * String literal for text values.
     *
     * Represents direct string values including business names, descriptions,
     * identifiers, and formatted data. One of the most commonly used literal
     * types in E2E testing for realistic business data.
     *
     * E2E testing importance: Critical for providing realistic business data that
     * reflects actual user input and system behavior, especially as parameters
     * for API operations and in comparisons with captured response data.
     */
    interface IStringLiteral {
        /** Type discriminator. */
        type: "stringLiteral";
        /**
         * The string value.
         *
         * Should contain realistic business data appropriate for the context:
         *
         * - Names: "John Doe", "Acme Corporation"
         * - Emails: "john@example.com"
         * - Descriptions: "High-quality wireless headphones"
         * - Codes: "PROMO2024", "SKU-12345"
         * - Status values: "pending", "approved", "completed"
         *
         * **Usage context**: Commonly used as arguments in `IApiOperateStatement`
         * for string parameters, in predicate validations for expected values, or
         * in conditional expressions for business logic.
         *
         * AI content strategy: Use meaningful, realistic values that reflect actual
         * business scenarios rather than placeholder text like "string" or "test".
         */
        value: string;
    }
    /**
     * Array literal for creating array values directly.
     *
     * Represents direct array construction with explicit elements. Essential for
     * providing list data in test scenarios such as multiple products, user
     * lists, or configuration arrays, particularly as parameters for API
     * operations.
     *
     * E2E testing scenarios:
     *
     * - Product lists for bulk API operations
     * - Tag arrays for categorization in API requests
     * - Multiple item selections for API parameters
     * - Configuration option lists for test setup
     * - Multiple entity references for relationship testing
     *
     * **Note**: Commonly used as arguments in `IApiOperateStatement` when API
     * operations require array parameters, or for constructing test data to be
     * used in business logic.
     *
     * AI function calling usage: Use when business scenarios require explicit
     * list data rather than dynamic array generation from captured API
     * responses.
     */
    interface IArrayLiteralExpression {
        /** Type discriminator. */
        type: "arrayLiteralExpression";
        /**
         * Array of expressions representing the array elements.
         *
         * Each element can be any valid expression (literals, identifiers
         * referencing captured data, function calls, etc.). Elements should
         * represent meaningful business data appropriate for the array's purpose.
         *
         * **⚠️ CRITICAL AI RESTRICTION: Each element MUST be an AST expression, NOT
         * raw JSON values! ⚠️** **❌ WRONG: ["item1", "item2", 123] (raw JSON
         * values)** **✅ CORRECT: [IStringLiteral, IStringLiteral, INumericLiteral]
         * (AST expressions)**
         *
         * Examples:
         *
         * - [product1, product2, product3] for entity arrays (referencing captured
         *   data)
         * - ["electronics", "gadgets"] for category tags
         * - [{ name: "file1.jpg" }, { name: "file2.jpg" }] for file lists
         * - [seller.id, customer.id] for ID arrays (mixing captured data)
         *
         * AI content strategy: Populate with realistic business data that reflects
         * actual usage patterns, mixing literals and references to captured data as
         * appropriate.
         */
        elements: IExpression[];
    }
    /**
     * Object literal for creating object values directly.
     *
     * Represents direct object construction with explicit properties. The primary
     * mechanism for creating request bodies, configuration objects, and
     * structured data in E2E test scenarios, particularly as parameters for API
     * operations.
     *
     * E2E testing importance: Critical for API request bodies in
     * `IApiOperateStatement` calls and configuration objects that drive business
     * operations.
     */
    interface IObjectLiteralExpression {
        /** Type discriminator. */
        type: "objectLiteralExpression";
        /**
         * Array of property assignments defining the object structure.
         *
         * Each property represents a key-value pair in the object. Properties
         * should correspond to actual DTO structure requirements and business data
         * needs when used as API request bodies.
         *
         * **For API operations**: Must align with API schema requirements when used
         * as arguments in `IApiOperateStatement`. Property names and value types
         * should match expected DTO interfaces.
         *
         * **For test data**: Can mix literal values with references to captured
         * data from previous API operations to create realistic business
         * scenarios.
         *
         * AI validation requirement: Ensure properties match the target schema
         * definition exactly when used for API operations, including required
         * fields and types.
         */
        properties: IPropertyAssignment[];
    }
    /**
     * Null literal for explicit null values.
     *
     * Represents explicit null values used in business scenarios where absence of
     * data is meaningful. Important for optional fields, cleared states, and
     * explicit "no value" conditions in API operations and business logic.
     *
     * E2E testing scenarios:
     *
     * - Optional relationship fields in API request bodies
     * - Cleared user preferences in business state
     * - Explicit "no selection" states for optional parameters
     * - Default null values for optional business data in API operations
     *
     * AI decision context: Use when business logic specifically requires null
     * rather than undefined or omitted properties, particularly in API request
     * bodies or when comparing with captured API response data.
     */
    interface INullLiteral {
        /** Type discriminator. */
        type: "nullLiteral";
    }
    /**
     * Undefined keyword for explicit undefined values.
     *
     * Represents explicit undefined values used when business logic requires
     * undefined rather than null or omitted properties. Less commonly used than
     * null in typical business scenarios, but necessary for certain API
     * operations or business logic conditions.
     *
     * E2E testing usage:
     *
     * - Explicit undefined state representation in business logic
     * - Clearing previously set values in test scenarios
     * - API parameters that distinguish between null and undefined
     * - Conditional expressions where undefined has specific meaning
     *
     * AI guidance: Prefer null over undefined unless specific business or API
     * requirements dictate undefined usage, or when working with captured data
     * that may contain undefined values.
     */
    interface IUndefinedKeyword {
        /** Type discriminator. */
        type: "undefinedKeyword";
    }
    /**
     * Identifier expression for referencing variables and utility functions.
     *
     * Represents references to previously captured variables from API operations,
     * imported utility functions, or global identifiers. Essential for data flow
     * in test scenarios where values from earlier API operations are used in
     * later operations.
     *
     * **IMPORTANT**: Should NOT reference API functions directly. API operations
     * should use `IApiOperateStatement` instead.
     *
     * **🚨 CRITICAL: SIMPLE IDENTIFIERS ONLY! 🚨**
     *
     * This interface is ONLY for simple identifiers (single variable names). DO
     * NOT use compound expressions like:
     *
     * **❌ WRONG - These are NOT simple identifiers:**
     *
     * - `Array.isArray` (use IPropertyAccessExpression instead)
     * - `user.name` (use IPropertyAccessExpression instead)
     * - `items[0]` (use IElementAccessExpression instead)
     * - `console.log` (use IPropertyAccessExpression instead)
     * - `Math.random` (use IPropertyAccessExpression instead)
     * - `x.y?.z` (use chained IPropertyAccessExpression instead)
     *
     * **✅ CORRECT - Simple identifiers only:**
     *
     * - `seller` (variable name from IApiOperateStatement)
     * - `product` (variable name from IApiOperateStatement)
     * - `Array` (global constructor name)
     * - `console` (global object name)
     * - `Math` (global object name)
     *
     * **For compound access, use the appropriate expression types:**
     *
     * - Property access: Use `IPropertyAccessExpression` (e.g., `user.name`)
     * - Array/object indexing: Use `IElementAccessExpression` (e.g., `items[0]`)
     * - Method calls: Use `ICallExpression` with `IPropertyAccessExpression` for
     *   the function
     *
     * Common E2E testing usage:
     *
     * - Referencing captured data from previous API operations
     * - Referencing business entities from previous steps
     * - Accessing non-API SDK utilities (simple names only)
     *
     * AI function calling context: Use when referencing any simple named entity
     * in the test scope, excluding direct API function references which should
     * use dedicated statement types. For any property access or method calls, use
     * the appropriate expression types instead.
     */
    interface IIdentifier {
        /** Type discriminator. */
        type: "identifier";
        /**
         * The simple identifier name being referenced.
         *
         * Must be a SIMPLE identifier name (single word) that corresponds to a
         * valid identifier in the current scope:
         *
         * - Previously captured variable names (from IApiOperateStatement
         *   variableName)
         * - Global utility names (simple names only, not property paths)
         * - Parameter names from function scope
         *
         * **Should NOT** reference API functions directly. Use IApiOperateStatement
         * for API operations instead.
         *
         * **MUST NOT contain dots, brackets, or any compound access patterns.** For
         * compound access, use IPropertyAccessExpression or
         * IElementAccessExpression.
         *
         * Examples:
         *
         * **✅ CORRECT - Simple identifiers:**
         *
         * - "seller" (previously captured from API operation)
         * - "product" (previously captured from API operation)
         * - "Array" (global constructor, to be used with IPropertyAccessExpression
         *   for Array.isArray)
         * - "console" (global object, to be used with IPropertyAccessExpression for
         *   console.log)
         *
         * **❌ WRONG - Compound expressions (use other expression types):**
         *
         * - "Array.isArray" (use IPropertyAccessExpression instead)
         * - "user.name" (use IPropertyAccessExpression instead)
         * - "items[0]" (use IElementAccessExpression instead)
         *
         * AI naming consistency: Must match exactly with variable names from
         * previous IApiOperateStatement.variableName. Keep it simple - just the
         * variable name, nothing more.
         */
        text: string & tags.Pattern<"^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$">;
    }
    /**
     * Property access expression for object member navigation.
     *
     * Enables access to properties of objects, which is fundamental for
     * navigating captured data from API operations, utility namespaces, and
     * business entity relationships in E2E test scenarios.
     *
     * **IMPORTANT**: Should NOT be used to construct API function calls. Use
     * `IApiOperateStatement` for all API operations instead.
     *
     * Critical E2E testing patterns:
     *
     * - Accessing properties of captured API response data (customer.id,
     *   order.status)
     * - Extracting business data for subsequent operations
     * - Optional chaining for safe property access
     *
     * AI function calling usage: Essential for building dot-notation chains for
     * data access and utility function calls, but NOT for API operations which
     * have their own dedicated statement type.
     */
    interface IPropertyAccessExpression {
        /** Type discriminator. */
        type: "propertyAccessExpression";
        /**
         * The base expression being accessed.
         *
         * Typically an IIdentifier for the root object, but can be another property
         * access expression for chained access. Represents the object whose
         * property is being accessed.
         */
        expression: IExpression;
        /**
         * Whether to use optional chaining (?.) operator.
         *
         * True: Uses ?. for safe property access (property may not exist) False:
         * Uses . for standard property access (property expected to exist)
         *
         * E2E testing context: Use optional chaining when accessing properties that
         * might not exist based on business conditions or API variations.
         *
         * AI decision rule: Use true for optional business data, false for
         * guaranteed response structures and utility function paths.
         */
        questionDot?: boolean;
        /**
         * The property name being accessed.
         *
         * Must be a valid property name on the base expression's type. Should
         * correspond to actual properties defined in DTO schemas or utility
         * function names.
         *
         * AI validation requirement: Ensure property exists on the base
         * expression's type according to schema definitions, excluding API paths.
         */
        name: string;
    }
    /**
     * Element access expression for dynamic property access and array indexing.
     *
     * Enables access to object properties using computed keys or array elements
     * using indices. Useful for dynamic property access based on runtime values
     * or when property names are not valid identifiers.
     *
     * **Primary use cases in E2E testing:**
     *
     * - Array element access from captured API response data (order.items[0])
     * - Dynamic property access with string keys from API responses
     * - Accessing properties with special characters from captured data
     * - Computed property access based on test data
     *
     * AI function calling context: Use when property access requires computation
     * or when accessing array elements by index in captured data.
     */
    interface IElementAccessExpression {
        /** Type discriminator. */
        type: "elementAccessExpression";
        /**
         * The base expression being indexed/accessed.
         *
         * Can be any expression that evaluates to an object or array. Typically
         * represents collections or objects from captured API responses with
         * dynamic properties.
         *
         * Should reference previously captured data from API operations rather than
         * direct API calls.
         */
        expression: IExpression;
        /**
         * Whether to use optional chaining (?.[]) operator.
         *
         * True: Uses ?.[] for safe element access False: Uses [] for standard
         * element access
         *
         * Use optional chaining when the base expression might be null/undefined or
         * when the accessed element might not exist in the captured data.
         */
        questionDot?: boolean;
        /**
         * Expression that evaluates to the property key or array index.
         *
         * For arrays: typically INumericLiteral for index access For objects:
         * typically IStringLiteral for property key Can be any expression that
         * evaluates to a valid key type
         *
         * Examples:
         *
         * - INumericLiteral(0) for first array element
         * - IStringLiteral("id") for property access
         * - IIdentifier("index") for variable-based access
         */
        argumentExpression: IExpression;
    }
    /**
     * TypeOf expression for runtime type checking.
     *
     * Represents the JavaScript `typeof` operator for determining the type of a
     * value at runtime. Essential for type validation, conditional logic based on
     * data types, and ensuring captured API response data matches expected types
     * in business scenarios.
     *
     * E2E testing scenarios:
     *
     * - Validating captured API response data types before use
     * - Conditional business logic based on data type checking
     * - Type safety verification for dynamic data from API operations
     * - Ensuring proper data type handling in business workflows
     *
     * **Common return values:**
     *
     * - "string" for text data from API responses
     * - "number" for numeric values from API operations
     * - "boolean" for flag values from API calls
     * - "object" for entity data from API responses (including arrays)
     * - "undefined" for missing or uninitialized data
     * - "function" for callback or utility function references
     *
     * AI function calling usage: Use when business logic requires runtime type
     * validation of captured data or when conditional operations depend on data
     * type verification from API responses.
     */
    interface ITypeOfExpression {
        /** Type discriminator. */
        type: "typeOfExpression";
        /**
         * Expression whose type should be determined at runtime.
         *
         * Can be any expression that evaluates to a value requiring type checking.
         * Commonly used with captured data from API operations, variable
         * references, or property access expressions to validate data types before
         * use in business logic.
         *
         * Common patterns:
         *
         * - Identifiers referencing captured API response data
         * - Property access expressions extracting fields from API responses
         * - Array/object element access for nested data type validation
         * - Variable references for dynamic data type checking
         *
         * Should reference captured data or computed values, not direct API calls.
         *
         * AI expression selection: Choose expressions that represent data whose
         * type needs runtime verification, especially when working with dynamic API
         * response data or conditional business logic.
         */
        expression: IExpression;
    }
    /**
     * Prefix unary expression for operators applied before operands.
     *
     * Represents unary operators that appear before their operands:
     *
     * - "!" for logical negation
     * - "++" for pre-increment
     * - "--" for pre-decrement
     *
     * **⚠️ IMPORTANT: For `typeof` operator, use `AutoBeTest.ITypeOfExpression`
     * instead! ⚠️**
     *
     * If you're trying to create a `typeof X` expression, DO NOT use this
     * interface with `operator: "typeof"`. Use the dedicated
     * `AutoBeTest.ITypeOfExpression` interface instead, which is specifically
     * designed for typeof operations.
     *
     * **❌ WRONG:**
     *
     * ```typescript
     * {
     *   type: "prefixUnaryExpression",
     *   operator: "typeof",  // ❌ This is incorrect!
     *   operand: someExpression
     * }
     * ```
     *
     * **✅ CORRECT:**
     *
     * ```typescript
     * {
     *   type: "typeOfExpression",  // ✅ Use this for typeof!
     *   expression: someExpression
     * }
     * ```
     *
     * E2E testing usage:
     *
     * - Logical negation for condition inversion in business logic
     * - Increment/decrement for counter operations (rare in typical test scenarios)
     *
     * AI function calling context: Use for simple unary operations needed in
     * business logic conditions or calculations involving captured test data.
     */
    interface IPrefixUnaryExpression {
        /** Type discriminator. */
        type: "prefixUnaryExpression";
        /**
         * The unary operator to apply.
         *
         * - "!": Logical NOT (most common in test conditions)
         * - "++": Pre-increment (modify then use value)
         * - "--": Pre-decrement (modify then use value)
         */
        operator: "!" | "++" | "--" | "-" | "+";
        /**
         * The operand expression to which the operator is applied.
         *
         * For "!": typically boolean expressions or conditions involving captured
         * data For "++/--": typically variable identifiers that need modification
         *
         * Should reference captured data or computed values, not direct API calls.
         */
        operand: IExpression;
    }
    /**
     * Postfix unary expression for operators applied after operands.
     *
     * Represents unary operators that appear after their operands:
     *
     * - "++" for post-increment
     * - "--" for post-decrement
     *
     * E2E testing usage:
     *
     * - Counter operations where original value is used before modification
     * - Loop iteration variables (though rare in typical E2E test scenarios)
     *
     * AI function calling context: Use when the original value is needed before
     * the increment/decrement operation, typically in scenarios involving
     * iteration or counting with captured test data.
     */
    interface IPostfixUnaryExpression {
        /** Type discriminator. */
        type: "postfixUnaryExpression";
        /**
         * The unary operator to apply.
         *
         * - "++": Post-increment (use value then modify)
         * - "--": Post-decrement (use value then modify)
         */
        operator: "++" | "--";
        /**
         * The operand expression to which the operator is applied.
         *
         * Typically variable identifiers that need modification. Should reference
         * captured data or computed values, not direct API call results.
         */
        operand: IExpression;
    }
    /**
     * Binary expression for operations between two operands.
     *
     * Represents all binary operations including comparison, arithmetic, and
     * logical operations. Essential for implementing business logic conditions,
     * calculations, and validations in test scenarios using captured data.
     *
     * **🚨 CRITICAL: DO NOT confuse with property access or element access! 🚨**
     *
     * This interface is ONLY for binary operators (===, !==, +, -, etc.). Do NOT
     * use this for:
     *
     * **❌ WRONG - These are NOT binary expressions:**
     *
     * - `Array.isArray` (use IPropertyAccessExpression instead)
     * - `user.name` (use IPropertyAccessExpression instead)
     * - `items[0]` (use IElementAccessExpression instead)
     * - `x.y` (use IPropertyAccessExpression instead)
     * - `object.property` (use IPropertyAccessExpression instead)
     * - `console.log` (use IPropertyAccessExpression instead)
     * - `Math.max` (use IPropertyAccessExpression instead)
     * - `array.length` (use IPropertyAccessExpression instead)
     * - `string.includes` (use IPropertyAccessExpression instead)
     *
     * **✅ CORRECT - Binary expressions only:**
     *
     * - `x === y` (equality comparison)
     * - `a + b` (arithmetic operation)
     * - `count > 0` (comparison operation)
     * - `isActive && isValid` (logical operation)
     *
     * **For property/method access, use the appropriate expression types:**
     *
     * - Property access: Use `IPropertyAccessExpression` (e.g., `user.name`,
     *   `Array.isArray`, `array.length`)
     * - Array/object indexing: Use `IElementAccessExpression` (e.g., `items[0]`,
     *   `obj["key"]`)
     * - Method calls: Use `ICallExpression` with `IPropertyAccessExpression` for
     *   the function
     *
     * **Common AI mistakes to avoid:**
     *
     * - Using IBinaryExpression for dot notation (`.`) - this is property access,
     *   not a binary operator
     * - Using IBinaryExpression for `.length`, `.includes()`, etc. - these are
     *   property/method access
     * - Confusing property access with binary operations
     * - Mixing structural navigation with computational operations
     *
     * E2E testing importance: Critical for implementing business rule
     * validations, data comparisons, and conditional logic that reflects
     * real-world application behavior using data captured from API responses.
     */
    interface IBinaryExpression {
        /** Type discriminator. */
        type: "binaryExpression";
        /**
         * Left operand of the binary operation.
         *
         * Typically represents the primary value being compared or operated upon.
         * In business contexts, often represents actual values from captured API
         * responses or business entities from previous operations.
         *
         * **Note**: If you need to access object properties (like `user.name`,
         * `array.length`), use IPropertyAccessExpression as the left operand, not
         * IBinaryExpression.
         */
        left: IExpression;
        /**
         * Binary operator defining the operation type.
         *
         * **⚠️ IMPORTANT: These are computational/logical operators ONLY! ⚠️**
         *
         * **🚨 CRITICAL JavaScript Requirements: 🚨**
         *
         * **❌ NEVER use loose equality operators:**
         *
         * - `==` (loose equality) - This is NOT supported and causes type coercion
         *   bugs
         * - `!=` (loose inequality) - This is NOT supported and causes type coercion
         *   bugs
         *
         * **✅ ALWAYS use strict equality operators:**
         *
         * - `===` (strict equality) - Use this for all equality comparisons
         * - `!==` (strict inequality) - Use this for all inequality comparisons
         *
         * **Why strict equality is required:**
         *
         * - Prevents unexpected type coercion (e.g., `"0" == 0` is true, but `"0" ===
         *   0` is false)
         * - Ensures predictable behavior in business logic
         * - Follows TypeScript and modern JavaScript best practices
         * - Avoids subtle bugs in API response validation
         *
         * Do NOT include:
         *
         * - `.` (dot) - This is property access, use IPropertyAccessExpression
         * - `[]` (brackets) - This is element access, use IElementAccessExpression
         * - `()` (parentheses) - This is function call, use ICallExpression
         * - `.length`, `.includes`, etc. - These are property/method access, use
         *   IPropertyAccessExpression
         * - '.length ===': Capsule left expression into IPropertyAccessExpression
         * - '[0] >=' Capsule left expression into IElementAccessExpression
         *
         * **Comparison operators:**
         *
         * - "===", "!==": Strict equality/inequality (REQUIRED - never use == or !=)
         * - "<", "<=", ">", ">=": Numerical/string comparisons
         *
         * **Arithmetic operators:**
         *
         * - "+", "-", "*", "/", "%": Mathematical operations
         *
         * **Logical operators:**
         *
         * - "&&": Logical AND (both conditions must be true)
         * - "||": Logical OR (either condition can be true)
         *
         * AI selection guide:
         *
         * - Use === for equality checks (NEVER ==)
         * - Use !== for inequality checks (NEVER !=)
         * - Use logical operators for combining business conditions
         * - Use arithmetic for calculations on captured data
         * - For property access, method calls, or array indexing, use the appropriate
         *   expression types instead
         */
        operator: "===" | "!==" | "<" | "<=" | ">" | ">=" | "+" | "-" | "*" | "/" | "%" | "&&" | "||" | "instanceof";
        /**
         * Right operand of the binary operation.
         *
         * Represents the comparison value, second operand in calculations, or
         * second condition in logical operations. In business contexts, often
         * represents expected values, business rule thresholds, or additional
         * captured data from API responses.
         *
         * **Note**: If you need to access object properties (like `order.status`,
         * `items.length`), use IPropertyAccessExpression as the right operand, not
         * IBinaryExpression.
         */
        right: IExpression;
    }
    /**
     * Conditional expression for inline value selection.
     *
     * Represents the ternary operator (condition ? trueValue : falseValue) for
     * inline conditional value selection. Useful when values need to be chosen
     * based on business conditions within expressions.
     *
     * E2E testing scenarios:
     *
     * - Conditional parameter values based on captured test data
     * - Dynamic value selection based on business rules from API responses
     * - Fallback value specification for optional data
     * - Simple conditional logic within expression contexts
     *
     * AI function calling context: Use when business logic requires different
     * values based on runtime conditions within expressions, where the conditions
     * and values don't involve direct API calls.
     */
    interface IConditionalExpression {
        /** Type discriminator. */
        type: "conditionalExpression";
        /**
         * Boolean condition determining which value to select.
         *
         * Should represent meaningful business logic conditions based on captured
         * data rather than arbitrary technical conditions. Can reference data
         * captured from previous API operations.
         */
        condition: IExpression;
        /**
         * Expression evaluated and returned when condition is true.
         *
         * Represents the primary or expected value for the business scenario. Can
         * reference captured API data or computed values.
         */
        whenTrue: IExpression;
        /**
         * Expression evaluated and returned when condition is false.
         *
         * Represents the alternative or fallback value for the business scenario.
         * Can reference captured API data or computed values.
         */
        whenFalse: IExpression;
    }
    /**
     * Arrow function expression for callback definitions.
     *
     * Used primarily for callback functions required by certain utility functions
     * or specialized operations. In E2E testing, commonly needed for array
     * operations, error handling callbacks, or random data generation functions.
     *
     * E2E testing scenarios:
     *
     * - Callback functions for IErrorPredicate (testing expected API errors)
     * - Generator functions for IArrayRepeatExpression (creating test data arrays)
     * - Filter/transform functions for captured data manipulation
     * - Event handler functions for specialized testing scenarios
     *
     * AI function calling usage: Generate when utility operations require
     * function parameters or when data transformation callbacks are needed within
     * the test flow.
     */
    interface IArrowFunction {
        /** Type discriminator. */
        type: "arrowFunction";
        /**
         * The function body containing the function's logic.
         *
         * Contains the statements that comprise the function's implementation. In
         * test contexts, typically contains simple operations like data
         * transformation, validation, or utility calls.
         *
         * Can include IApiOperateStatement for API operations within the callback,
         * though this should be used judiciously and only when the callback
         * specifically requires API interactions.
         *
         * Should represent meaningful business logic rather than arbitrary
         * computational operations.
         */
        body: IBlock;
    }
    /**
     * Function call expression for non-API function invocations and utility
     * calls.
     *
     * **IMPORTANT: For API function calls, use `IApiOperateStatement` instead.**
     * This type should only be used for:
     *
     * - Helper functions and transformations
     * - Built-in JavaScript functions
     * - Non-API library function calls
     *
     * Essential for E2E testing for utility operations, but API calls should use
     * the dedicated `IApiOperateStatement` for proper handling of business
     * operations and response capturing.
     *
     * AI function calling importance: This represents utility and validation
     * operations in test scenarios, but should NOT be used for SDK API calls
     * which have their own dedicated statement type.
     */
    interface ICallExpression {
        /** Type discriminator. */
        type: "callExpression";
        /**
         * Expression representing the function to be called.
         *
         * **Should NOT represent API/SDK functions** - use `IApiOperateStatement`
         * for those instead.
         *
         * Typically represents utility functions:
         *
         * - Built-in functions (Array.from, Object.keys, etc.)
         * - Helper/transformation functions
         *
         * Can also be a simple identifier for direct function references.
         *
         * AI requirement: Must NOT resolve to SDK API functions. Those should use
         * the dedicated API function call statement type.
         */
        expression: IExpression;
        /**
         * Array of argument expressions passed to the function.
         *
         * Each argument must match the expected parameter type of the called
         * function. Order and types must correspond exactly to the function
         * signature defined in utility or validation documentation.
         *
         * Common patterns:
         *
         * - Transformation parameters for utility functions
         *
         * AI validation: Ensure argument types and count match the target
         * function's signature exactly, excluding API functions.
         */
        arguments: IExpression[];
    }
    /**
     * New expression for object instantiation.
     *
     * Creates new instances of objects, primarily used for:
     *
     * - Error object creation for throw statements
     * - Date object creation for timestamp values
     * - Custom object instantiation when required by utility functions
     *
     * E2E testing context: Most commonly used for creating Error objects in throw
     * statements or Date objects for time-sensitive test data. Also used for
     * instantiating utility objects that don't involve API calls.
     *
     * AI function calling usage: Use when business logic requires explicit object
     * instantiation rather than literal values, excluding API-related entity
     * creation.
     */
    interface INewExpression {
        /** Type discriminator. */
        type: "newExpression";
        /**
         * Expression representing the constructor function.
         *
         * Typically an identifier for built-in constructors:
         *
         * - "Error" for error objects
         * - "Date" for date objects
         * - Custom class identifiers when needed for utility purposes
         *
         * Should NOT represent API-related constructors or entity builders.
         */
        expression: IExpression;
        /**
         * Arguments passed to the constructor.
         *
         * Must match the constructor's parameter signature. For Error objects:
         * typically string message For Date objects: typically string or number
         * timestamp For other constructors: appropriate parameter types
         *
         * Arguments should be derived from captured data, literals, or
         * computations, not from direct API calls.
         */
        arguments: IExpression[];
    }
    /**
     * Array filter expression for selecting elements that meet criteria.
     *
     * Filters array elements based on a predicate function, keeping only elements
     * that satisfy the specified condition. Essential for extracting subsets of
     * business data from captured API responses or test collections based on
     * business rules and conditions.
     *
     * E2E testing scenarios:
     *
     * - Filtering products by category or price range from API response arrays
     * - Selecting active users from captured user lists for business operations
     * - Finding orders with specific status from API response collections
     * - Extracting eligible items for business rule validation
     *
     * **Primary usage**: Processing captured data from API operations to create
     * focused datasets for subsequent operations or validations.
     *
     * AI function calling strategy: Use when business logic requires working with
     * specific subsets of data captured from API responses, especially for
     * conditional operations or validation scenarios.
     */
    interface IArrayFilterExpression {
        /** Type discriminator. */
        type: "arrayFilterExpression";
        /**
         * Array expression to be filtered.
         *
         * Must be an expression that evaluates to an array containing business
         * entities or data that requires filtering based on specific criteria. Can
         * reference variables from previous API calls, array literals, or other
         * expressions that produce arrays.
         *
         * The array elements will be individually evaluated by the filter function
         * to determine inclusion in the filtered result. Each element should be
         * compatible with the filtering logic defined in the function parameter.
         *
         * Examples:
         *
         * - Reference to captured product array from API response
         * - Array of user entities from previous API operations
         * - Collection of business data requiring conditional processing
         * - Variable references to previously constructed arrays
         *
         * Business context: Typically represents collections of entities that need
         * subset selection based on business rules, such as active users, available
         * products, or eligible transactions.
         */
        array: IExpression;
        /**
         * Arrow function defining the filter criteria.
         *
         * Called for each array element to determine if it should be included in
         * the filtered result. Should return a boolean expression that evaluates
         * business conditions relevant to the filtering purpose.
         *
         * The function parameter represents the current array element being
         * evaluated and can be used to access properties for business logic
         * conditions.
         */
        function: IArrowFunction;
    }
    /**
     * Array forEach expression for iterating over elements with side effects.
     *
     * Executes a function for each array element without returning a new array.
     * Used for performing operations on each element such as validation, logging,
     * or side-effect operations that don't require collecting results.
     *
     * E2E testing scenarios:
     *
     * - Validating each product in a collection meets business requirements
     * - Logging details of each order for debugging test scenarios
     * - Performing individual validations on user entities from API responses
     * - Executing side-effect operations on captured business data
     *
     * **Note**: Use when you need to process each element but don't need to
     * transform or collect results. For transformations, use
     * IArrayMapExpression.
     *
     * AI function calling strategy: Use for validation operations or side effects
     * on each element of captured data collections, especially when the operation
     * doesn't produce a new collection.
     */
    interface IArrayForEachExpression {
        /** Type discriminator. */
        type: "arrayForEachExpression";
        /**
         * Array expression to iterate over.
         *
         * Must be an expression that evaluates to an array containing business
         * entities or data that requires individual element processing. Often
         * references collections captured from API operations or constructed arrays
         * for testing.
         *
         * Each element in the array will be passed to the function for processing.
         * The array can contain any type of business data appropriate for the
         * intended operation.
         *
         * Examples:
         *
         * - Array of customers from API response requiring individual validation
         * - Collection of orders needing status verification
         * - List of products requiring individual business rule checks
         * - User entities from previous API calls needing processing
         *
         * Business context: Represents collections where each element needs
         * individual attention, such as validation, logging, or side-effect
         * operations that don't transform the data but perform actions based on
         * each element's properties.
         */
        array: IExpression;
        /**
         * Arrow function executed for each array element.
         *
         * Called once for each element in the array. Should contain operations that
         * process the individual element, such as validation calls, logging
         * operations, or other side effects relevant to the business scenario.
         *
         * The function parameter represents the current array element and can be
         * used to access properties and perform element-specific operations.
         */
        function: IArrowFunction;
    }
    /**
     * Array map expression for transforming elements into new values.
     *
     * Transforms each array element using a function, producing a new array with
     * the transformed values. Essential for data transformation, extraction of
     * specific properties, and converting between data formats in business
     * scenarios.
     *
     * E2E testing scenarios:
     *
     * - Extracting IDs from captured entity arrays for subsequent API operations
     * - Transforming product data for different API request formats
     * - Converting user objects to summary data for business validations
     * - Creating parameter arrays from captured business entities
     *
     * **Primary usage**: Data transformation when you need to convert captured
     * API response data into formats suitable for subsequent operations or when
     * extracting specific information from business entities.
     *
     * AI function calling strategy: Use when business logic requires transforming
     * collections of captured data into different formats, especially for
     * preparing data for subsequent API operations.
     */
    interface IArrayMapExpression {
        /** Type discriminator. */
        type: "arrayMapExpression";
        /**
         * Array expression to be transformed.
         *
         * Must be an expression that evaluates to an array containing business
         * entities or data that needs transformation. Often references collections
         * captured from API operations that require conversion to different
         * formats.
         *
         * Each element in the array will be passed to the transformation function
         * to produce a corresponding element in the resulting array. The original
         * array remains unchanged.
         *
         * Examples:
         *
         * - Array of product entities requiring ID extraction
         * - Collection of users needing transformation to summary format
         * - Business data requiring format conversion for API parameters
         * - Entity arrays from API responses needing property extraction
         *
         * Business context: Represents source data that needs to be converted to a
         * different format or structure, such as extracting specific fields,
         * calculating derived values, or preparing data for subsequent API
         * operations.
         */
        array: IExpression;
        /**
         * Arrow function defining the transformation logic.
         *
         * Called for each array element to produce the transformed value. Should
         * return an expression that represents the desired transformation of the
         * input element, creating business-appropriate output data.
         *
         * The function parameter represents the current array element being
         * transformed and can be used to access properties and create the
         * transformed result.
         */
        function: IArrowFunction;
    }
    /**
     * Array repeat generator for dynamic test data creation.
     *
     * Generates arrays with specified length by repeating a generator function.
     * Essential for creating realistic test data that simulates collections like
     * product lists, user arrays, or transaction histories for use in API
     * operations.
     *
     * **Primary usage**: Creating dynamic test data for API operation parameters
     * that require arrays, or for generating test scenarios with specific data
     * sizes.
     *
     * E2E testing importance: Enables testing with realistic data volumes and
     * variations that reflect real-world usage patterns, particularly when
     * combined with `IApiOperateStatement` for bulk operations.
     *
     * AI function calling strategy: Use when business scenarios require
     * collections of specific size rather than fixed arrays, especially for API
     * operations that handle multiple entities.
     */
    interface IArrayRepeatExpression {
        /** Type discriminator. */
        type: "arrayRepeatExpression";
        /**
         * Expression determining how many elements to generate.
         *
         * Must be an expression that evaluates to a number representing the desired
         * array length. Can be a literal number for fixed length or a random
         * generator for variable length. Should reflect realistic business
         * constraints and use cases.
         *
         * **⚠️ CRITICAL AI RESTRICTION: This MUST be an AST expression, NOT a raw
         * number! ⚠️**
         *
         * **❌ WRONG: 5 (raw number)** **✅ CORRECT: INumericLiteral with value: 5
         * (AST expression)** **✅ CORRECT: IIntegerRandom for variable length (AST
         * expression)**
         *
         * Examples:
         *
         * - `INumericLiteral(5)` for exactly 5 elements
         * - `IIntegerRandom({ minimum: 3, maximum: 7 })` for variable length
         * - `IIdentifier("itemCount")` for dynamic count from captured data
         *
         * Business considerations:
         *
         * - 1-10 for shopping cart items (realistic user behavior)
         * - 5-20 for product reviews (typical engagement levels)
         * - 10-100 for product catalogs (reasonable inventory sizes)
         * - 3-8 for team member lists (typical business team sizes)
         *
         * The count should be appropriate for the business context and reflect
         * realistic data volumes that would be encountered in actual API
         * operations.
         *
         * AI constraint setting: Choose counts that make business sense for the
         * specific use case, considering both realistic data volumes and system
         * performance implications when used in API operations.
         */
        count: IExpression;
        /**
         * Arrow function for generating individual array elements.
         *
         * Called once for each array element to generate the element value. Should
         * produce business-appropriate data for the array's purpose.
         *
         * The function typically uses random generators to create varied but
         * realistic business entities. Can also reference captured data from
         * previous API operations to create related test data.
         *
         * AI implementation requirement: Generate meaningful business data rather
         * than arbitrary random values. Consider how the generated data will be
         * used in subsequent API operations.
         */
        function: IArrowFunction;
    }
    /**
     * Randomly selects an element from an array expression.
     *
     * Picks one element randomly from the provided array expression. Used for
     * selecting categories, status values, etc. for API parameters and test
     * data.
     */
    interface IPickRandom {
        /** Type discriminator */
        type: "pickRandom";
        /**
         * Array expression to pick from.
         *
         * Must be an expression that evaluates to an array containing the candidate
         * elements for random selection. Can be any expression type that produces
         * an array:
         *
         * - Array literals with explicit elements
         * - Variable references to previously captured arrays
         * - Function calls that return arrays
         * - Property access to array properties
         *
         * The array should contain at least one element for meaningful random
         * selection. All elements should be of compatible types appropriate for the
         * business context.
         *
         * Example:
         *
         * ```typescript
         * {
         *   "type": "pickRandom",
         *   "array": {
         *     "type": "arrayLiteralExpression",
         *     "elements": [
         *       { "type": "stringLiteral", "value": "electronics" },
         *       { "type": "stringLiteral", "value": "clothing" },
         *       { "type": "stringLiteral", "value": "books" }
         *     ]
         *   }
         * }
         * ```
         *
         * Business usage: Commonly used for selecting random categories, status
         * values, or options in API operation parameters to create varied test
         * scenarios.
         */
        array: IExpression;
    }
    /**
     * Random sampler for selecting multiple items from a collection.
     *
     * Randomly selects a specified number of elements from a provided collection
     * without duplication. Useful for creating realistic subsets of business data
     * like featured products, selected users, or sample transactions for API
     * operations.
     *
     * E2E testing scenarios:
     *
     * - Selecting featured products from catalog for API parameters
     * - Choosing random users for notification API calls
     * - Sampling transactions for analysis operations
     * - Creating test data subsets for bulk API operations
     *
     * **Usage with APIs**: Often combined with `IApiOperateStatement` to perform
     * operations on multiple randomly selected entities.
     *
     * AI function calling context: Use when business scenarios require multiple
     * selections from a larger set without duplication, particularly for API
     * operations that handle multiple entities.
     */
    interface ISampleRandom {
        /** Type discriminator. */
        type: "sampleRandom";
        /**
         * Array expression containing the collection to sample from.
         *
         * Must be an expression that evaluates to an array containing more elements
         * than the requested sample count to enable meaningful random selection.
         * Elements should be valid business entities appropriate for the sampling
         * context.
         *
         * Can reference captured data from previous API operations, array literals,
         * or other expressions that produce collections suitable for sampling.
         *
         * Examples:
         *
         * - Array of product IDs from captured API response
         * - Collection of user entities from previous API call
         * - Available options from business configuration
         * - Variable references to previously constructed arrays
         *
         * The collection size should exceed the `count` parameter to ensure
         * meaningful random sampling without duplication.
         *
         * Business context: Typically represents pools of available entities like
         * product catalogs, user lists, or option sets that need subset selection
         * for API operations.
         */
        array: IExpression;
        /**
         * Expression determining how many elements to select from the collection.
         *
         * Must be an expression that evaluates to a number representing the desired
         * sample size. Should be less than or equal to the collection size to avoid
         * sampling errors. Should represent realistic business requirements for the
         * sampling scenario.
         *
         * **⚠️ CRITICAL AI RESTRICTION: This MUST be an AST expression, NOT a raw
         * number! ⚠️**
         *
         * **❌ WRONG: 3 (raw number)** **✅ CORRECT: INumericLiteral with value: 3
         * (AST expression)** **✅ CORRECT: IIntegerRandom for variable count (AST
         * expression)**
         *
         * Examples:
         *
         * - `INumericLiteral(3)` for exactly 3 featured products
         * - `IIntegerRandom({ minimum: 2, maximum: 5 })` for variable selection
         * - `IIdentifier("sampleSize")` for dynamic count from captured data
         *
         * Business considerations:
         *
         * - 3-5 for featured products (typical homepage display)
         * - 5-10 for sample users (reasonable notification batch)
         * - 10-20 for transaction samples (meaningful analysis size)
         * - 2-8 for recommended items (typical recommendation count)
         *
         * The count should be appropriate for the business context and not exceed
         * the available collection size. Consider both user experience and system
         * performance when selecting sample sizes for API operations.
         *
         * AI selection strategy: Choose counts that reflect realistic business
         * requirements and typical usage patterns, especially when the sampled data
         * will be used in subsequent API operations.
         */
        count: IExpression;
    }
    /**
     * Random boolean generator for true/false values with probability control.
     *
     * Generates boolean values with optional probability weighting. Useful for
     * simulating business scenarios with probabilistic outcomes like feature
     * flags, user preferences, or conditional states in API operations.
     *
     * E2E testing scenarios:
     *
     * - Random feature flag states for API parameter variation
     * - User preference simulation in test data
     * - Conditional business logic testing with probabilistic outcomes
     * - Random yes/no decisions for API operation parameters
     *
     * **API usage**: Commonly used as boolean parameters in
     * `IApiOperateStatement` to create varied test scenarios with realistic
     * probability distributions.
     *
     * AI function calling usage: Use when business logic involves probabilistic
     * boolean outcomes rather than deterministic values, especially for creating
     * diverse API operation parameters.
     */
    interface IBooleanRandom {
        /** Type discriminator. */
        type: "booleanRandom";
        /**
         * Probability of generating true (0.0 to 1.0).
         *
         * - Null: 50/50 probability (default random boolean)
         * - 0.0: Always false
         * - 1.0: Always true
         * - 0.7: 70% chance of true, 30% chance of false
         *
         * Should reflect realistic business probabilities:
         *
         * - High probability (0.8-0.9) for common positive states
         * - Low probability (0.1-0.2) for rare conditions
         * - Default (null) for balanced scenarios
         *
         * AI probability selection: Choose based on real-world business likelihood
         * of the condition being true, especially when used in API operations.
         */
        probability?: number | null;
    }
    /**
     * Random integer generator with business-appropriate constraints.
     *
     * Generates random integer values within specified ranges and constraints.
     * Essential for creating realistic business numeric data like quantities,
     * counts, scores, and identifiers for use in API operations and business
     * logic.
     *
     * E2E testing importance: Provides realistic numeric data that reflects
     * actual business value ranges and constraints, particularly for API
     * operation parameters and validation scenarios.
     */
    interface IIntegerRandom {
        /** Type discriminator. */
        type: "integerRandom";
        /**
         * Minimum value (inclusive).
         *
         * - Null: No minimum constraint
         * - Number: Specific minimum value
         *
         * Should reflect business constraints:
         *
         * - 0 for non-negative quantities
         * - 1 for positive-only values
         * - Business-specific minimums for scores, ratings, etc.
         *
         * AI constraint setting: Choose minimums that make business sense for the
         * specific data type being generated, especially when used in API
         * operations.
         */
        minimum?: (number & tags.Type<"int32">) | null;
        /**
         * Maximum value (inclusive).
         *
         * - Null: No maximum constraint
         * - Number: Specific maximum value
         *
         * Should reflect realistic business limits:
         *
         * - 100 for percentage values
         * - 5 for rating scales
         * - Reasonable inventory quantities for business operations
         * - Business-specific maximums that align with API constraints
         *
         * AI constraint setting: Choose maximums that reflect real-world business
         * limits and system constraints, particularly for API operation
         * parameters.
         */
        maximum?: (number & tags.Type<"int32">) | null;
        /**
         * Multiple constraint for generated values.
         *
         * - Null: No multiple constraint
         * - Number: Generated value must be multiple of this number
         *
         * Business use cases:
         *
         * - 5 for rating systems (0, 5, 10, 15, ...)
         * - 10 for price increments in business systems
         * - Custom business increment requirements for API parameters
         *
         * AI usage: Apply when business rules require specific value increments,
         * especially for API operations with constrained parameter values.
         */
        multipleOf?: (number & tags.Type<"int32">) | null;
    }
    /**
     * Random number generator for decimal/floating-point values.
     *
     * Generates random decimal values within specified ranges and constraints.
     * Essential for business data like prices, percentages, measurements, and
     * calculated values used in API operations and business validations.
     *
     * E2E testing scenarios:
     *
     * - Product prices and costs for API operation parameters
     * - Percentage values and rates for business calculations
     * - Measurement data for physical product specifications
     * - Financial calculations and monetary values
     * - Performance metrics and business KPIs
     */
    interface INumberRandom {
        /** Type discriminator. */
        type: "numberRandom";
        /**
         * Minimum value (inclusive).
         *
         * - Null: No minimum constraint
         * - Number: Specific minimum value (can be decimal)
         *
         * Business considerations:
         *
         * - 0.0 for non-negative amounts
         * - 0.01 for minimum price values in business systems
         * - Business-specific decimal minimums for API constraints
         *
         * AI constraint setting: Consider business rules for minimum values,
         * especially for monetary and measurement data used in API operations.
         */
        minimum?: number | null;
        /**
         * Maximum value (inclusive).
         *
         * - Null: No maximum constraint
         * - Number: Specific maximum value (can be decimal)
         *
         * Business considerations:
         *
         * - 100.0 for percentage values
         * - Realistic price ranges for products in API operations
         * - System limits for calculations and business rules
         *
         * AI constraint setting: Set realistic upper bounds based on business
         * context and system capabilities, especially for API parameter
         * validation.
         */
        maximum?: number | null;
        /**
         * Multiple constraint for decimal precision.
         *
         * - Null: No multiple constraint
         * - Number: Generated value must be multiple of this number
         *
         * Business use cases:
         *
         * - 0.01 for currency precision (cents) in financial API operations
         * - 0.5 for half-point rating systems
         * - Custom precision requirements for business calculations
         *
         * AI precision consideration: Match business precision requirements for the
         * specific data type (currency, measurements, etc.) and API constraints.
         */
        multipleOf?: number | null;
    }
    /**
     * Random string generator with length constraints.
     *
     * Generates random strings within specified length ranges. Useful for
     * creating variable-length text data like names, descriptions, codes, and
     * identifiers for use in API operations and business logic testing.
     *
     * E2E testing scenarios:
     *
     * - User names and nicknames for API operation parameters
     * - Product descriptions and content for API requests
     * - Generated codes and tokens for business operations
     * - Text content of varying lengths for validation testing
     * - Custom identifiers for business entity creation
     *
     * **API usage**: Commonly used to generate string parameters for
     * `IApiOperateStatement` calls with appropriate length constraints.
     */
    interface IStringRandom {
        /** Type discriminator. */
        type: "stringRandom";
        /**
         * Minimum string length.
         *
         * - Null: No minimum length constraint
         * - Number: Minimum number of characters
         *
         * Business considerations:
         *
         * - 3 for minimum usernames in business systems
         * - 8 for minimum passwords for security requirements
         * - 1 for required non-empty fields in API operations
         * - Business-specific minimum requirements for validation
         *
         * AI length setting: Consider business validation rules and user experience
         * requirements for minimum lengths, especially for API parameter
         * constraints.
         */
        minLength?: (number & tags.Type<"uint32">) | null;
        /**
         * Maximum string length.
         *
         * - Null: No maximum length constraint
         * - Number: Maximum number of characters
         *
         * Business considerations:
         *
         * - 255 for typical database field limits
         * - 50 for names and titles in business systems
         * - 1000 for descriptions and content fields
         * - System-specific character limits for API operations
         *
         * AI length setting: Respect database constraints and UI limitations while
         * allowing realistic content length variation for API operations.
         */
        maxLength?: (number & tags.Type<"uint32">) | null;
    }
    /**
     * Pattern-based random string generator.
     *
     * Generates strings matching specific patterns using regular expressions or
     * format strings. Essential for creating data that matches exact business
     * format requirements like codes, identifiers, and structured text for API
     * operations.
     *
     * E2E testing scenarios:
     *
     * - Product SKU generation for API parameters
     * - User ID formats for business system integration
     * - Business code patterns for API operations
     * - Structured identifier creation for entity relationships
     * - Format-specific text generation for validation testing
     *
     * **API integration**: Particularly useful for generating parameters that
     * must match specific format requirements in `IApiOperateStatement` calls.
     *
     * AI pattern usage: Ensure patterns match actual business format requirements
     * and API validation rules.
     */
    interface IPatternRandom {
        /** Type discriminator. */
        type: "patternRandom";
        /**
         * Regular expression pattern for string generation.
         *
         * Defines the exact format structure for generated strings. Should match
         * business format requirements and validation patterns used in API
         * operations.
         *
         * Examples:
         *
         * - "SKU-[0-9]{6}" for product SKUs in business systems
         * - "[A-Z]{3}-[0-9]{4}" for order codes in API operations
         * - "[a-zA-Z]{5,10}" for username patterns with length constraints
         * - "[A-Z]{2}[0-9]{8}" for business reference numbers
         *
         * AI pattern creation: Ensure patterns generate valid data that passes
         * business validation rules and format requirements used in API calls.
         */
        pattern: string;
    }
    /**
     * Format-based random data generator.
     *
     * Generates data matching specific standardized formats like emails, UUIDs,
     * dates, and URLs. Critical for creating valid business data that conforms to
     * standard formats and validation requirements in API operations.
     *
     * E2E testing importance: Ensures generated data passes format validation and
     * represents realistic business data types, particularly essential for API
     * operation parameters that require specific formats.
     */
    interface IFormatRandom {
        /** Type discriminator. */
        type: "formatRandom";
        /**
         * Standardized format specification for data generation.
         *
         * Supports common business data formats essential for API operations:
         *
         * **Security & Encoding:**
         *
         * - "binary": Binary data representation
         * - "byte": Base64 encoded data
         * - "password": Password strings for authentication
         * - "regex": Regular expression patterns
         *
         * **Identifiers:**
         *
         * - "uuid": Universally unique identifiers for entity references
         *
         * **Network & Communication:**
         *
         * - "email": Email addresses for user-related API operations
         * - "hostname": Network hostnames for system integration
         * - "idn-email": Internationalized email addresses
         * - "idn-hostname": Internationalized hostnames
         * - "ipv4": IPv4 addresses for network configuration
         * - "ipv6": IPv6 addresses for network configuration
         *
         * **Web & URI:**
         *
         * - "uri": Uniform Resource Identifiers for API endpoints
         * - "iri": Internationalized Resource Identifiers
         * - "iri-reference": IRI references
         * - "uri-reference": URI references
         * - "uri-template": URI templates
         * - "url": Web URLs for external resource references
         *
         * **Date & Time:**
         *
         * - "date-time": ISO 8601 date-time strings for API timestamps
         * - "date": Date-only strings for business date fields
         * - "time": Time-only strings for scheduling operations
         * - "duration": Time duration strings for business processes
         *
         * **JSON & Pointers:**
         *
         * - "json-pointer": JSON Pointer strings for data navigation
         * - "relative-json-pointer": Relative JSON Pointers
         *
         * AI format selection: Choose formats that match the business context and
         * validation requirements of the target API operation field.
         */
        format: "binary" | "byte" | "password" | "regex" | "uuid" | "email" | "hostname" | "idn-email" | "idn-hostname" | "iri" | "iri-reference" | "ipv4" | "ipv6" | "uri" | "uri-reference" | "uri-template" | "url" | "date-time" | "date" | "time" | "duration" | "json-pointer" | "relative-json-pointer";
    }
    /**
     * Domain-specific random data generator.
     *
     * Generates realistic business data for specific domains using predefined
     * generation rules. Provides contextually appropriate data that reflects
     * real-world business scenarios and user behavior for API operations.
     *
     * E2E testing importance: Creates realistic test data that closely mimics
     * actual user input and business content, improving test scenario
     * authenticity and catching real-world edge cases in API operations.
     */
    interface IKeywordRandom {
        /** Type discriminator. */
        type: "keywordRandom";
        /**
         * Domain-specific data generation keyword.
         *
         * **🚨 CRITICAL: ONLY use the exact predefined constant values! 🚨**
         *
         * **❌ UNSUPPORTED values that will cause errors:**
         *
         * - "title", "comment", "article", "description", "text", "body"
         * - "summary", "details", "note", "message", "subject", "sentence"
         * - "address", "phone", "email", "url", "username"
         * - Any value not explicitly listed in the supported constants below
         *
         * **✅ SUPPORTED constant values ONLY:**
         *
         * **Text & Content:**
         *
         * - "alphabets": Random alphabetic strings for codes and identifiers
         * - "alphaNumeric": Random alphanumeric strings for mixed-format identifiers
         * - "paragraph": Realistic paragraph text for content fields
         * - "content": Generic content text for description fields
         *
         * **Personal Information:**
         *
         * - "mobile": Mobile phone numbers for contact information in APIs
         * - "name": Personal names (first, last, full) for user-related operations
         *
         * **🎯 AI SELECTION STRATEGY: Map your needs to existing constants!**
         *
         * Before trying unsupported values, find the closest match from available
         * options:
         *
         * - **Need titles/headers?** → Use "content" (generic text content)
         * - **Need comments/descriptions?** → Use "paragraph" (realistic paragraph
         *   text)
         * - **Need articles/body text?** → Use "paragraph" (longer text content)
         * - **Need details/summaries?** → Use "content" (general text fields)
         * - **Need phone numbers?** → Use "mobile" (phone number format)
         * - **Need usernames/IDs?** → Use "alphaNumeric" (mixed identifier format)
         * - **Need codes/tokens?** → Use "alphabets" (alphabetic strings)
         *
         * **Usage strategy for API operations:**
         *
         * - Use "name" for user registration and profile API calls
         * - Use "mobile" for contact information in business APIs
         * - Use "paragraph" for descriptions, comments, articles, and content in API
         *   requests
         * - Use "content" for general text fields, titles, subjects in API parameters
         * - Use "alphabets"/"alphaNumeric" for codes, usernames, and identifiers in
         *   API calls
         *
         * **⚠️ REMINDER: The system only supports these 6 exact constants. No
         * exceptions!** If you need functionality not covered by these constants,
         * use other generators like:
         *
         * - IStringRandom for custom length text
         * - IFormatRandom for specific formats (email, url, etc.)
         * - IPatternRandom for custom patterns
         */
        keyword: "alphabets" | "alphaNumeric" | "paragraph" | "content" | "mobile" | "name";
    }
    /**
     * Equality validation predicate for TestValidator assertion.
     *
     * Generates TestValidator.equals() calls to verify that two values are equal.
     * This is the most commonly used validation pattern in E2E tests for
     * confirming API responses match expected values and ensuring data integrity
     * throughout business workflows.
     *
     * **Preferred over manual validation**: Use this instead of `IIfStatement`
     * with throw statements for equality checking.
     *
     * E2E testing scenarios:
     *
     * - Verifying API response data matches expected values
     * - Confirming entity IDs are correctly preserved across API operations
     * - Validating state transitions in business workflows
     * - Ensuring data consistency after CRUD operations via API calls
     *
     * AI function calling usage: Use after API operations (IApiOperateStatement)
     * to validate response data and confirm business logic execution. Essential
     * for maintaining test reliability and catching regressions.
     */
    interface IEqualPredicate {
        /** Type discriminator. */
        type: "equalPredicate";
        /**
         * Descriptive title explaining what is being validated.
         *
         * 🚨 CRITICAL: This MUST be a simple string value, NOT an expression! 🚨
         *
         * ❌ WRONG - DO NOT use expressions of any kind:
         *
         * - { type: "binaryExpression", operator: "+", left: "Customer", right: "
         *   validation" }
         * - { type: "stringLiteral", value: "some string" }
         * - Any IExpression types - this is NOT an expression field!
         *
         * ✅ CORRECT - Use direct string values only:
         *
         * - "Customer ID should match created entity"
         * - Simple, complete descriptive text as a raw string
         *
         * Should clearly describe the business context and expectation being
         * tested. This title appears in test failure messages to help with
         * debugging.
         *
         * Examples:
         *
         * - "Customer ID should match created entity"
         * - "Order status should be confirmed after payment"
         * - "Product price should equal the specified amount"
         * - "Review content should match updated values"
         *
         * AI title strategy: Use business-meaningful descriptions that explain the
         * validation purpose and help developers understand test failures.
         */
        title: string & tags.MinLength<1>;
        /**
         * Expected value expression (first parameter to TestValidator.equals).
         *
         * Represents the value that should be returned or the expected state after
         * a business operation. Typically literal values or previously captured
         * data from earlier API operations.
         *
         * Common patterns:
         *
         * - String literals for expected names, statuses, or codes
         * - Numeric literals for expected quantities, prices, or scores
         * - Identifiers referencing captured entity IDs or data from API operations
         * - Object literals for expected data structures
         *
         * AI value selection: Choose expected values that reflect realistic
         * business outcomes and match the API response schema.
         */
        x: IExpression;
        /**
         * Actual value expression (second parameter to TestValidator.equals).
         *
         * Represents the actual value returned from API operations or business
         * operations that needs validation. Often property access expressions
         * extracting specific fields from captured API response data.
         *
         * Common patterns:
         *
         * - Property access for API response fields (customer.id, order.status)
         * - Identifiers for captured variables from API operations
         * - Array/object element access for nested data from API responses
         * - Function call results for computed values (excluding API calls)
         *
         * AI expression construction: Ensure the actual value expression extracts
         * the correct data from API responses according to the schema structure.
         */
        y: IExpression;
    }
    /**
     * Inequality validation predicate for TestValidator assertion.
     *
     * Used for negative validations and ensuring values have changed or differ
     * from previous states.
     *
     * **Preferred over manual validation**: Use this instead of `IIfStatement`
     * with throw statements for inequality checking.
     *
     * E2E testing scenarios:
     *
     * - Verifying values have changed after update API operations
     * - Confirming different entities have different identifiers
     * - Ensuring sensitive data is not exposed in API responses
     * - Validating that values are NOT of unexpected types
     *
     * AI function calling usage: Use when business logic requires confirming
     * differences or ensuring values have been modified by API operations.
     * Important for testing update operations and data transformations.
     */
    interface INotEqualPredicate {
        /** Type discriminator. */
        type: "notEqualPredicate";
        /**
         * Descriptive title explaining what inequality is being validated.
         *
         * 🚨 CRITICAL: This MUST be a simple string value, NOT an expression! 🚨
         *
         * ❌ WRONG - DO NOT use expressions of any kind:
         *
         * - { type: "binaryExpression", operator: "+", left: "Value", right: " should
         *   differ" }
         * - { type: "stringLiteral", value: "some string" }
         * - Any IExpression types - this is NOT an expression field!
         *
         * ✅ CORRECT - Use direct string values only:
         *
         * - "Updated product name should differ from original"
         * - Simple, complete descriptive text as a raw string
         *
         * Should clearly describe why the values should NOT be equal or what
         * difference is expected. This helps with understanding test intent and
         * debugging failures.
         *
         * Examples:
         *
         * - "Updated product name should differ from original"
         * - "New order ID should not match previous order"
         * - "Modified review should have different content"
         * - "Response should not contain sensitive password data"
         *
         * AI title strategy: Focus on the business reason for the inequality check
         * and what change or difference is being validated.
         */
        title: string & tags.MinLength<1>;
        /**
         * First value expression for comparison.
         *
         * Typically represents the original value, previous state, or value that
         * should be different from the second expression. Often captured from
         * earlier API operations or represents a baseline state.
         *
         * Common patterns:
         *
         * - Original values before update API operations
         * - Different entity identifiers from API responses
         * - Previous state values captured from earlier API calls
         * - Baseline data for comparison
         */
        x: IExpression;
        /**
         * Second value expression for comparison.
         *
         * Represents the new value, current state, or value that should differ from
         * the first expression. Often the result of API operations or updated data
         * captured from API responses.
         *
         * Common patterns:
         *
         * - Updated values after modification API operations
         * - Current entity states from API responses
         * - New data from API responses
         * - Transformed or processed values
         */
        y: IExpression;
    }
    /**
     * Conditional validation predicate for TestValidator assertion.
     *
     * Generates TestValidator validation calls based on boolean conditions. Used
     * for validating business logic conditions, state checks, and conditional
     * assertions that depend on runtime data or business rules from API
     * responses.
     *
     * **Preferred over manual validation**: Use this instead of `IIfStatement`
     * with throw statements for conditional validation logic.
     *
     * E2E testing scenarios:
     *
     * - Validating business rule compliance using API response data
     * - Checking conditional states (user roles, feature flags) from API calls
     * - Verifying complex boolean logic conditions involving captured data
     * - Ensuring data meets business constraints after API operations
     *
     * AI function calling usage: Use when test validation depends on evaluating
     * business conditions rather than simple equality checks. Essential for
     * testing complex business logic and rule-based systems with API
     * integration.
     */
    interface IConditionalPredicate {
        /** Type discriminator. */
        type: "conditionalPredicate";
        /**
         * Descriptive title explaining the conditional logic being validated.
         *
         * 🚨 CRITICAL: This MUST be a simple string value, NOT an expression! 🚨
         *
         * ❌ WRONG - DO NOT use expressions of any kind:
         *
         * - { type: "binaryExpression", operator: "+", left: "User", right: " should
         *   have access" }
         * - { type: "stringLiteral", value: "some string" }
         * - Any IExpression types - this is NOT an expression field!
         *
         * ✅ CORRECT - Use direct string values only:
         *
         * - "Premium customer should have access to exclusive features"
         * - Simple, complete descriptive text as a raw string
         *
         * Should clearly describe the business condition or rule being tested and
         * why it should be true. This helps understand the business context and
         * debug failures when conditions aren't met.
         *
         * Examples:
         *
         * - "Premium customer should have access to exclusive features"
         * - "Order total should exceed minimum purchase amount"
         * - "Product should be available for selected category"
         * - "User should have sufficient permissions for this operation"
         *
         * AI title strategy: Explain the business rule or condition being validated
         * and its importance to the overall business workflow.
         */
        title: string & tags.MinLength<1>;
        /**
         * Boolean expression representing the condition to be validated.
         *
         * Should evaluate to true when the business condition is met. Can be simple
         * comparisons or complex logical expressions combining multiple business
         * rules and data checks involving captured API response data.
         *
         * Common patterns:
         *
         * - Comparison expressions using captured data (customer.tier === "premium")
         * - Logical combinations (hasPermission && isActive) with API response data
         * - Type checks using typia.is<Type>(capturedValue)
         * - Complex business rule evaluations with captured entities
         *
         * AI condition construction: Build conditions that accurately represent
         * business rules and constraints relevant to the test scenario, using data
         * captured from API operations.
         */
        expression: IExpression;
    }
    /**
     * General error validation predicate for TestValidator assertion.
     *
     * Generates TestValidator.error() call to verify that operations correctly
     * throw errors under specific conditions. Used for testing error handling,
     * business rule violations, and validation of both general errors and
     * HTTP-specific error conditions in API operations.
     *
     * **Preferred over manual error testing**: Use this instead of `IIfStatement`
     * with throw statements or try-catch blocks for error validation.
     *
     * E2E testing scenarios:
     *
     * - Testing business logic validation errors
     * - Verifying general exception handling in utility functions
     * - Confirming error throwing for invalid business operations
     * - Testing HTTP status code responses from API operations (400, 401, 403, 404,
     *   etc.)
     * - Testing authentication failures and authorization errors
     * - Validating API request validation errors and conflict responses
     *
     * AI function calling usage: Use when business scenarios should intentionally
     * fail to test error handling, including both general errors and specific
     * HTTP status code validation from API operations.
     */
    interface IErrorPredicate {
        /** Type discriminator. */
        type: "errorPredicate";
        /**
         * Descriptive title explaining the error condition being tested.
         *
         * 🚨 CRITICAL: This MUST be a simple string value, NOT an expression! 🚨
         *
         * ❌ WRONG - DO NOT use expressions of any kind:
         *
         * - { type: "binaryExpression", operator: "+", left: "Should fail", right: "
         *   with invalid data" }
         * - { type: "stringLiteral", value: "some string" }
         * - Any IExpression types - this is NOT an expression field!
         *
         * ✅ CORRECT - Use direct string values only:
         *
         * - "Should fail business validation with invalid data"
         * - Simple, complete descriptive text as a raw string
         *
         * Should clearly describe what error is expected and why it should occur.
         * This helps understand the negative test case purpose and assists with
         * debugging when expected errors don't occur.
         *
         * Examples:
         *
         * **General Error Testing:**
         *
         * - "Should fail business validation with invalid data"
         * - "Should throw error for duplicate entity creation"
         * - "Should reject operation with insufficient business context"
         * - "Should validate required business rule constraints"
         *
         * **HTTP Error Testing:**
         *
         * - "Should return 401 for invalid authentication credentials"
         * - "Should return 403 for unauthorized customer access"
         * - "Should return 400 for missing required fields in registration"
         * - "Should return 404 for non-existent product ID"
         * - "Should return 409 for duplicate email registration"
         * - "Should return 422 for invalid business data format"
         * - "Should return 429 for rate limit exceeded"
         *
         * AI title strategy: Focus on the specific error condition and business
         * context that should trigger the failure. Include HTTP status codes when
         * testing API error responses for clarity and debugging assistance.
         */
        title: string & tags.MinLength<1>;
        /**
         * Arrow function containing the operation that should throw an error.
         *
         * Encapsulates the API operation or business logic that is expected to
         * fail. The function should contain realistic API operations (using
         * IApiOperateStatement within the function body) with invalid data or
         * conditions that trigger appropriate error responses.
         *
         * **Note**: The function body can contain IApiOperateStatement calls since
         * this is specifically for testing API error conditions.
         *
         * **General Error Testing Patterns:**
         *
         * - API calls with invalid business data that should trigger general errors
         * - API operations with malformed or missing required data
         * - Business rule violations that should be rejected by API operations
         * - General validation failures and custom error conditions
         *
         * **HTTP Error Testing Patterns:**
         *
         * **Authentication Errors (401)**:
         *
         * - API calls with invalid or expired tokens
         * - Login attempts with wrong credentials
         * - Access without required authentication headers
         *
         * **Authorization Errors (403)**:
         *
         * - API calls with insufficient user permissions
         * - Access to restricted resources by unauthorized users
         * - Operations requiring admin privileges by regular users
         *
         * **Validation Errors (400, 422)**:
         *
         * - API calls with missing required fields
         * - Invalid data format or type in request body
         * - Business rule violations in API parameters
         *
         * **Not Found Errors (404)**:
         *
         * - API calls with non-existent resource IDs
         * - Access to deleted or unavailable resources
         * - Invalid endpoint or resource paths
         *
         * **Conflict Errors (409)**:
         *
         * - Duplicate resource creation attempts
         * - Concurrent modification conflicts
         * - Business rule conflicts (e.g., duplicate emails)
         *
         * **Rate Limiting Errors (429)**:
         *
         * - Excessive API calls within time window
         * - Quota exceeded for API operations
         * - Throttling due to usage limits
         *
         * **Server Errors (5xx)**:
         *
         * - API calls that trigger internal server errors
         * - Operations that cause service unavailability
         * - Database connection or processing failures
         *
         * AI function construction: Create realistic error scenarios that test
         * actual business constraints and error handling. Focus on API operation
         * error conditions that should throw errors, including both general
         * exceptions and specific HTTP status code responses.
         */
        function: IArrowFunction;
    }
    /**
     * Property assignment for object literal construction.
     *
     * Represents individual key-value pairs within object literals. Critical for
     * building request bodies, configuration objects, and structured data that
     * conforms to API schemas and business requirements, particularly for use in
     * `IApiOperateStatement` operations.
     *
     * E2E testing importance: Each property assignment must align with DTO schema
     * requirements to ensure valid API requests and realistic business data
     * representation.
     *
     * AI function calling requirement: Property names and value types must match
     * target schema definitions exactly, especially when used for API operation
     * parameters.
     */
    interface IPropertyAssignment {
        /**
         * Type discriminator for property assignments.
         *
         * Always "propertyAssignment" to distinguish from other object construction
         * mechanisms in the AST.
         */
        type: "propertyAssignment";
        /**
         * Property name (object key).
         *
         * Must correspond to actual property names defined in target DTO schemas,
         * API specifications, or business data models. Should use camelCase
         * convention matching TypeScript interfaces.
         *
         * **API context**: When used in request bodies for API operations, must
         * exactly match the expected parameter names in the API specification.
         *
         * Examples:
         *
         * - "name" for entity names in API requests
         * - "email" for contact information in API calls
         * - "price" for monetary values in business API operations
         * - "createdAt" for timestamps in API responses
         * - "isActive" for boolean flags in API parameters
         *
         * AI validation requirement: Ensure property names exist in the target
         * schema and follow exact naming conventions used in API specifications.
         */
        name: string & tags.MinLength<1>;
        /**
         * Property value expression.
         *
         * Expression that evaluates to the property value. Type must match the
         * expected type for this property in the target schema. Should represent
         * realistic business data appropriate for the property's purpose.
         *
         * - **⚠️ CRITICAL AI RESTRICTION: This MUST be an AST expression, NOT a raw
         *   value! ⚠️**
         * - **❌ WRONG: "John Doe" (raw string)**
         * - **❌ WRONG: 123 (raw number)**
         * - **❌ WRONG: true (raw boolean)**
         * - **✅ CORRECT: IStringLiteral, INumericLiteral, IBooleanLiteral (AST
         *   expressions)**
         *
         * **API usage**: When used in API operation parameters, must generate
         * values compatible with the API specification requirements.
         *
         * Common patterns:
         *
         * - String literals for names, descriptions, codes in API requests
         * - Numeric literals for quantities, prices, scores in API calls
         * - Boolean literals for flags and states in API parameters
         * - Object literals for nested business data in API requests
         * - Array literals for collections in API operations
         * - Random generators for variable test data in API calls
         * - Identifiers for referencing captured data from previous API operations
         *
         * AI type matching: Must generate expressions that produce values
         * compatible with the target property's schema type and API constraints.
         */
        value: IExpression;
    }
}