feat(zynml): add stdlib traits, extern calls, and type system foundations

Grammar additions:
- Add trait definitions with generics and associated types
- Add impl blocks with trait arguments and associated type impls
- Add type definitions (@opaque for ZRTL-backed types, type aliases)
- Add generic type parameters with bounds (T: Display + Clone)
- Add extern call syntax for invoking ZRTL builtins

Standard library foundation:
- Create stdlib/prelude.zynml with core traits:
  - Display, Debug (formatting)
  - Add, Sub, Mul, Div, Mod, MatMul, Neg (arithmetic operators)
  - Eq, Ord (comparison operators)
  - BitAnd, BitOr, BitXor, Not (bitwise operators)
  - Index, IndexMut (indexing)
  - Clone, Drop (lifecycle)
  - Iterator, IntoIterator (iteration)
- Create stdlib/tensor.zynml with Tensor module:
  - @opaque("$Tensor") type backed by zrtl_tensor plugin
  - Display impl using extern tensor_to_string
  - Operator trait impls (Add, Sub, Mul, Div, MatMul, Neg)
  - Clone and Drop trait impls
  - Tensor creation functions (from_array, zeros, ones, etc.)
  - @method functions for tensor operations

ZRTL plugin updates:
- Add tensor_to_string, tensor_clone, tensor_free builtins
- Add operator builtins (tensor_add, tensor_sub, tensor_mul, etc.)
- Enhance IO plugin with type-aware printing infrastructure

Compiler updates:
- Fix function definition parsing with optional parameters
- Split fn_def into explicit variants to avoid index shifting
- Add extern call resolution through @Builtin mappings

Author: darmie

book/05-semantic-actions.md

