kumi 0.0.9 → 0.0.11

data/lib/kumi/core/explain.rb

@@ -4,291 +4,243 @@ module Kumi
   module Core
     module Explain
       class ExplanationGenerator
-        def initialize(syntax_tree, analyzer_result, inputs)
-          @analyzer_result = analyzer_result
-          @inputs = EvaluationWrapper.new(inputs)
-          @definitions = analyzer_result.definitions
-          @compiled_schema = Compiler.compile(syntax_tree, analyzer: analyzer_result)
+        def initialize(syntax_tree, analysis_state, inputs, registry: Kumi::Registry)
+          @syntax_tree = syntax_tree
+          @state       = analysis_state
+          @inputs      = inputs
+          @definitions = analysis_state[:declarations] || {}
+          @registry    = registry
 
-          # TODO: REFACTOR QUICK!
-          # Set up compiler once for expression evaluation
-          @compiler = Compiler.new(syntax_tree, analyzer_result)
-          @compiler.send(:build_index)
-
-          # Populate bindings from the compiled schema
-          @compiled_schema.bindings.each do |name, (type, fn)|
-            @compiler.instance_variable_get(:@bindings)[name] = [type, fn]
-          end
+          @program = Kumi::Runtime::Executable.from_analysis(@state, registry: nil)
+          @session = @program.read(@inputs, mode: :ruby)
         end
 
         def explain(target_name)
-          declaration = @definitions[target_name]
-          raise ArgumentError, "Unknown declaration: #{target_name}" unless declaration
-
-          expression = declaration.expression
-          result_value = @compiled_schema.evaluate_binding(target_name, @inputs)
+          decl = @definitions[target_name] or raise ArgumentError, "Unknown declaration: #{target_name}"
+          expr = decl.expression
+          value = @session.get(target_name)
 
           prefix = "#{target_name} = "
-          expression_str = format_expression(expression, indent_context: prefix.length)
+          expr_str = format_expression(expr, indent_context: prefix.length)
 
-          "#{prefix}#{expression_str} => #{format_value(result_value)}"
+          "#{prefix}#{expr_str} => #{format_value(value)}"
         end
 
         private
 
+        # ---------- formatting ----------
+
         def format_expression(expr, indent_context: 0, nested: false)
           case expr
           when Kumi::Syntax::InputReference
             "input.#{expr.name}"
+          when Kumi::Syntax::InputElementReference
+            "input.#{expr.path.join('.')}"
           when Kumi::Syntax::DeclarationReference
             expr.name.to_s
           when Kumi::Syntax::Literal
             format_value(expr.value)
-          when Kumi::Syntax::CallExpression
-            format_call_expression(expr, indent_context: indent_context, nested: nested)
           when Kumi::Syntax::ArrayExpression
-            "[#{expr.elements.map { |e| format_expression(e, indent_context: indent_context, nested: nested) }.join(', ')}]"
+            "[" + expr.elements.map { |e| format_expression(e, indent_context:, nested:) }.join(", ") + "]"
           when Kumi::Syntax::CascadeExpression
-            format_cascade_expression(expr, indent_context: indent_context)
+            format_cascade(expr, indent_context:)
+          when Kumi::Syntax::CallExpression
+            format_call(expr, indent_context:, nested:)
           else
             expr.class.name.split("::").last
           end
         end
 
-        def format_call_expression(expr, indent_context: 0, nested: false)
-          if pretty_printable?(expr.fn_name)
-            format_pretty_function(expr, expr.fn_name, indent_context, nested: nested)
+        def format_call(expr, indent_context:, nested:)
+          fn = expr.fn_name
+          if pretty_print?(fn)
+            format_pretty(expr, fn, indent_context:, nested:)
           else
-            format_generic_function(expr, indent_context)
+            format_generic(expr, indent_context:)
           end
         end
 
