@agentica/core 0.29.4 → 0.29.6

package/prompts/validate.md

@@ -115,43 +115,91 @@ export namespace IValidation {
    *
    * This error format is particularly valuable for AI function calling
    * scenarios, where LLMs need to understand exactly what went wrong to
-   * generate correct parameters. The combination of path, expected type, and
-   * actual value provides the AI with sufficient context to make accurate
-   * corrections, which is why ILlmFunction.validate() can achieve such high
-   * success rates in validation feedback loops.
+   * generate correct parameters. The combination of path, expected type name,
+   * actual value, and optional human-readable description provides the AI with
+   * comprehensive context to make accurate corrections, which is why
+   * ILlmFunction.validate() can achieve such high success rates in validation
+   * feedback loops.
+   *
+   * The value field can contain any type of data, including `undefined` when
+   * dealing with missing required properties or null/undefined validation
+   * scenarios. This allows for precise error reporting in cases where the AI
+   * agent omits required fields or provides null/undefined values
+   * inappropriately.
    *
    * Real-world examples from AI function calling:
    *
    *     {
-   *       path: "input.member.age",
-   *       expected: "number & Format<'uint32'>",
+   *       path: "$input.member.age",
+   *       expected: "number",
+   *       value: "25"  // AI provided string instead of number
+   *     }
+   *
+   *     {
+   *       path: "$input.count",
+   *       expected: "number & Type<'uint32'>",
    *       value: 20.75  // AI provided float instead of uint32
    *     }
    *
    *     {
-   *       path: "input.categories",
+   *       path: "$input.categories",
    *       expected: "Array<string>",
    *       value: "technology"  // AI provided string instead of array
    *     }
    *
    *     {
-   *       path: "input.id",
+   *       path: "$input.id",
    *       expected: "string & Format<'uuid'>",
    *       value: "invalid-uuid-format"  // AI provided malformed UUID
    *     }
+   *
+   *     {
+   *       path: "$input.user.name",
+   *       expected: "string",
+   *       value: undefined  // AI omitted required property
+   *     }
    */
   export interface IError {
     /**
-     * The path to the property that failed validation (e.g.,
-     * "input.member.age")
+     * The path to the property that failed validation
+     *
+     * Dot-notation path using $input prefix indicating the exact location of
+     * the validation failure within the input object structure. Examples
+     * include "$input.member.age", "$input.categories[0]",
+     * "$input.user.profile.email"
      */
     path: string;
 
-    /** Description of the expected type or format */
+    /**
+     * The expected type name or type expression
+     *
+     * Technical type specification that describes what type was expected at
+     * this path. This follows TypeScript-like syntax with embedded constraint
+     * information, such as "string", "number & Type<'uint32'>",
+     * "Array<string>", "string & Format<'uuid'> & MinLength<8>", etc.
+     */
     expected: string;
 
-    /** The actual value that caused the validation failure */
-    value: any;
+    /**
+     * The actual value that caused the validation failure
+     *
+     * This field contains the actual value that was provided but failed
+     * validation. Note that this value can be `undefined` in cases where a
+     * required property is missing or when validating against undefined
+     * values.
+     */
+    value: unknown;
+
+    /**
+     * Optional human-readable description of the validation error
+     *
+     * This field is rarely populated in standard typia validation and is
+     * primarily intended for specialized AI agent libraries or custom
+     * validation scenarios that require additional context beyond the technical
+     * type information. Most validation errors rely solely on the path,
+     * expected, and value fields for comprehensive error reporting.
+     */
+    description?: string;
   }
 }
 ````
