kumi 0.0.10 → 0.0.11

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

@@ -3,92 +3,179 @@
 module Kumi
   module Core
     module FunctionRegistry
-      # Utility class to reduce repetition in function definitions
       class FunctionBuilder
-        Entry = Struct.new(:fn, :arity, :param_types, :return_type, :description, :inverse, :reducer, :structure_function,
-                           keyword_init: true)
+        # Rich, defaulted function entry
+        class Entry
+          # NOTE: Keep ctor args minimal; everything else has sensible defaults.
+          attr_reader :fn, :arity, :param_types, :return_type, :description,
+                      :reducer, :structure_function, :param_modes, :param_info
 
-        def self.comparison(_name, description, operation)
+          # param_modes:  nil | ->(argc){[:elem,:scalar,...]} | {fixed: [...], variadic: :elem|:scalar}
+          # param_info:   nil | ->(argc){[specs]} | {fixed: [...], variadic: {…}}
+          #   where a spec is: { name:, type:, mode:, required:, default:, doc: }
+          def initialize(
+            fn:,
+            arity: nil,                 # Integer (>=0) or -1 / nil for variadic
+            param_types: nil,           # defaults to [:any] * arity (when fixed)
+            return_type: :any,
+            description: "",
+            reducer: false,
+            structure_function: false,
+            param_modes: nil,
+            param_info: nil
+          )
+            @fn                 = fn
+            @arity              = arity
+            @param_types        = param_types || default_param_types(arity)
+            @return_type        = return_type
+            @description        = description
+            @reducer            = !!reducer
+            @structure_function = !!structure_function
+            @param_modes        = normalize_param_modes(param_modes, arity)
+            @param_info         = normalize_param_info(param_info, arity, @param_types)
+          end
+
+          # Concrete modes for a call site
+          def param_modes_for(argc)
+            pm = @param_modes
+            return pm.call(argc) if pm.respond_to?(:call)
+
+            fixed = Array(pm[:fixed] || [])
+            return fixed.first(argc) if argc <= fixed.size
+
+            fixed + Array.new(argc - fixed.size, pm.fetch(:variadic, :elem))
+          end
+
+          # Concrete param specs for a call site
+          # → [{name:, type:, mode:, required:, default:, doc:}, ...]
+          def param_specs_for(argc)
+            base = if @param_info.respond_to?(:call)
+                     @param_info.call(argc)
+                   else
+                     fixed = Array(@param_info[:fixed] || [])
+                     if argc <= fixed.size
+                       fixed.first(argc)
+                     else
+                       fixed + Array.new(argc - fixed.size, @param_info.fetch(:variadic, {}))
+                     end
+                   end
+
+            modes = param_modes_for(argc)
+            types = expand_types_for(argc)
+
+            base.each_with_index.map do |spec, i|
+              {
+                name: spec[:name]     || auto_name(i),
+                type: spec[:type]     || types[i] || :any,
+                mode: spec[:mode]     || modes[i] || :elem,
+                required: spec.key?(:required) ? spec[:required] : true,
+                default: spec[:default],
+                doc: spec[:doc] || ""
+              }
+            end
+          end
+
+          private
+
+          def default_param_types(arity)
+            if arity.is_a?(Integer) && arity >= 0
+              Array.new(arity, :any)
+            else
+              [] # variadic → types resolved per call
+            end
+          end
+
+          def expand_types_for(argc)
+            if @param_types.nil? || @param_types.empty?
+              Array.new(argc, :any)
+            elsif @param_types.length >= argc
+              @param_types.first(argc)
+            else
+              @param_types + Array.new(argc - @param_types.length, @param_types.last || :any)
+            end
+          end
+
+          def normalize_param_modes(pm, arity)
+            return pm if pm
+
+            # Default: everything element-wise/broadcastable
+            ->(argc) { Array.new(argc, :elem) }
+          end
+
+          def normalize_param_info(info, arity, types)
+            return info if info
+
+            # Default: synthesize from types/modes at call time
+            ->(argc) { Array.new(argc) { {} } }
+          end
+
+          def auto_name(i) = :"arg#{i + 1}"
+        end
+
+        # ===== Helper constructors (unchanged usage; now benefit from defaults) =====
+
+        def self.comparison(_name, description, op)
           Entry.new(
-            fn: ->(a, b) { a.public_send(operation, b) },
-            arity: 2,
-            param_types: %i[float float],
-            return_type: :boolean,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[float float],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.equality(_name, description, operation)
+        def self.equality(_name, description, op)
           Entry.new(
-            fn: ->(a, b) { a.public_send(operation, b) },
-            arity: 2,
-            param_types: %i[any any],
-            return_type: :boolean,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[any any],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.math_binary(_name, description, operation, return_type: :float)
+        def self.math_binary(_name, description, op, return_type: :float)
           Entry.new(
-            fn: lambda { |a, b|
-              a.public_send(operation, b)
-            },
-            arity: 2,
-            param_types: %i[float float],
-            return_type: return_type,
-            description: description
+            fn: ->(a, b) { a.public_send(op, b) },
+            arity: 2, param_types: %i[float float],
+            return_type: return_type, description: description
           )
         end
 
-        def self.math_unary(_name, description, operation, return_type: :float)
+        def self.math_unary(_name, description, op, return_type: :float)
           Entry.new(
-            fn: proc(&operation),
-            arity: 1,
-            param_types: [:float],
-            return_type: return_type,
-            description: description
+            fn: proc(&op),
+            arity: 1, param_types: [:float],
+            return_type: return_type, description: description
           )
         end
 
-        def self.string_unary(_name, description, operation)
+        def self.string_unary(_name, description, op)
           Entry.new(
-            fn: ->(str) { str.to_s.public_send(operation) },
-            arity: 1,
-            param_types: [:string],
-            return_type: :string,
-            description: description
+            fn: ->(s) { s.to_s.public_send(op) },
+            arity: 1, param_types: [:string],
+            return_type: :string, description: description
           )
         end
 
-        def self.string_binary(_name, description, operation, return_type: :string)
+        def self.string_binary(_name, description, op, return_type: :string)
           Entry.new(
-            fn: ->(str, arg) { str.to_s.public_send(operation, arg.to_s) },
-            arity: 2,
-            param_types: %i[string string],
-            return_type: return_type,
-            description: description
+            fn: ->(s, x) { s.to_s.public_send(op, x.to_s) },
+            arity: 2, param_types: %i[string string],
+            return_type: return_type, description: description
           )
         end
 
-        def self.logical_variadic(_name, description, operation)
+        def self.logical_variadic(_name, description, op)
           Entry.new(
-            fn: ->(conditions) { conditions.public_send(operation) },
-            arity: -1,
-            param_types: [:boolean],
-            return_type: :boolean,
-            description: description
+            fn: ->(*conds) { conds.flatten.public_send(op) },
+            arity: -1, param_types: [:boolean],
+            return_type: :boolean, description: description
           )
         end
 
-        def self.collection_unary(_name, description, operation, return_type: :boolean, reducer: false, structure_function: false)
+        def self.collection_unary(_name, description, op, return_type: :boolean, reducer: false, structure_function: false)
           Entry.new(
-            fn: proc(&operation),
-            arity: 1,
-            param_types: [Kumi::Core::Types.array(:any)],
-            return_type: return_type,
-            description: description,
-            reducer: reducer,
-            structure_function: structure_function
+            fn: proc(&op),
+            arity: 1, param_types: [Kumi::Core::Types.array(:any)],
+            return_type: return_type, description: description,
+            reducer: reducer, structure_function: structure_function
           )
         end
       end

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

@@ -173,9 +173,9 @@ module Kumi
             ),
 
             # Collection logical operations
-            all?: FunctionBuilder.collection_unary(:all?, "Check if all elements in collection are truthy", :all?),
-            any?: FunctionBuilder.collection_unary(:any?, "Check if any element in collection is truthy", :any?),
-            none?: FunctionBuilder.collection_unary(:none?, "Check if no elements in collection are truthy", :none?),
+            all?: FunctionBuilder.collection_unary(:all?, "Check if all elements in collection are truthy", :all?, reducer: true),
+            any?: FunctionBuilder.collection_unary(:any?, "Check if any element in collection is truthy", :any?, reducer: true),
+            none?: FunctionBuilder.collection_unary(:none?, "Check if no elements in collection are truthy", :none?, reducer: true),
 
             # Element-wise AND for cascades - works on arrays with same structure
             cascade_and: FunctionBuilder::Entry.new(
@@ -188,9 +188,9 @@ module Kumi
                 end
 
                 return false if conditions.empty?
-                return conditions.first if conditions.length == 1
 
-                # Element-wise AND for arrays with same nested structure
+                # Always process uniformly, even for single conditions
+                # This ensures DeclarationReferences are evaluated properly
                 result = conditions.first
                 conditions[1..].each_with_index do |condition, i|
                   puts "  Combining result with condition[#{i + 1}]" if ENV["DEBUG_CASCADE"]

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

@@ -8,7 +8,7 @@ module Kumi
           {
             # Statistical Functions
             avg: FunctionBuilder::Entry.new(
-              fn: ->(array) { array.sum.to_f / array.size },
+              fn: ->(array) { array.empty? ? nil : array.sum.to_f / array.size },
               arity: 1,
               param_types: [Kumi::Core::Types.array(:float)],
               return_type: :float,
@@ -17,7 +17,7 @@ module Kumi
             ),
 
             mean: FunctionBuilder::Entry.new(
-              fn: ->(array) { array.sum.to_f / array.size },
+              fn: ->(array) { array.empty? ? nil : array.sum.to_f / array.size },
               arity: 1,
               param_types: [Kumi::Core::Types.array(:float)],
               return_type: :float,

data/lib/kumi/core/function_registry.rb

@@ -2,18 +2,15 @@
 
 module Kumi
   module Core
-    # Internal function registry implementation
-    # Use Kumi::Registry for the public interface to register custom functions
+    # Internal function registry (single source of truth).
     module FunctionRegistry
-      # Re-export the Entry struct from FunctionBuilder for compatibility
       Entry = FunctionBuilder::Entry
 
-      # Core operators that are always available
       CORE_OPERATORS = %i[== > < >= <= != between?].freeze
 
-      # Build the complete function registry by combining all categories
+      # Build core functions once
       CORE_FUNCTIONS = {}.tap do |registry|
-        function_modules = [
+        [
           ComparisonFunctions.definitions,
           MathFunctions.definitions,
           StringFunctions.definitions,
@@ -22,137 +19,158 @@ module Kumi
           ConditionalFunctions.definitions,
           TypeFunctions.definitions,
           StatFunctions.definitions
-        ]
+        ].each do |defs|
+          defs.each do |name, entry|
+            raise ArgumentError, "Duplicate core function: #{name}" if registry.key?(name)
 
-        function_modules.each do |module_definitions|
-          module_definitions.each do |name, definition|
-            if registry.key?(name)
-              raise ArgumentError, "Function #{name.inspect} is already registered. Found duplicate in function registry."
-            end
-
-            registry[name] = definition
+            registry[name] = entry
           end
         end
       end.freeze
 
-      @functions = CORE_FUNCTIONS.dup
-      @frozen = false
+      @lock      = Mutex.new
+      @functions = CORE_FUNCTIONS.transform_values(&:dup)
+      @frozen    = false
 
-      # class << self
-      # Internal interface for registering custom functions
-      def register(name, &block)
-        raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
+      class FrozenError < RuntimeError; end
 
-        fn_lambda = block.is_a?(Proc) ? block : ->(*args) { yield(*args) }
-        register_with_metadata(name, fn_lambda, arity: fn_lambda.arity, param_types: [:any], return_type: :any)
-      end
-
-      # Register with custom metadata
-      def register_with_metadata(name, fn_lambda, arity:, param_types: [:any], return_type: :any, description: nil,
-                                 inverse: nil, reducer: false)
-        raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
-
-        @functions[name] = Entry.new(
-          fn: fn_lambda,
-          arity: arity,
-          param_types: param_types,
-          return_type: return_type,
-          description: description,
-          inverse: inverse,
-          reducer: reducer
-        )
-      end
+      class << self
+        def auto_register(*mods)
+          mods.each do |mod|
+            mod.public_instance_methods(false).each do |m|
+              next if function?(m)
 
-      # Auto-register functions from modules
-      def auto_register(*modules)
-        modules.each do |mod|
-          mod.public_instance_methods(false).each do |method_name|
-            next if supported?(method_name)
+              register(m) { |*args| mod.new.public_send(m, *args) }
+            end
+            mod.singleton_methods(false).each do |m|
+              next if function?(m)
 
-            register(method_name) do |*args|
-              mod.new.public_send(method_name, *args)
+              fn = mod.method(m)
+              register(m) { |*args| fn.call(*args) }
             end
           end
         end
-      end
 
-      # Query interface
-      def supported?(name)
-        @functions.key?(name)
-      end
-
-      def operator?(name)
-        return false unless name.is_a?(Symbol)
+        #
+        # Lifecycle
+        #
+        def reset!
+          @lock.synchronize do
+            @functions = CORE_FUNCTIONS.transform_values(&:dup)
+            @frozen    = false
+          end
+        end
 
-        @functions.key?(name) && CORE_OPERATORS.include?(name)
-      end
+        def freeze!
+          @lock.synchronize do
+            @functions.each_value(&:freeze)
+            @functions.freeze
+            @frozen = true
+          end
+        end
 
-      def fetch(name)
-        @functions.fetch(name) { raise Kumi::Errors::UnknownFunction, "Unknown function: #{name}" }.fn
-      end
+        def frozen?
+          @frozen
+        end
 
-      def signature(name)
-        entry = @functions.fetch(name) { raise Kumi::Errors::UnknownFunction, "Unknown function: #{name}" }
-        {
-          arity: entry.arity,
-          param_types: entry.param_types,
-          return_type: entry.return_type,
-          description: entry.description
-        }
-      end
+        #
+        # Registration
+        #
+        # Unified entry point; used by both public and internal callers.
+        def register(name, fn_or = nil, **meta, &block)
+          fn = fn_or || block
+          raise ArgumentError, "block or Proc required" unless fn.is_a?(Proc)
+
+          defaults = {
+            arity: fn.arity,
+            param_types: [:any],
+            return_type: :any,
+            description: nil,
+            param_modes: nil,
+            reducer: false,
+            structure_function: false
+          }
+          register_with_metadata(name, fn, **defaults, **meta)
+        end
 
-      def all_functions
-        @functions.keys
-      end
+        # Back-compat explicit API
+        def register_with_metadata(name, fn, arity:, param_types: [:any], return_type: :any,
+                                   description: nil, param_modes: nil, reducer: false,
+                                   structure_function: false)
+          @lock.synchronize do
+            raise FrozenError, "registry is frozen" if @frozen
+            raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
+
+            @functions[name] = Entry.new(
+              fn: fn,
+              arity: arity,
+              param_types: param_types,
+              return_type: return_type,
+              description: description,
+              param_modes: param_modes,
+              reducer: reducer,
+              structure_function: structure_function
+            )
+          end
+        end
 
-      def reducer?(name)
-        entry = @functions.fetch(name) { return false }
-        entry.reducer || false
-      end
+        #
+        # Queries
+        #
+        def function?(name)
+          @functions.key?(name)
+        end
+        alias supported? function?
 
-      def structure_function?(name)
-        entry = @functions.fetch(name) { return false }
-        entry.structure_function || false
-      end
+        def operator?(name)
+          name.is_a?(Symbol) && function?(name) && CORE_OPERATORS.include?(name)
+        end
 
-      # Alias for compatibility
-      def all
-        @functions.keys
-      end
+        def entry(name)
+          @functions[name]
+        end
 
-      # Category accessors for introspection
-      def comparison_operators
-        ComparisonFunctions.definitions.keys
-      end
+        def fetch(name)
+          ent = entry(name)
+          raise Kumi::Errors::UnknownFunction, "Unknown function: #{name}" unless ent
 
-      def math_operations
-        MathFunctions.definitions.keys
-      end
+          ent.fn
+        end
 
-      def string_operations
-        StringFunctions.definitions.keys
-      end
+        def signature(name)
+          ent = entry(name) or raise Kumi::Errors::UnknownFunction, "Unknown function: #{name}"
+          { arity: ent.arity, param_types: ent.param_types, return_type: ent.return_type, description: ent.description }
+        end
 
-      def logical_operations
-        LogicalFunctions.definitions.keys
-      end
+        def reducer?(name)
+          ent = entry(name)
+          ent ? !!ent.reducer : false
+        end
 
-      def collection_operations
-        CollectionFunctions.definitions.keys
-      end
+        def structure_function?(name)
+          ent = entry(name)
+          ent ? !!ent.structure_function : false
+        end
 
-      def conditional_operations
-        ConditionalFunctions.definitions.keys
-      end
+        def all_functions
+          @functions.keys
+        end
+        alias all all_functions
 
-      def type_operations
-        TypeFunctions.definitions.keys
-      end
+        def functions
+          @functions.dup
+        end
 
-      def stat_operations
-        StatFunctions.definitions.keys
+        # Introspection helpers
+        def comparison_operators   = ComparisonFunctions.definitions.keys
+        def math_operations        = MathFunctions.definitions.keys
+        def string_operations      = StringFunctions.definitions.keys
+        def logical_operations     = LogicalFunctions.definitions.keys
+        def collection_operations  = CollectionFunctions.definitions.keys
+        def conditional_operations = ConditionalFunctions.definitions.keys
+        def type_operations        = TypeFunctions.definitions.keys
+        def stat_operations        = StatFunctions.definitions.keys
       end
     end
   end
 end
-# end

data/lib/kumi/core/ir/execution_engine/combinators.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module IR
+      module ExecutionEngine
+        # Pure combinators for data transformation
+        module Combinators
+          # Broadcast scalar over vec (scalar→vec only)
+          # @param s [Hash] scalar value {:k => :scalar, :v => value}
+          # @param v [Hash] vector value {:k => :vec, :scope => [...], :rows => [...]}
+          # @return [Hash] broadcasted vector
+          def self.broadcast_scalar(s, v)
+            raise "First arg must be scalar" unless s[:k] == :scalar
+            raise "Second arg must be vec" unless v[:k] == :vec
+
+            rows = v[:rows].map do |r|
+              r.key?(:idx) ? { v: s[:v], idx: r[:idx] } : { v: s[:v] }
+            end
+
+            Values.vec(v[:scope], rows, v[:has_idx])
+          end
+
+          # Positional zip for same-scope vecs
+          # @param vecs [Array<Hash>] vectors to zip together
+          # @return [Hash] zipped vector
+          def self.zip_same_scope(*vecs)
+            raise "All arguments must be vecs" unless vecs.all? { |v| v[:k] == :vec }
+            raise "All vecs must have same scope" unless vecs.map { |v| v[:scope] }.uniq.size == 1
+            raise "All vecs must have same row count" unless vecs.map { |v| v[:rows].size }.uniq.size == 1
+            return vecs.first if vecs.length == 1
+
+            first_vec = vecs.first
+            zipped_rows = first_vec[:rows].zip(*vecs[1..].map { |v| v[:rows] }).map do |row_group|
+              combined_values = row_group.map { |r| r[:v] }
+              result_row = { v: combined_values }
+              result_row[:idx] = row_group.first[:idx] if row_group.first.key?(:idx)
+              result_row
+            end
+
+            Values.vec(first_vec[:scope], zipped_rows, first_vec[:has_idx])
+          end
+
+          # Prefix-index alignment for rank expansion/broadcasting
+          # @param tgt [Hash] target vector (defines output structure)
+          # @param src [Hash] source vector (values to align)
+          # @param to_scope [Array] target scope
+          # @param require_unique [Boolean] enforce unique prefixes
+          # @param on_missing [Symbol] :error or :nil policy
+          # @return [Hash] aligned vector
+          def self.align_to(tgt, src, to_scope:, require_unique: false, on_missing: :error)
+            raise "align_to expects vecs with indices" unless [tgt, src].all? { |v| v[:k] == :vec && v[:has_idx] }
+
+            to_rank = to_scope.length
+            src_rank = src[:rows].first[:idx].length
+            raise "scope not prefix-compatible: #{src_rank} > #{to_rank}" unless src_rank <= to_rank
+
+            # Build prefix->value hash
+            h = {}
+            src[:rows].each do |r|
+              k = r[:idx].first(src_rank)
+              raise "non-unique prefix for align_to: #{k.inspect}" if require_unique && h.key?(k)
+
+              h[k] = r[:v]
+            end
+
+            # Map target rows through alignment
+            rows = tgt[:rows].map do |r|
+              k = r[:idx].first(src_rank)
+              if h.key?(k)
+                { v: h[k], idx: r[:idx] }
+              else
+                case on_missing
+                when :nil then { v: nil, idx: r[:idx] }
+                when :error then raise "missing prefix #{k.inspect} in align_to"
+                else raise "unknown on_missing policy: #{on_missing}"
+                end
+              end
+            end
+
+            Values.vec(to_scope, rows, true)
+          end
+
+          # Build hierarchical groups for lift operation
+          # @param rows [Array<Hash>] rows with indices
+          # @param depth [Integer] nesting depth
+          # @return [Array] nested array structure
+          # rows: [{ v: ..., idx: [i0,i1,...] }, ...] with lexicographically sorted :idx
+          def self.group_rows(rows, depth = 0)
+            return [] if rows.empty?
+            raise ArgumentError, "depth < 0" if depth < 0
+
+            if depth == 0
+              return rows.first[:v] if rows.first[:idx].nil? || rows.first[:idx].empty?
+
+              return rows.map { |r| r[:v] }
+            end
+
+            out = []
+            i = 0
+            n = rows.length
+            while i < n
+              head = rows[i][:idx].first
+              j = i + 1
+              j += 1 while j < n && rows[j][:idx].first == head
+
+              tail = rows[i...j].map { |r| { v: r[:v], idx: r[:idx][1..-1] } }
+              out << group_rows(tail, depth - 1)
+              i = j
+            end
+            out
+          end
+        end
+      end
+    end
+  end
+end