-        def format_pretty_function(expr, fn_name, _indent_context, nested: false)
-          if needs_evaluation?(expr.args) && !nested
-            # For top-level expressions, show the flattened symbolic form and evaluation
-            if chain_of_same_operator?(expr, fn_name)
-              # For chains like a + b + c, flatten to show all operands
-              all_operands = flatten_operator_chain(expr, fn_name)
-              symbolic_operands = all_operands.map { |op| format_expression(op, indent_context: 0, nested: true) }
-              symbolic_format = symbolic_operands.join(" #{get_operator_symbol(fn_name)} ")
-
-              evaluated_operands = all_operands.map do |op|
-                if op.is_a?(Kumi::Syntax::Literal)
-                  format_expression(op, indent_context: 0, nested: true)
-                else
-                  arg_value = format_value(evaluate_expression(op))
-                  if op.is_a?(Kumi::Syntax::DeclarationReference) && all_operands.length > 1
-                    "(#{format_expression(op, indent_context: 0, nested: true)} = #{arg_value})"
-                  else
-                    arg_value
-                  end
-                end
-              end
-              evaluated_format = evaluated_operands.join(" #{get_operator_symbol(fn_name)} ")
+        def pretty_print?(fn)
+          %i[add subtract multiply divide == != > < >= <= and or not].include?(fn)
+        end
 
+        def format_pretty(expr, fn, indent_context:, nested:)
+          if needs_eval?(expr.args) && !nested
+            if chain_of_same_op?(expr, fn)
+              ops = flatten_chain(expr, fn)
+              sym = op_symbol(fn)
+              sym_args = ops.map { |a| format_expression(a, indent_context:, nested: true) }
+              eval_args = ops.map { |a| eval_arg_for_display(a) }
+              "#{sym_args.join(" #{sym} ")} = #{eval_args.join(" #{sym} ")}"
             else
-              # Regular pretty formatting for non-chain expressions
-              symbolic_args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
-              symbolic_format = display_format(fn_name, symbolic_args)
-
-              evaluated_args = expr.args.map do |arg|
-                if arg.is_a?(Kumi::Syntax::Literal)
-                  format_expression(arg, indent_context: 0, nested: true)
-                else
-                  arg_value = format_value(evaluate_expression(arg))
-                  if arg.is_a?(Kumi::Syntax::DeclarationReference) &&
-                     expr.args.count { |a| !a.is_a?(Kumi::Syntax::Literal) } > 1
-                    "(#{format_expression(arg, indent_context: 0, nested: true)} = #{arg_value})"
-                  else
-                    arg_value
-                  end
-                end
-              end
-              evaluated_format = display_format(fn_name, evaluated_args)
-
+              sym_args = expr.args.map { |a| format_expression(a, indent_context:, nested: true) }
+              eval_args = expr.args.map { |a| eval_arg_for_display(a) }
+              display_fmt(fn, sym_args) + " = " + display_fmt(fn, eval_args)
             end
-            "#{symbolic_format} = #{evaluated_format}"
           else
-            # For nested expressions, just show the symbolic form without evaluation details
-            args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
-            display_format(fn_name, args)
+            display_fmt(fn, expr.args.map { |a| format_expression(a, indent_context:, nested: true) })
           end
         end
 
-        def chain_of_same_operator?(expr, fn_name)
-          return false unless %i[add subtract multiply divide].include?(fn_name)
-
-          # Check if any argument is the same operator
-          expr.args.any? do |arg|
-            arg.is_a?(Kumi::Syntax::CallExpression) && arg.fn_name == fn_name
+        def format_generic(expr, indent_context:)
+          parts = expr.args.map do |a|
+            desc = format_expression(a, indent_context:)
+            if literalish?(a)
+              desc
+            else
+              val = evaluate(a)
+              "#{desc} = #{format_value(val)}"
+            end
+          end
+          if parts.length > 1
+            indent = " " * (indent_context + expr.fn_name.to_s.length + 1)
+            "#{expr.fn_name}(#{parts.join(",\n#{indent}")})"
+          else
+            "#{expr.fn_name}(#{parts.join(', ')})"
           end
         end
 
-        def flatten_operator_chain(expr, operator)
-          operands = []
-
-          expr.args.each do |arg|
-            if arg.is_a?(Kumi::Syntax::CallExpression) && arg.fn_name == operator
-              # Recursively flatten nested operations of the same type
-              operands.concat(flatten_operator_chain(arg, operator))
-            else
-              operands << arg
-            end
+        def format_cascade(expr, indent_context:)
+          lines = []
+          expr.cases.each do |c|
+            cond_val = evaluate(c.condition)
+            cond_desc = format_expression(c.condition, indent_context:)
+            res_desc  = format_expression(c.result, indent_context:)
+            lines << "  #{cond_val ? '✓' : '✗'} on #{cond_desc}, #{res_desc}"
+            break if cond_val
           end
