refactor: reorganize array expressions in proto for LLM-friendly development

- Group all array expressions together with inline documentation
- Add comments guiding future array function additions
- Preserve existing field numbers for backwards compatibility
- No functional changes, pure organization

Author: bcallender

protos/logical_plan/v1/expressions.proto

@@ -9,24 +9,65 @@ import "logical_plan/v1/enums.proto";
 // Base message for all logical expressions
 message LogicalExpr {
   oneof expr_type {
-    // Basic expressions
+    // ============================================================================
+    // Core Basic Expressions
+    // ============================================================================
     ColumnExpr column = 1;
     LiteralExpr literal = 2;
     AliasExpr alias = 3;
     SortExpr sort = 4;
     IndexExpr index = 5;
-    ArrayExpr array = 6;
     StructExpr struct = 7;
     CastExpr cast = 8;
     NotExpr not_expr = 9; //keyword
     CoalesceExpr coalesce = 10;
     InExpr in_expr = 11; //keyword
     IsNullExpr is_null = 12;
-    ArrayLengthExpr array_length = 13;
-    ArrayContainsExpr array_contains = 14;
+    UnresolvedLiteralExpr unresolved_literal = 17;
+
+    // ============================================================================
+    // Array Expressions
+    // When adding new array functions:
+    // - Add field definition here in this grouped section
+    // - Use next available number in 170-199 range
+    // - Follow naming pattern: array_<operation> or <operation> for general ops
+    // - Add corresponding message definition below (search for "Array message definitions")
+    // - Add serde in: src/fenic/core/_serde/proto/expressions/basic.py
+    // ============================================================================
+
+    // Array construction and introspection
+    ArrayExpr array = 6;                      // Construct array from elements
+    ArrayLengthExpr array_length = 13;        // Get array length (size)
+
+    // Array element operations
+    ArrayContainsExpr array_contains = 14;    // Check if array contains element
+    ElementAtExpr element_at = 182;           // Get element at index (1-based, PySpark compat)
+    ArraySliceExpr array_slice = 181;         // Extract subarray (start, length)
+
+    // Array transformation operations
+    ArrayDistinctExpr array_distinct = 18;    // Remove duplicates
+    ArrayMaxExpr array_max = 170;             // Get max element (primitives only)
+    ArrayMinExpr array_min = 171;             // Get min element (primitives only)
+    ArraySortExpr array_sort = 172;           // Sort ascending (primitives only, no comparator)
+    ArrayReverseExpr array_reverse = 173;     // Reverse array order
+    ArrayRemoveExpr array_remove = 174;       // Remove all occurrences of element
+    ArrayCompactExpr array_compact = 178;     // Remove null values
+    ArrayRepeatExpr array_repeat = 179;       // Create array by repeating element n times
+    FlattenExpr flatten = 180;                // Flatten array of arrays (one level)
+
+    // Array set operations (return distinct elements)
+    ArrayUnionExpr array_union = 175;         // Union of two arrays (distinct)
+    ArrayIntersectExpr array_intersect = 176; // Intersection of two arrays
+    ArrayExceptExpr array_except = 177;       // Elements in first but not second
+    ArraysOverlapExpr arrays_overlap = 183;   // Check if arrays have common elements
+
+    // Reserved for future array functions: 184-199
+
+    // ============================================================================
+    // Comparison and Logic Expressions
+    // ============================================================================
     GreatestExpr greatest = 15;
     LeastExpr least = 16;
-    UnresolvedLiteralExpr unresolved_literal = 17;
 
     // Binary expressions
     ArithmeticExpr arithmetic = 20;
@@ -190,15 +231,89 @@ message IsNullExpr {
   bool is_null = 2;
 }
 
+// =============================================================================
+// Array Expression Message Definitions
+// When adding a new array function, add the message definition here.
+// =============================================================================
+
 message ArrayLengthExpr {
   LogicalExpr expr = 1;
 }
 
+message ArrayDistinctExpr {
+  LogicalExpr expr = 1;
+}
+
 message ArrayContainsExpr {
   LogicalExpr expr = 1;
   LogicalExpr other = 2;
 }
 
+message ArrayMaxExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArrayMinExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArraySortExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArrayReverseExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArrayRemoveExpr {
+  LogicalExpr expr = 1;
+  LogicalExpr element = 2;
+}
+
+message ArrayUnionExpr {
+  LogicalExpr left = 1;
+  LogicalExpr right = 2;
+}
+
+message ArrayIntersectExpr {
+  LogicalExpr left = 1;
+  LogicalExpr right = 2;
+}
+
+message ArrayExceptExpr {
+  LogicalExpr left = 1;
+  LogicalExpr right = 2;
+}
+
+message ArrayCompactExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArrayRepeatExpr {
+  LogicalExpr element = 1;
+  LogicalExpr count = 2;
+}
+
+message FlattenExpr {
+  LogicalExpr expr = 1;
+}
+
+message ArraySliceExpr {
+  LogicalExpr expr = 1;
+  LogicalExpr start = 2;
+  LogicalExpr length = 3;
+}
+
+message ElementAtExpr {
+  LogicalExpr expr = 1;
+  LogicalExpr index = 2;
+}
+
+message ArraysOverlapExpr {
+  LogicalExpr left = 1;
+  LogicalExpr right = 2;
+}
+
 // Binary expressions
 message ArithmeticExpr {
   LogicalExpr left = 1;