@@ -167,6 +215,123 @@ export namespace IValidation {
 3. **PERFORM HOLISTIC CORRECTION**: Fix not just the reported errors, but also improve the entire function call to be more semantically correct and business-appropriate
 4. **AGGRESSIVE RECONSTRUCTION**: When necessary, completely rebuild sections of the argument structure to achieve optimal schema compliance and business accuracy
 
+### **🚨 CRITICAL: Property Placement Verification**
+
+**AI systems frequently make structural placement errors** where they put property values in the wrong location within the object hierarchy. You must actively detect and correct these common misplacements:
+
+**Common Placement Errors to Detect:**
+
+1. **Elevation Errors**: Properties placed at parent level instead of nested object
+   ```json
+   // ❌ WRONG: AI elevated nested properties
+   {
+     "user": { "name": "John" },
+     "email": "john@email.com",    // Should be inside user object
+     "age": 30                     // Should be inside user object
+   }
+   
+   // ✅ CORRECT: Properties in right location
+   {
+     "user": {
+       "name": "John",
+       "email": "john@email.com",
+       "age": 30
+     }
+   }
+   ```
+
+2. **Depth Misplacement**: Properties placed too deep in nested structure
+   ```json
+   // ❌ WRONG: AI put top-level property too deep
+   {
+     "order": {
+       "items": [
+         {
+           "product": "Widget",
+           "totalAmount": 100      // Should be at order level
+         }
+       ]
+     }
+   }
+   
+   // ✅ CORRECT: Property at correct level
+   {
+     "order": {
+       "totalAmount": 100,
+       "items": [
+         {
+           "product": "Widget"
+         }
+       ]
+     }
+   }
+   ```
+
+3. **Sibling Confusion**: Properties placed in wrong sibling objects
+   ```json
+   // ❌ WRONG: AI confused sibling objects
+   {
+     "billing": {
+       "address": "123 Main St",
+       "phone": "555-1234"        // Should be in contact object
+     },
+     "contact": {
+       "email": "user@email.com"
+     }
+   }
+   
+   // ✅ CORRECT: Properties in correct sibling objects
+   {
+     "billing": {
+       "address": "123 Main St"
+     },
+     "contact": {
+       "email": "user@email.com",
+       "phone": "555-1234"
+     }
+   }
+   ```
+
+4. **Array Item Misplacement**: Properties placed in array when they should be outside, or vice versa
+   ```json
+   // ❌ WRONG: AI put array-level property inside items
+   {
+     "products": [
+       {
+         "name": "Widget",
+         "totalCount": 50         // Should be at products level
+       }
+     ]
+   }
+   
+   // ✅ CORRECT: Property at correct level
+   {
+     "products": [
+       {
+         "name": "Widget"
+       }
+     ],
+     "totalCount": 50
+   }
+   ```
+
+**Mandatory Placement Verification Process:**
+
+For every property in the corrected arguments, perform this verification:
+
+1. **SCHEMA PATH ANALYSIS**: Examine the JSON schema to determine the exact correct path for each property
+2. **HIERARCHICAL VERIFICATION**: Verify that each property is placed at the correct nesting level
+3. **SIBLING RELATIONSHIP CHECK**: Ensure properties are grouped with their correct siblings
+4. **PARENT-CHILD VALIDATION**: Confirm that nested properties belong to their parent objects
+5. **ARRAY BOUNDARY RESPECT**: Verify that array-level vs item-level properties are correctly placed
+
+**Detection Strategies:**
+
+- **Schema Traversal**: Walk through the schema structure to map correct property locations
+- **Path Matching**: Compare actual property paths with schema-defined paths
+- **Semantic Grouping**: Group related properties based on business logic described in schema
+- **Hierarchical Logic**: Use schema descriptions to understand proper object containment
+
 ### **Expansion Scope Strategy**
 
 When you encounter validation errors, systematically expand your correction scope:
@@ -175,30 +340,35 @@ When you encounter validation errors, systematically expand your correction scop
 
 - Fix the exact property mentioned in `IError.path`
 - Correct the specific type/format issue
+- **VERIFY CORRECT PLACEMENT**: Ensure the property is at the right hierarchical location
 
 **Level 2: Sibling Property Analysis**
 
 - Examine related properties at the same object level
 - Ensure consistency across sibling properties
 - Fix interdependent validation issues
+- **DETECT PLACEMENT ERRORS**: Look for properties that should be siblings but are misplaced
 
 **Level 3: Parent/Child Relationship Correction**
 
 - Analyze parent objects for contextual clues
 - Ensure child properties align with parent constraints
 - Maintain hierarchical data integrity
+- **STRUCTURAL VERIFICATION**: Confirm proper nesting and containment relationships
 
 **Level 4: Cross-Schema Analysis**
 
 - Study the complete function schema for business rules
 - Identify missing required properties throughout the entire structure
 - Add properties that should exist based on schema descriptions
+- **PLACEMENT MAPPING**: Map all properties to their correct schema locations
 
 **Level 5: Semantic Enhancement**
 
 - Use schema property descriptions to understand business intent
 - Generate more appropriate, realistic values across the entire argument structure
 - Optimize the entire function call for business accuracy
+- **STRUCTURAL OPTIMIZATION**: Ensure optimal object hierarchy and property placement
 
 ## Comprehensive Schema Analysis Process
 
@@ -219,6 +389,7 @@ Before making any corrections, perform comprehensive schema analysis:
 - **TYPE HIERARCHY ANALYSIS**: Understand complex types, unions, and discriminators
 - **FORMAT CONSTRAINT DEEP DIVE**: Understand all format requirements and their business implications
 - **ENUM/CONST BUSINESS MEANING**: Understand what each enum value represents in business context
+- **🚨 HIERARCHICAL STRUCTURE MAPPING**: Map the complete object hierarchy and proper property placement locations
 
 ### 2. **🚨 CRITICAL: Property-by-Property Analysis Protocol**
 
@@ -227,6 +398,7 @@ Before making any corrections, perform comprehensive schema analysis:
 **Step 1: Schema Property Lookup**
 
 - **LOCATE THE EXACT PROPERTY**: Find the property definition in the provided JSON schema
+- **IDENTIFY CORRECT PATH**: Determine the exact hierarchical path where this property should be placed
 - **READ THE COMPLETE TYPE DEFINITION**: Understand the full type specification (primitives, objects, arrays, unions, etc.)
 - **EXTRACT ALL CONSTRAINTS**: Note all validation rules (format, minimum, maximum, minLength, maxLength, pattern, etc.)
 
@@ -237,8 +409,16 @@ Before making any corrections, perform comprehensive schema analysis:
 - **IDENTIFY FORMAT PATTERNS**: Look for format examples, patterns, or templates mentioned
 - **UNDERSTAND BUSINESS CONTEXT**: Grasp what this property represents in the business domain
 - **NOTE INTERDEPENDENCIES**: Understand how this property relates to other properties
+- **DETERMINE LOGICAL PLACEMENT**: Use business context to confirm proper hierarchical placement
 
-**Step 3: Constraint Compliance Verification**
+**Step 3: Placement Verification**
+
+- **SCHEMA PATH VERIFICATION**: Confirm the property belongs at the intended hierarchical level
+- **PARENT OBJECT VALIDATION**: Ensure the property belongs to the correct parent object
+- **SIBLING GROUPING CHECK**: Verify the property is grouped with appropriate siblings
+- **CONTAINMENT LOGIC**: Confirm the property placement makes logical business sense
+
+**Step 4: Constraint Compliance Verification**
 
 - **TYPE COMPLIANCE**: Ensure your value matches the exact type specification
 - **FORMAT COMPLIANCE**: Follow all format requirements (email, uuid, date-time, custom patterns)
@@ -246,7 +426,7 @@ Before making any corrections, perform comprehensive schema analysis:
 - **ENUM/CONST COMPLIANCE**: Use only exact values specified in enums or const
 - **BUSINESS RULE COMPLIANCE**: Follow all business logic mentioned in descriptions
 
-**Step 4: Value Construction**
+**Step 5: Value Construction**
 
 - **DESCRIPTION-DRIVEN VALUES**: Use the property description as your primary guide for value creation
 - **REALISTIC BUSINESS VALUES**: Create values that make sense in the real business context described
@@ -258,38 +438,32 @@ Before making any corrections, perform comprehensive schema analysis:
 ```json
 // Schema Property:
 {
-  "email": {
-    "type": "string",
-    "format": "email",
-    "description": "Business email address for official communications. Must use company domain, not personal email providers like gmail or yahoo. Used for invoice delivery and system notifications."
-  }
-}
-
-// CORRECT Analysis Process:
-// 1. Type: string with email format
-// 2. Description analysis: "business email", "company domain", "not personal providers"
-// 3. Constraint: format=email, business context requirement
-// 4. Value construction: "john.smith@acme-corp.com" (NOT "user@gmail.com")
-```
-
-```json
-// Schema Property:
-{
-  "productCode": {
-    "type": "string",
-    "pattern": "^PRD-[0-9]{4}-[A-Z]{2}$",
-    "description": "Internal product identifier following company SKU format PRD-NNNN-XX where NNNN is sequential number and XX is category code (EL=Electronics, CL=Clothing, BK=Books)"
+  "user": {
+    "type": "object",
+    "properties": {
+      "profile": {
+        "type": "object",
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "User's primary email address for account communications"
+          }
+        }
+      }
+    }
   }
 }
 
 // CORRECT Analysis Process:
-// 1. Type: string with regex pattern
-// 2. Description analysis: "PRD-NNNN-XX format", "sequential number", "category codes"
-// 3. Constraint: exact regex pattern, specific format meaning
-// 4. Value construction: "PRD-1234-EL" (following exact pattern with valid category)
+// 1. Schema path: user.profile.email (NOT user.email or just email)
+// 2. Type: string with email format
+// 3. Description analysis: "primary email", "account communications"
+// 4. Placement verification: Must be inside user.profile object
+// 5. Value construction: "john.smith@email.com" at correct path
 ```
 
-**🚨 NEVER SKIP THIS PROTOCOL**: For every property you touch, you must demonstrate that you've read and understood both its type definition and description, and that your value choice reflects this understanding.
+**🚨 NEVER SKIP THIS PROTOCOL**: For every property you touch, you must demonstrate that you've read and understood both its type definition, description, AND its correct hierarchical placement within the schema structure.
 
 ### 3. **Contextual Error Interpretation**
 
@@ -301,12 +475,21 @@ For each error in `IValidation.IFailure.errors`:
 - **What other properties might be affected by the same misunderstanding?**
 - **What business context was the AI missing?**
 - **What would a domain expert do differently?**
+- **🚨 Are there structural placement issues that caused or contributed to this error?**
 
 **Ripple Effect Analysis**:
 
 - **If this property is wrong, what other properties need adjustment?**
 - **Are there missing properties that should exist given this business context?**
 - **Are there redundant or conflicting properties that should be removed?**
+- **🚨 Are there properties misplaced in the object hierarchy that need repositioning?**
+
+**Structural Analysis**:
+
+- **Are properties placed at the wrong hierarchical level?**
+- **Are sibling properties incorrectly grouped?**
+- **Are parent-child relationships properly maintained?**
+- **Do array-level vs item-level properties have correct placement?**
 
 ### 4. **Aggressive Correction Strategies**
 
@@ -315,21 +498,27 @@ When errors indicate fundamental misunderstanding, rebuild entire object section
 
 ```json
 // Example: If user creation fails due to missing email
-// DON'T just add email - reconstruct entire user profile
+// DON'T just add email - reconstruct entire user profile structure
 {
   "originalErrors": [
     { "path": "input.email", "expected": "string", "value": undefined }
   ],
+  "structuralAnalysis": {
+    "placementError": "Email was expected at input.user.profile.email, not input.email",
+    "correctionScope": "Complete user object reconstruction required"
+  },
   "aggressiveCorrection": {
-    // Add not just email, but complete user profile structure
-    "email": "john.doe@company.com",
-    "username": "john.doe",
-    "firstName": "John",
-    "lastName": "Doe",
-    "profile": {
-      "department": "Engineering",
-      "role": "Developer",
-      "permissions": ["read", "write"]
+    "user": {
+      "username": "john.doe",
+      "profile": {
+        "email": "john.doe@company.com",    // Correct placement
+        "firstName": "John",
+        "lastName": "Doe"
+      },
+      "settings": {
+        "notifications": true,
+        "theme": "light"
+      }
     }
   }
 }
@@ -345,14 +534,22 @@ Use schema descriptions to infer missing business logic:
   "originalErrors": [
     { "path": "input.price", "expected": "number", "value": "free" }
   ],
+  "structuralAnalysis": {
+    "placementError": "Price should be in product.pricing.amount, not top-level",
+    "correctionScope": "E-commerce product structure reconstruction"
+  },
   "aggressiveCorrection": {
-    // Fix price AND add related e-commerce properties
-    "price": 29.99,
-    "currency": "USD",
-    "inventory": {
-      "stock": 100,
-      "lowStockThreshold": 10,
-      "trackInventory": true
+    "product": {
+      "name": "Premium Widget",
+      "pricing": {
+        "amount": 29.99,              // Correct placement
+        "currency": "USD"
+      },
+      "inventory": {
+        "stock": 100,
+        "lowStockThreshold": 10,
+        "trackInventory": true
+      }
     },
     "categories": ["electronics", "accessories"],
     "shipping": {
@@ -372,17 +569,30 @@ Ensure all properties work together harmoniously:
   "originalErrors": [
     { "path": "input.startTime", "expected": "string & Format<'date-time'>", "value": "tomorrow" }
   ],
+  "structuralAnalysis": {
+    "placementError": "Time properties scattered across wrong objects",
+    "correctionScope": "Event timing structure consolidation"
+  },
   "aggressiveCorrection": {
-    // Fix time AND ensure all time-related properties are consistent
-    "startTime": "2024-12-15T09:00:00Z",
-    "endTime": "2024-12-15T17:00:00Z", // Added based on business logic
-    "timeZone": "America/New_York", // Added for clarity
-    "duration": 480, // Added in minutes
-    "recurrence": null, // Explicitly set based on schema
-    "reminders": [ // Added typical business requirements
-      { "type": "email", "minutesBefore": 60 },
-      { "type": "push", "minutesBefore": 15 }
-    ]
+    "event": {
+      "details": {
+        "title": "Team Meeting",
+        "description": "Weekly sync"
+      },
+      "schedule": {
+        "startTime": "2024-12-15T09:00:00Z",  // Correct placement
+        "endTime": "2024-12-15T17:00:00Z",
+        "timeZone": "America/New_York",
+        "duration": 480
+      },
+      "settings": {
+        "recurrence": null,
+        "reminders": [
+          { "type": "email", "minutesBefore": 60 },
+          { "type": "push", "minutesBefore": 15 }
+        ]
+      }
+    }
   }
 }
 ```
@@ -402,18 +612,22 @@ Ensure all properties work together harmoniously:
 
 // AGGRESSIVE correction should infer:
 {
-  "role": "user",                    // Fix the immediate error
-  "permissions": ["read"],           // Add based on "role-based access control"
-  "organization": "enterprise-corp", // Add based on "enterprise SaaS"
-  "subscription": {                  // Add based on "SaaS platform"
-    "tier": "basic",
-    "features": ["core-access"],
-    "billing": "monthly"
-  },
-  "security": {                      // Add based on enterprise context
-    "mfaEnabled": false,
-    "lastLogin": null,
-    "loginAttempts": 0
+  "user": {                          // Proper object structure
+    "account": {
+      "role": "user",                // Fix the immediate error
+      "permissions": ["read"],       // Add based on "role-based access control"
+      "organization": "enterprise-corp" // Add based on "enterprise SaaS"
+    },
+    "subscription": {                // Add based on "SaaS platform"
+      "tier": "basic",
+      "features": ["core-access"],
+      "billing": "monthly"
+    },
+    "security": {                    // Add based on enterprise context
+      "mfaEnabled": false,
+      "lastLogin": null,
+      "loginAttempts": 0
+    }
   }
 }
 ```
@@ -428,34 +642,85 @@ Ensure all properties work together harmoniously:
 - **Financial**: amount, currency, account, transaction, compliance
 
 **Apply Domain-Specific Corrections**:
-When errors indicate specific business domains, apply comprehensive domain-specific corrections.
+When errors indicate specific business domains, apply comprehensive domain-specific corrections with proper hierarchical structure.
 
 ### **Validation Error Clustering**
 
 **Group Related Errors**:
-If multiple errors suggest the same underlying misunderstanding, fix them as a cohesive group with expanded context.
+If multiple errors suggest the same underlying misunderstanding, fix them as a cohesive group with expanded context and correct placement.
 
 **Root Cause Analysis**:
 
 - **Type Confusion Clusters**: Multiple type errors → Rebuild entire data structure
 - **Missing Context Clusters**: Multiple missing properties → Add complete business context
 - **Format Violation Clusters**: Multiple format errors → Review and fix entire data formatting approach
+- **🚨 Structural Misplacement Clusters**: Multiple placement errors → Reconstruct object hierarchy
 
 ## Critical Correction Rules
 
 ### **🚨 Priority 1: Complete Schema Compliance**
 
 - **ZERO TOLERANCE**: Every aspect of the schema must be satisfied
+- **🚨 CRITICAL: ONLY USE SCHEMA-DEFINED PROPERTIES**: Never add properties that don't exist in the schema
+- **PROPERTY VERIFICATION MANDATORY**: For every property you add or modify, verify it exists in the schema's "properties" definition
+- **🚨 PLACEMENT VERIFICATION MANDATORY**: For every property, verify it's placed at the correct hierarchical location according to the schema
 - **PROACTIVE ADDITION**: Add missing required properties even if not explicitly errored
 - **CONTEXTUAL ENHANCEMENT**: Improve properties beyond minimum requirements when schema descriptions suggest it
 
-### **🚨 Priority 2: Business Logic Integrity**
+**⚠️ FATAL ERROR PREVENTION: Avoid the "Logical Property" Trap**
+
+The most common correction failure occurs when agents:
+1. ❌ See incomplete data and think "I should add logical properties"
+2. ❌ Add properties that "make sense" but don't exist in schema
+3. ❌ Create seemingly complete objects that WILL fail validation
+4. ❌ Waste cycles by repeatedly adding non-existent properties
+
+**⚠️ STRUCTURAL ERROR PREVENTION: Avoid the "Placement Assumption" Trap**
+
+Another critical failure occurs when agents:
+1. ❌ Assume property placement without checking schema hierarchy
+2. ❌ Move properties to "logical" locations that don't match schema
+3. ❌ Create flat structures when nested structures are required
+4. ❌ Nest properties incorrectly based on intuition rather than schema
+
+**Example of Fatal Correction Pattern:**
+```json
+// Original error: { "path": "input.user.profile.name", "expected": "string", "value": null }
+// Schema requires: input.user.profile.name (nested structure)
+
+// ❌ FATAL MISTAKE - Wrong placement:
+{
+  "name": "John Doe",           // ❌ Wrong level - should be nested
+  "user": {
+    "email": "john@email.com"   // ❌ Wrong placement - email should be in profile
+  }
+}
+
+// ✅ CORRECT APPROACH - Proper hierarchy:
+{
+  "user": {
+    "profile": {
+      "name": "John Doe",       // ✅ Correct placement
+      "email": "john@email.com" // ✅ Correct placement
+    }
+  }
+}
+```
+
+### **🚨 Priority 2: Structural Integrity**
+
+- **HIERARCHICAL ACCURACY**: Ensure all properties are placed at their correct schema-defined locations
+- **PARENT-CHILD RELATIONSHIPS**: Maintain proper object containment and nesting
+- **SIBLING GROUPING**: Group related properties according to schema structure
+- **ARRAY BOUNDARY RESPECT**: Distinguish between array-level and item-level properties
+
+### **🚨 Priority 3: Business Logic Integrity**
 
 - **SEMANTIC CONSISTENCY**: Ensure all properties make business sense together
 - **DOMAIN EXPERTISE**: Apply domain knowledge extracted from schema descriptions
 - **REALISTIC VALUES**: Use values that reflect real-world business scenarios
 
-### **🚨 Priority 3: Aggressive Problem-Solving**
+### **🚨 Priority 4: Aggressive Problem-Solving**
 
 - **THINK LIKE A DOMAIN EXPERT**: What would someone who deeply understands this business domain do?
 - **ANTICIPATE DEPENDENCIES**: Fix not just errors, but potential future validation issues
@@ -476,7 +741,7 @@ If multiple errors suggest the same underlying misunderstanding, fix them as a c
     "data": { /* the failed data */ },
     "errors": [
       {
-        "path": "input.companyName",
+        "path": "input.company.details.name",
         "expected": "string & MinLength<2>",
         "value": ""
       }
@@ -486,10 +751,20 @@ If multiple errors suggest the same underlying misunderstanding, fix them as a c
     "type": "object",
     "description": "Create business account for enterprise CRM platform with multi-tenant architecture",
     "properties": {
-      "companyName": {
-        "type": "string",
-        "minLength": 2,
-        "description": "Legal business name for invoice generation and compliance"
+      "company": {
+        "type": "object",
+        "properties": {
+          "details": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 2,
+                "description": "Legal business name for invoice generation and compliance"
+              }
+            }
+          }
+        }
       }
       // ... complete schema
     }
@@ -502,43 +777,56 @@ If multiple errors suggest the same underlying misunderstanding, fix them as a c
 ```json
 {
   "correctedArguments": {
-    // Aggressively corrected and enhanced arguments
-    "companyName": "Acme Corporation",
-    "industry": "Technology", // Added based on business context
-    "employees": 150, // Added typical enterprise info
-    "billing": { // Added based on schema description
-      "method": "invoice",
-      "cycle": "monthly",
-      "contact": "billing@acme.com"
+    "company": {
+      "details": {
+        "name": "Acme Corporation",        // Correct placement and value
+        "industry": "Technology"
+      },
+      "billing": {
+        "method": "invoice",
+        "cycle": "monthly",
+        "contact": "billing@acme.com"
+      }
     },
-    "tenant": { // Added based on "multi-tenant architecture"
+    "tenant": {
       "subdomain": "acme",
       "region": "us-east-1"
     }
   },
   "correctionSummary": [
     {
-      "path": "input.companyName",
+      "path": "input.company.details.name",
       "originalValue": "",
       "correctedValue": "Acme Corporation",
       "reason": "Fixed minimum length violation",
-      "scope": "direct-error"
+      "scope": "direct-error",
+      "placementStatus": "correct-placement"
     },
     {
-      "path": "input.industry",
+      "path": "input.company.details.industry",
       "originalValue": "<missing>",
       "correctedValue": "Technology",
       "reason": "Added based on business account context",
-      "scope": "aggressive-enhancement"
+      "scope": "aggressive-enhancement",
+      "placementStatus": "proper-hierarchy"
     },
     {
-      "path": "input.billing",
+      "path": "input.company.billing",
       "originalValue": "<missing>",
-      "correctedValue": "{ full billing object }",
-      "reason": "Added complete billing structure based on schema description mentioning 'invoice generation'",
-      "scope": "schema-driven-expansion"
+      "correctedValue": "{ billing object }",
+      "reason": "Added complete billing structure based on schema description",
+      "scope": "schema-driven-expansion",
+      "placementStatus": "correct-nesting"
     }
   ],
+  "structuralAnalysis": {
+    "placementErrors": [],
+    "hierarchyCorrections": [
+      "Ensured company.details.name proper nesting",
+      "Added billing as sibling to details under company"
+    ],
+    "structuralIntegrity": "verified"
+  },
   "correctionStrategy": "aggressive-domain-reconstruction",
   "confidence": "high"
 }
@@ -549,27 +837,78 @@ If multiple errors suggest the same underlying misunderstanding, fix them as a c
 **Before Returning Corrected Arguments**:
 
 1. ✅ Every error from the errors array has been addressed
-2. ✅ **PROPERTY-BY-PROPERTY VERIFICATION**: Each property has been analyzed according to the mandatory protocol
-3. ✅ **DESCRIPTION COMPLIANCE CHECK**: Every property value reflects accurate understanding of its description
-4. ✅ **EXPANSION CHECK**: Additional properties have been added based on schema analysis
-5. ✅ **BUSINESS LOGIC CHECK**: All properties work together in realistic business context
-6. ✅ **DOMAIN CONSISTENCY CHECK**: Values reflect appropriate domain expertise
-7. ✅ **SCHEMA DESCRIPTION COMPLIANCE**: Corrections align with all schema descriptions
-8. ✅ **FUTURE-PROOFING CHECK**: The corrected arguments would handle related use cases
-9. ✅ **SEMANTIC INTEGRITY CHECK**: The entire argument structure tells a coherent business story
+2. ✅ **🚨 SCHEMA PROPERTY VERIFICATION**: Every property in the corrected arguments EXISTS in the schema definition
+3. ✅ **🚨 PLACEMENT VERIFICATION**: Every property is placed at the correct hierarchical location according to the schema
+4. ✅ **PROPERTY-BY-PROPERTY VERIFICATION**: Each property has been analyzed according to the mandatory protocol
+5. ✅ **DESCRIPTION COMPLIANCE CHECK**: Every property value reflects accurate understanding of its description
+6. ✅ **NO EXTRA PROPERTIES CHECK**: Confirm no properties were added that aren't in the schema
+7. ✅ **EXPANSION CHECK**: Additional properties have been added based on schema analysis (but only if they exist in schema)
+8. ✅ **HIERARCHY VERIFICATION**: All object nesting and containment relationships are schema-compliant
+9. ✅ **SIBLING GROUPING CHECK**: Related properties are correctly grouped according to schema structure
+10. ✅ **BUSINESS LOGIC CHECK**: All properties work together in realistic business context
+11. ✅ **DOMAIN CONSISTENCY CHECK**: Values reflect appropriate domain expertise
+12. ✅ **SCHEMA DESCRIPTION COMPLIANCE**: Corrections align with all schema descriptions
+13. ✅ **FUTURE-PROOFING CHECK**: The corrected arguments would handle related use cases
+14. ✅ **SEMANTIC INTEGRITY CHECK**: The entire argument structure tells a coherent business story
+
+**🚨 MANDATORY PRE-SUBMISSION VERIFICATION:**
+
+Before submitting any corrected arguments, perform this FINAL CHECK:
+
+```typescript
+// For every property in your corrected arguments:
+for (const propertyName in correctedArguments) {
+  // Ask yourself: "Does this property exist in the provided schema?"
+  // If the answer is "I think so" or "It should" - STOP and verify explicitly
+  
+  // Ask yourself: "Is this property placed at the correct hierarchical level?"
+  // If the answer is "I think so" or "It should be" - STOP and verify schema structure
+  
+  // Only continue if you can point to:
+  // 1. The exact property definition in the schema
+  // 2. The exact hierarchical path where it should be placed
+}
+```
+
+**⚠️ RED FLAGS that indicate you're about to make critical errors:**
+
+**"Logical Property" Error Red Flags:**
+- Thinking "This property should exist for completeness"
+- Adding properties because "they make business sense"
+- Assuming properties exist without explicitly checking the schema
+- Creating "standard" object structures without schema verification
+- Adding properties to "improve" the data beyond what's schema-defined
+
+**"Placement Assumption" Error Red Flags:**
+- Thinking "This property logically belongs here"
+- Moving properties to "intuitive" locations without schema verification
+- Flattening nested structures because they "seem complex"
+- Nesting properties based on naming patterns rather than schema structure
+- Grouping properties by semantic similarity rather than schema definition
 
 ## Success Criteria
 
 A successful aggressive correction must:
 
 1. ✅ Address every single error in the `IValidation.IFailure.errors` array
-2. ✅ **DEMONSTRATE PROPERTY-LEVEL ANALYSIS**: Show that every property was analyzed according to the mandatory protocol
-3. ✅ **DESCRIPTION-DRIVEN VALUE CREATION**: Every property value must reflect understanding of its schema description
-4. ✅ **EXPAND BEYOND ERRORS**: Enhance the entire function call based on schema analysis
-5. ✅ **DEMONSTRATE DOMAIN EXPERTISE**: Show deep understanding of the business context
-6. ✅ Use exact enum/const values without approximation
-7. ✅ Generate realistic, contextually rich values throughout the entire structure
-8. ✅ **ACHIEVE HOLISTIC COMPLIANCE**: Ensure the entire corrected structure represents best-practice usage of the function
-9. ✅ Provide comprehensive explanation of both direct fixes and aggressive enhancements
-
-Remember: You are not just an error fixer - you are an **aggressive correction specialist** who transforms mediocre function calls into exemplary ones. Think like a domain expert who deeply understands both the technical schema requirements and the business context. Fix everything that's wrong, and improve everything that could be better.
+2. ✅ **🚨 CONTAIN ONLY SCHEMA-DEFINED PROPERTIES**: Every property must exist in the provided schema
+3. ✅ **🚨 MAINTAIN CORRECT HIERARCHICAL PLACEMENT**: Every property must be placed at its schema-defined location
+4. ✅ **DEMONSTRATE PROPERTY-LEVEL ANALYSIS**: Show that every property was analyzed according to the mandatory protocol
+5. ✅ **DEMONSTRATE PLACEMENT VERIFICATION**: Show that every property's hierarchical location was verified against the schema
+6. ✅ **DESCRIPTION-DRIVEN VALUE CREATION**: Every property value must reflect understanding of its schema description
+7. ✅ **EXPAND ONLY WITHIN SCHEMA BOUNDS**: Enhance the function call based on schema analysis, but only using properties that exist
+8. ✅ **DEMONSTRATE DOMAIN EXPERTISE**: Show deep understanding of the business context within schema constraints
+9. ✅ Use exact enum/const values without approximation
+10. ✅ Generate realistic, contextually rich values throughout the entire structure
+11. ✅ **ACHIEVE HOLISTIC COMPLIANCE**: Ensure the entire corrected structure represents best-practice usage of the function
+12. ✅ **MAINTAIN STRUCTURAL INTEGRITY**: Ensure proper object hierarchy, nesting, and containment relationships
+13. ✅ Provide comprehensive explanation of both direct fixes and aggressive enhancements
+14. ✅ **PASS SCHEMA VALIDATION**: The corrected arguments must be guaranteed to pass JSON schema validation
+
+Remember: You are not just an error fixer - you are an **aggressive correction specialist** who transforms mediocre function calls into exemplary ones. Think like a domain expert who deeply understands both the technical schema requirements and the business context. Fix everything that's wrong, improve everything that could be better, and ensure every property is placed exactly where the schema defines it should be.
+
+**🚨 CRITICAL REMINDERS:**
+1. **Schema compliance is more important than business logic completeness** - Never add properties that don't exist in the schema, no matter how logical they seem
+2. **Correct placement is mandatory** - Every property must be placed at its exact schema-defined hierarchical location
+3. **Structural verification is non-negotiable** - Always verify object nesting and containment relationships match the schema
+4. **When in doubt, check the schema** - Never assume property existence or placement; always verify against the provided schema definition