+          "\n" + lines.join("\n")
+        end
 
-          operands
+        def literalish?(expr)
+          expr.is_a?(Kumi::Syntax::Literal) ||
+            (expr.is_a?(Kumi::Syntax::ArrayExpression) && expr.elements.all?(Kumi::Syntax::Literal))
         end
 
-        def get_operator_symbol(fn_name)
-          case fn_name
-          when :add then "+"
-          when :subtract then "-"
-          when :multiply then "×"
-          when :divide then "÷"
-          else fn_name.to_s
-          end
+        def needs_eval?(args)
+          args.any? { |a| !literalish?(a) }
+        end
+
+        def chain_of_same_op?(expr, fn) = expr.args.any? { |a| a.is_a?(Kumi::Syntax::CallExpression) && a.fn_name == fn }
+        def flatten_chain(expr, fn)
+          expr.args.flat_map { |a|
+            a.is_a?(Kumi::Syntax::CallExpression) && a.fn_name == fn ? flatten_chain(a, fn) : [a]
+          }
         end
 
-        def pretty_printable?(fn_name)
-          %i[add subtract multiply divide == != > < >= <= and or not].include?(fn_name)
+        def op_symbol(fn)
+          { add: "+", subtract: "-", multiply: "×", divide: "÷" }[fn] || fn.to_s
         end
 
-        def display_format(fn_name, args)
-          case fn_name
-          when :add then args.join(" + ")
+        def display_fmt(fn, args)
+          case fn
+          when :add      then args.join(" + ")
           when :subtract then args.join(" - ")
           when :multiply then args.join(" × ")
-          when :divide then args.join(" ÷ ")
-          when :== then "#{args[0]} == #{args[1]}"
-          when :!= then "#{args[0]} != #{args[1]}"
-          when :> then "#{args[0]} > #{args[1]}"
-          when :< then "#{args[0]} < #{args[1]}"
-          when :>= then "#{args[0]} >= #{args[1]}"
-          when :<= then "#{args[0]} <= #{args[1]}"
-          when :and then args.join(" && ")
-          when :or then args.join(" || ")
-          when :not then "!#{args[0]}"
-          else "#{fn_name}(#{args.join(', ')})"
+          when :divide   then args.join(" ÷ ")
+          when :==       then "#{args[0]} == #{args[1]}"
+          when :!=       then "#{args[0]} != #{args[1]}"
+          when :>        then "#{args[0]} > #{args[1]}"
+          when :<        then "#{args[0]} < #{args[1]}"
+          when :>=       then "#{args[0]} >= #{args[1]}"
+          when :<=       then "#{args[0]} <= #{args[1]}"
+          when :and      then args.join(" && ")
+          when :or       then args.join(" || ")
+          when :not      then "!#{args[0]}"
+          else                "#{fn}(#{args.join(', ')})"
           end
         end
 
-        def format_generic_function(expr, indent_context)
-          args = expr.args.map do |arg|
-            arg_desc = format_expression(arg, indent_context: indent_context)
-
-            # For literals and literal lists, just show the value, no need for "100 = 100"
-            if arg.is_a?(Kumi::Syntax::Literal) ||
-               (arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.all?(Kumi::Syntax::Literal))
-              arg_desc
-            else
-              arg_value = evaluate_expression(arg)
-              "#{arg_desc} = #{format_value(arg_value)}"
-            end
-          end
-
-          if args.length > 1
-            # Align with opening parenthesis, accounting for the full context
-            function_indent = indent_context + expr.fn_name.to_s.length + 1
-            indent = " " * function_indent
-            "#{expr.fn_name}(#{args.join(",\n#{indent}")})"
+        def eval_arg_for_display(arg)
+          return format_expression(arg, indent_context: 0, nested: true) if literalish?(arg)
+          val = evaluate(arg)
+          if arg.is_a?(Kumi::Syntax::DeclarationReference)
+            "(#{format_expression(arg, indent_context: 0, nested: true)} = #{format_value(val)})"
           else
-            "#{expr.fn_name}(#{args.join(', ')})"
+            format_value(val)
           end
         end
 