@@ -443,6 +443,231 @@ typed_var_decl = { "const" ~ identifier ~ ":" ~ type_expr ~ "=" ~ expr ~ ";" }
   }
 ```
 
+## The `fold_left_ops` Command
+
+This command handles left-associative binary expressions where operators are interleaved with operands in the child list.
+
+### Difference from `fold_binary`
+
+While `fold_binary` expects named rules for operands and operators, `fold_left_ops` works with children in a flat pattern: `[operand, operator, operand, operator, operand, ...]`
+
+### Usage
+
+```zyn
+// Multiplication with operators in child list
+multiplicative_expr = { unary_expr ~ (multiplicative_op ~ unary_expr)* }
+  -> TypedExpression {
+      "get_all_children": true,
+      "fold_left_ops": true
+  }
+
+multiplicative_op = { "*" | "/" | "%" }
+  -> String {
+      "get_text": true
+  }
+```
+
+### How It Works
+
+For input `2 * 3 / 4`:
+
+1. Parse produces: `[unary(2), "*", unary(3), "/", unary(4)]`
+2. Start with first operand: `result = 2`
+3. Process pairs: `result = binary(*, result, 3)` → `(2 * 3)`
+4. Continue: `result = binary(/, result, 4)` → `((2 * 3) / 4)`
+
+### Important Notes
+
+- Requires `get_all_children: true` before `fold_left_ops`
+- Operators should be extracted as strings (use `get_text: true`)
+- Automatically unwraps nested single-element lists
+
+## The `apply_unary` Command
+
+This command handles optional unary prefix operators.
+
+### Problem It Solves
+
+When parsing unary expressions like `-x` or `!flag`, the unary operator is optional:
+- `-42` has a unary prefix
+- `42` has no unary prefix
+
+Without `apply_unary`, you'd need to split into separate rules.
+
+### Usage
+
+```zyn
+// Unary operators: -, !
+unary_expr = { unary_op? ~ postfix_expr }
+  -> TypedExpression {
+      "get_all_children": true,
+      "apply_unary": true
+  }
+
+unary_op = { "-" | "!" }
+  -> String {
+      "get_text": true
+  }
+```
+
+### How It Works
+
+1. Collects all children: `[operator?, operand]`
+2. If operator present: creates `unary(op, operand)`
+3. If no operator: passes through the operand unchanged
+4. Unwraps nested single-element lists from expression cascading
+
+## The `fold_left` Command
+
+This command provides custom left-folding behavior for special operators like the pipe operator.
+
+### Usage
+
+```zyn
+// Pipe operator: x |> f(args) |> g()
+// Transforms: a |> f(b) into f(a, b)
+pipe_expr = { or_expr ~ ("|>" ~ pipe_call)* }
+  -> TypedExpression {
+      "get_all_children": true,
+      "fold_left": {
+          "op": "pipe",
+          "transform": "prepend_arg"
+      }
+  }
+
+pipe_call = { identifier ~ "(" ~ call_args? ~ ")" }
+  -> TypedExpression {
+      "commands": [
+          { "define": "pipe_target", "args": {
+              "callee": { "define": "variable", "args": { "name": "$1" } },
+              "args": "$2"
+          }}
+      ]
+  }
+```
+
+### Parameters
+
+- `op`: The operator name ("pipe", "||", "&&", etc.)
+- `transform` (optional): Special transformation to apply
+  - `"prepend_arg"`: For pipe operator, prepends left-hand side to function args
+
+### How It Works for Pipe Operator
+
+For input `data |> filter(pred) |> map(fn)`:
+
+1. Parse produces: `[data, pipe_call(filter, [pred]), pipe_call(map, [fn])]`
+2. Start with `result = data`
+3. Transform: `filter(result, pred)` (prepends result to args)
+4. Transform: `map(result2, fn)` (prepends to args)
+
+Result is equivalent to: `map(filter(data, pred), fn)`
+
+### Logical Operators
+
+For simple left-folding (like `||` and `&&`):
+
+```zyn
+or_expr = { and_expr ~ ("||" ~ and_expr)* }
+  -> TypedExpression {
+      "get_all_children": true,
+      "fold_left": { "op": "||" }
+  }
+```
+
+## The `fold_postfix` Command
+
+This command handles postfix operations like function calls, array indexing, and member access.
+
+### Problem It Solves
+
+Postfix expressions chain operations: `obj.field[0](arg)` needs to fold left-to-right into nested AST nodes.
+
+### Usage
+
+```zyn
+// Postfix: function calls, indexing, member access
+postfix_expr = { primary_expr ~ postfix_op* }
+  -> TypedExpression {
+      "get_all_children": true,
+      "fold_postfix": true
+  }
+
+postfix_op = { call_op | index_op | member_op }
+  -> TypedExpression {
+      "get_child": { "index": 0 }
+  }
+
+// Function call: f(args)
+call_op = { "(" ~ call_args? ~ ")" }
+  -> TypedExpression {
+      "get_child": { "index": 0 },
+      "define": "call_args",
+      "args": { "args": "$result" }
+  }
+
+// Indexing: x[i]
+index_op = { "[" ~ expr ~ "]" }
+  -> TypedExpression {
+      "define": "index",
+      "args": { "index": "$1" }
+  }
+
+// Member access: x.field
+member_op = { "." ~ identifier }
+  -> TypedExpression {
+      "define": "member",
+      "args": { "field": "$1" }
+  }
+```
+
+### How It Works
+
+For input `arr[0].length`:
+
+1. Parse produces: `[primary(arr), index_op(0), member_op(length)]`
+2. Start with `result = arr`
+3. Apply index: `result = index(result, 0)`
+4. Apply member: `result = field_access(result, "length")`
+
+### Postfix Operation Types
+
+Each postfix operation is wrapped with a marker so `fold_postfix` knows how to apply it:
+
+| Marker | Creates |
+|--------|---------|
+| `call_args` | Function call with args |
+| `index` | Array/map index access |
+| `member` | Field/property access |
+
+## Type Inference Markers
+
+When defining variables in dynamically-typed or type-inferred languages, use these special type markers:
+
+### The `infer_type` Define
+
+```zyn
+let_stmt = { "let" ~ identifier ~ "=" ~ expr }
+  -> TypedStatement {
+      "commands": [
+          { "define": "let_stmt", "args": {
+              "name": "$1",
+              "type": { "define": "infer_type" },
+              "init": "$2",
+              "is_const": false
+          }}
+      ]
+  }
+```
+
+The `infer_type` define returns a special null marker indicating the type should be inferred from the initializer expression by the type checker.
+
+### Aliases
+
+These aliases also work for type inference:
+- `"define": "auto"` - C++ style auto type
+- `"define": "var"` - TypeScript/C# style var
+
 ## Handling Optional Children
 
 When a child might be absent, the builder handles null/missing gracefully:

crates/compiler/src/llvm_backend.rs

@@ -74,6 +74,9 @@ pub struct LLVMBackend<'ctx> {
 
     /// Maps HIR global IDs to compiled LLVM global values (persists across functions)
     globals_map: IndexMap<HirId, BasicValueEnum<'ctx>>,
+
+    /// Symbol signatures for auto-boxing (symbol name → signature)
+    symbol_signatures: std::collections::HashMap<String, crate::zrtl::ZrtlSymbolSig>,
 }
 
 impl<'ctx> LLVMBackend<'ctx> {
@@ -97,9 +100,27 @@ impl<'ctx> LLVMBackend<'ctx> {
             phi_map: IndexMap::new(),
             current_function: None,
             globals_map: IndexMap::new(),
+            symbol_signatures: std::collections::HashMap::new(),
+        }
+    }
+
+    /// Register symbol signatures for auto-boxing support
+    pub fn register_symbol_signatures(&mut self, symbols: &[crate::zrtl::RuntimeSymbolInfo]) {
+        for sym in symbols {
+            if let Some(sig) = &sym.sig {
+                self.symbol_signatures.insert(sym.name.to_string(), sig.clone());
+            }
         }
     }
 
+    /// Check if a symbol parameter expects DynamicBox
+    fn param_needs_boxing(&self, symbol_name: &str, param_index: usize) -> bool {
+        self.symbol_signatures
+            .get(symbol_name)
+            .map(|sig| sig.param_is_dynamic(param_index))
+            .unwrap_or(false)
+    }
+
     /// Compile an entire HIR module to LLVM IR
     ///
     /// This is the main entry point for compilation. It:
@@ -2230,17 +2251,68 @@ impl<'ctx> LLVMBackend<'ctx> {
             }
             HirCallable::Symbol(symbol_name) => {
                 // Call external runtime symbol by name (e.g., "$haxe$trace$int")
+                // Check if any parameters need auto-boxing based on symbol signature
+                let sig_info = self.symbol_signatures.get(symbol_name).cloned();
+
                 // Compile arguments first to infer their types
-                let arg_values: Vec<BasicMetadataValueEnum> = args
+                let raw_arg_values: Vec<BasicValueEnum> = args
                     .iter()
-                    .map(|arg_id| {
-                        self.get_value(*arg_id)
-                            .map(|v| v.into())
-                    })
+                    .map(|arg_id| self.get_value(*arg_id))
                     .collect::<CompilerResult<Vec<_>>>()?;
 
-                // Infer parameter types from argument values
-                let param_types: Vec<BasicMetadataTypeEnum> = arg_values
+                // Process arguments - box if needed
+                let final_arg_values: Vec<BasicMetadataValueEnum> = if let Some(ref sig) = sig_info {
+                    raw_arg_values.iter().enumerate().map(|(i, &arg_val)| {
+                        if sig.param_is_dynamic(i) {
+                            // This argument needs to be boxed as DynamicBox
+                            // Determine which boxing function to call based on type
+                            let func_name = if arg_val.is_int_value() {
+                                let int_ty = arg_val.into_int_value().get_type();
+                                if int_ty == self.context.i32_type() {
+                                    "zyntax_box_i32"
+                                } else if int_ty == self.context.i64_type() {
+                                    "zyntax_box_i64"
+                                } else if int_ty == self.context.i8_type() {
+                                    "zyntax_box_bool"
+                                } else {
+                                    "zyntax_box_i64"
+                                }
+                            } else if arg_val.is_float_value() {
+                                let float_ty = arg_val.into_float_value().get_type();
+                                if float_ty == self.context.f32_type() {
+                                    "zyntax_box_f32"
+                                } else {
+                                    "zyntax_box_f64"
+                                }
+                            } else {
+                                // Pointers and other types
+                                "zyntax_box_ptr"
+                            };
+
+                            // Declare and call boxing function
+                            let box_fn_type = self.context.i64_type().fn_type(
+                                &[arg_val.get_type().into()],
+                                false
+                            );
+                            let box_fn = self.module.get_function(func_name).unwrap_or_else(|| {
+                                self.module.add_function(func_name, box_fn_type, None)
+                            });
+
+                            if let Ok(call_site) = self.builder.build_call(box_fn, &[arg_val.into()], "box") {
+                                call_site.try_as_basic_value().left().unwrap_or(arg_val).into()
+                            } else {
+                                arg_val.into()
+                            }
+                        } else {
+                            arg_val.into()
+                        }
+                    }).collect()
+                } else {
+                    raw_arg_values.iter().map(|&v| v.into()).collect()
+                };
+
+                // Infer parameter types from (potentially boxed) argument values
+                let param_types: Vec<BasicMetadataTypeEnum> = final_arg_values
                     .iter()
                     .map(|v| match v {
                         BasicMetadataValueEnum::IntValue(i) => i.get_type().into(),
@@ -2260,7 +2332,7 @@ impl<'ctx> LLVMBackend<'ctx> {
                 });
 
                 // Build call
-                self.builder.build_call(func, &arg_values, symbol_name)?;
+                self.builder.build_call(func, &final_arg_values, symbol_name)?;
 
                 // Return a dummy value (void functions don't return anything meaningful)
                 Ok(self.context.i32_type().const_zero().into())

crates/compiler/src/llvm_jit_backend.rs

@@ -50,6 +50,9 @@ pub struct LLVMJitBackend<'ctx> {
     /// Runtime symbols to register with the execution engine
     /// Maps function name to function pointer address
     runtime_symbols: IndexMap<String, usize>,
+
+    /// Symbol signatures for auto-boxing (symbol name → signature)
+    symbol_signatures: Vec<crate::zrtl::RuntimeSymbolInfo>,
 }
 
 impl<'ctx> LLVMJitBackend<'ctx> {
@@ -73,9 +76,15 @@ impl<'ctx> LLVMJitBackend<'ctx> {
             function_pointers: IndexMap::new(),
             opt_level,
             runtime_symbols: IndexMap::new(),
+            symbol_signatures: Vec::new(),
         })
     }
 
+    /// Register symbol signatures for auto-boxing support
+    pub fn register_symbol_signatures(&mut self, symbols: &[crate::zrtl::RuntimeSymbolInfo]) {
+        self.symbol_signatures.extend(symbols.iter().cloned());
+    }
+
     /// Register a runtime symbol that will be available to JIT-compiled code
     ///
     /// Call this before `compile_module` to make external functions available.
@@ -100,6 +109,10 @@ impl<'ctx> LLVMJitBackend<'ctx> {
     pub fn compile_module(&mut self, hir_module: &HirModule) -> CompilerResult<()> {
         // Step 1: Create backend and compile HIR → LLVM IR
         let mut backend = LLVMBackend::new(self.context, "zyntax_jit");
+
+        // Register symbol signatures for auto-boxing
+        backend.register_symbol_signatures(&self.symbol_signatures);
+
         let _llvm_ir = backend.compile_module(hir_module)?;
 
         // Step 2: Collect external function declarations from the module BEFORE consuming it