-        def needs_evaluation?(args)
-          args.any? do |arg|
-            !arg.is_a?(Kumi::Syntax::Literal) &&
-              !(arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.all?(Kumi::Syntax::Literal))
+        def format_value(v)
+          case v
+          when Float, Integer then format_number(v)
+          when String         then "\"#{v}\""
+          when Array          then v.length <= 4 ? "[#{v.map { |x| format_value(x) }.join(', ')}]" :
+                                                  "[#{v.take(4).map { |x| format_value(x) }.join(', ')}, …]"
+          else v.to_s
           end
         end
 
-        def format_cascade_expression(expr, indent_context: 0)
-          lines = []
-          expr.cases.each do |case_expr|
-            condition_result = evaluate_expression(case_expr.condition)
-            condition_desc = format_expression(case_expr.condition, indent_context: indent_context)
-            result_desc = format_expression(case_expr.result, indent_context: indent_context)
+        def format_number(n)
+          return n.to_s unless n.is_a?(Numeric)
+          i = (n.is_a?(Integer) || n == n.to_i) ? n.to_i : nil
+          return n.to_s unless i
+          i.abs >= 1000 ? i.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1 ').reverse : i.to_s
+        end
 
-            status = condition_result ? "✓" : "✗"
-            lines << "  #{status} on #{condition_desc}, #{result_desc}"
+        # ---------- evaluation (Program + Registry) ----------
 
-            break if condition_result
+        def evaluate(expr)
+          case expr
+          when Kumi::Syntax::DeclarationReference
+            @session.get(expr.name)
+          when Kumi::Syntax::InputReference
+            fetch_indifferent(@inputs, expr.name)
+          when Kumi::Syntax::InputElementReference
+            dig_path(@inputs, expr.path)
+          when Kumi::Syntax::Literal
+            expr.value
+          when Kumi::Syntax::ArrayExpression
+            expr.elements.map { |e| evaluate(e) }
+          when Kumi::Syntax::CascadeExpression
+            evaluate_cascade(expr)
+          when Kumi::Syntax::CallExpression
+            eval_call(expr)
+          else
+            raise "Unsupported expression: #{expr.class}"
           end
+        end
 
-          "\n#{lines.join("\n")}"
+        def eval_call(expr)
+          entry = @registry.entry(expr.fn_name) or raise "Unknown function: #{expr.fn_name}"
+          fn = entry.fn
+          args = expr.args.map { |a| evaluate(a) }
+          fn.call(*args)
         end
 
-        def format_value(value)
-          case value
-          when Float, Integer
-            format_number(value)
-          when String
-            "\"#{value}\""
-          when Array
-            if value.length <= 4
-              "[#{value.map { |v| format_value(v) }.join(', ')}]"
-            else
-              "[#{value.take(4).map { |v| format_value(v) }.join(', ')}, …]"
-            end
-          else
-            value.to_s
+        def evaluate_cascade(expr)
+          expr.cases.each do |c|
+            return evaluate(c.result) if evaluate(c.condition)
           end
+          nil
         end
 
-        def format_number(num)
-          return num.to_s unless num.is_a?(Numeric)
+        def fetch_indifferent(h, k)
+          h[k] || h[k.to_s] || h[k.to_sym]
+        end
 
-          if num.is_a?(Integer) || (num.is_a?(Float) && num == num.to_i)
-            int_val = num.to_i
-            if int_val.abs >= 1000
-              int_val.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1 ').reverse
+        def dig_path(h, path)
+          node = h
+          path.each do |seg|
+            if node.is_a?(Hash)
+              node = fetch_indifferent(node, seg)
             else
-              int_val.to_s
+              # if arrays are in path, interpret seg as index when Integer-like
+              node = seg.is_a?(Integer) ? node[seg] : nil
             end
-          else
-            num.to_s
-          end
-        end
-
-        def evaluate_expression(expr)
-          case expr
-          when Kumi::Syntax::DeclarationReference
-            @compiled_schema.evaluate_binding(expr.name, @inputs)
-          when Kumi::Syntax::InputReference
-            @inputs[expr.name]
-          when Kumi::Syntax::Literal
-            expr.value
-          else
-            # For complex expressions, compile and evaluate using existing compiler
-            compiled_fn = @compiler.send(:compile_expr, expr)
-            compiled_fn.call(@inputs)
           end
+          node
         end
       end
 
       module_function
 
       def call(schema_class, target_name, inputs:)
-        syntax_tree = schema_class.instance_variable_get(:@__syntax_tree__)
-        analyzer_result = schema_class.instance_variable_get(:@__analyzer_result__)
-
-        raise ArgumentError, "Schema not found or not compiled" unless syntax_tree && analyzer_result
-
-        metadata = analyzer_result.state
-
-        # Create a minimal analyzer result structure for compatibility
-        analyzer_result = OpenStruct.new(
-          definitions: metadata[:declarations] || {},
-          dependency_graph: metadata[:dependencies] || {},
-          leaf_map: metadata[:leaves] || {},
-          topo_order: metadata[:evaluation_order] || [],
-          decl_types: metadata[:inferred_types] || {},
-          state: metadata
-        )
+        syntax_tree     = schema_class.instance_variable_get(:@__syntax_tree__)
+        analysis_state  = schema_class.instance_variable_get(:@__analyzer_result__)&.state
+        raise ArgumentError, "Schema not found or not compiled" unless syntax_tree && analysis_state
 
-        generator = ExplanationGenerator.new(syntax_tree, analyzer_result, inputs)
-        generator.explain(target_name)
+        ExplanationGenerator.new(syntax_tree, analysis_state, inputs).explain(target_name)
       end
     end
   end

data/lib/kumi/core/export/node_builders.rb

@@ -6,10 +6,10 @@ module Kumi
       module NodeBuilders
         def build_root(data, node_class)
           inputs = data[:inputs].map { |input_data| build_node(input_data) }
-          attributes = data[:attributes].map { |attr_data| build_node(attr_data) }
+          values = data[:values].map { |attr_data| build_node(attr_data) }
           traits = data[:traits].map { |trait_data| build_node(trait_data) }
 
-          node_class.new(inputs, attributes, traits)
+          node_class.new(inputs, values, traits)
         end
 
         def build_field_declaration(data, node_class)

data/lib/kumi/core/export/node_serializers.rb

@@ -9,7 +9,7 @@ module Kumi
           {
             type: "root",
             inputs: node.inputs.map { |input| serialize_node(input) },
-            attributes: node.attributes.map { |attr| serialize_node(attr) },
+            values: node.values.map { |attr| serialize_node(attr) },
             traits: node.traits.map { |trait| serialize_node(trait) }
           }
         end

data/lib/kumi/core/function_registry/collection_functions.rb

@@ -8,9 +8,18 @@ module Kumi
         def self.definitions
           {
             # Collection queries (these are reducers - they reduce arrays to scalars)
-            empty?: FunctionBuilder.collection_unary(:empty?, "Check if collection is empty", :empty?, reducer: true),
-            size: FunctionBuilder.collection_unary(:size, "Get collection size", :size, return_type: :integer, reducer: true),
-            length: FunctionBuilder.collection_unary(:length, "Get collection length", :length, return_type: :integer, reducer: true),
+            empty?: FunctionBuilder.collection_unary(:empty?, "Check if collection is empty", :empty?, reducer: true,
+                                                                                                       structure_function: true),
+            size: FunctionBuilder::Entry.new(
+              fn: ->(collection) { collection.size },
+              arity: 1,
+              param_types: [:any],
+              return_type: :integer,
+              description: "Get size of collection",
+              param_modes: { fixed: [:elem] }, # take a vector argument elementwise
+              reducer: true,
+              structure_function: true
+            ),
 
             # Element access
             first: FunctionBuilder::Entry.new(
@@ -56,7 +65,8 @@ module Kumi
               param_types: [Kumi::Core::Types.array(:float)],
               return_type: :float,
               description: "Find maximum value in numeric collection",
-              reducer: true
+              reducer: true,
+              param_modes: { fixed: [:elem] } # first param is the vector being reduced
             ),
 
             # Collection operations
@@ -94,11 +104,31 @@ module Kumi
 
             # Array transformation functions
             flatten: FunctionBuilder::Entry.new(
-              fn: lambda(&:flatten),
+              fn: ->(array) { array.flatten },
               arity: 1,
               param_types: [Kumi::Core::Types.array(:any)],
               return_type: Kumi::Core::Types.array(:any),
-              description: "Flatten nested arrays into a single array"
+              description: "Flatten nested arrays into a single array",
+              structure_function: true,
+              reducer: true
+            ),
+
+            flatten_one: FunctionBuilder::Entry.new(
+              fn: ->(array) { array.flatten(1) },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: Kumi::Core::Types.array(:any),
+              description: "Flatten nested arrays by one level only",
+              structure_function: true
+            ),
+
+            to_array: FunctionBuilder::Entry.new(
+              fn: ->(vals) { vals },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: Kumi::Core::Types.array(:any),
+              description: "Collect vector rows into a Ruby array",
+              reducer: true
             ),
 
             # Mathematical transformation functions
@@ -193,6 +223,70 @@ module Kumi
               param_types: [Kumi::Core::Types.array(:any)],
               return_type: Kumi::Core::Types.array(:integer),
               description: "Generate array of indices for the collection"
+            ),
+
+            # Conditional aggregation functions
+            count_if: FunctionBuilder::Entry.new(
+              fn: ->(condition_array) { condition_array.count(true) },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:boolean)],
+              return_type: :integer,
+              description: "Count number of true values in boolean array",
+              reducer: true
+            ),
+
+            sum_if: FunctionBuilder::Entry.new(
+              fn: lambda { |value_array, condition_array|
+                value_array.zip(condition_array).sum { |value, condition| condition ? value : 0 }
+              },
+              arity: 2,
+              param_types: [Kumi::Core::Types.array(:float), Kumi::Core::Types.array(:boolean)],
+              return_type: :float,
+              description: "Sum values where corresponding condition is true",
+              reducer: true
+            ),
+
+            avg_if: FunctionBuilder::Entry.new(
+              fn: lambda { |value_array, condition_array|
+                pairs = value_array.zip(condition_array)
+                true_values = pairs.filter_map { |value, condition| value if condition }
+                return 0.0 if true_values.empty?
+
+                true_values.sum.to_f / true_values.size
+              },
+              arity: 2,
+              param_types: [Kumi::Core::Types.array(:float), Kumi::Core::Types.array(:boolean)],
+              return_type: :float,
+              description: "Average values where corresponding condition is true",
+              reducer: true
+            ),
+
+            # Flattening utilities for hierarchical data
+            any_across: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.any? },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: :boolean,
+              description: "Check if any element is truthy across all nested levels",
+              reducer: true
+            ),
+
+            all_across: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.all? },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: :boolean,
+              description: "Check if all elements are truthy across all nested levels",
+              reducer: true
+            ),
+
+            count_across: FunctionBuilder::Entry.new(
+              fn: ->(nested_array) { nested_array.flatten.size },
+              arity: 1,
+              param_types: [Kumi::Core::Types.array(:any)],
+              return_type: :integer,
+              description: "Count total elements across all nested levels",
+              reducer: true
             )
           }
         end

data/lib/kumi/core/function_registry/conditional_functions.rb

@@ -3,31 +3,41 @@
 module Kumi
   module Core
     module FunctionRegistry
-      # Conditional and control flow functions
       module ConditionalFunctions
         def self.definitions
           {
+            # a ? b : c
             conditional: FunctionBuilder::Entry.new(
               fn: ->(condition, true_value, false_value) { condition ? true_value : false_value },
               arity: 3,
               param_types: %i[boolean any any],
               return_type: :any,
+              # all three are element-wise (scalars auto-broadcast)
+              param_modes: { fixed: %i[elem elem elem] },
               description: "Ternary conditional operator"
             ),
 
+            # if(cond, then, else=nil)
             if: FunctionBuilder::Entry.new(
               fn: ->(condition, true_value, false_value = nil) { condition ? true_value : false_value },
-              arity: -1, # Variable arity (2 or 3)
+              # keep arity=3; the last arg is optional at call time
+              arity: 3,
               param_types: %i[boolean any any],
               return_type: :any,
-              description: "If-then-else conditional"
+              param_modes: { fixed: %i[elem elem elem] },
+              description: "If-then-else conditional",
+              reducer: false,
+              structure_function: false
             ),
 
+            # coalesce(a, b, c, ...)
             coalesce: FunctionBuilder::Entry.new(
               fn: ->(*values) { values.find { |v| !v.nil? } },
-              arity: -1, # Variable arity
+              arity: -1, # variadic
               param_types: [:any],
               return_type: :any,
+              # every variadic arg participates element-wise
+              param_modes: { fixed: [], variadic: :elem },
               description: "Return first non-nil value"
             )
           }