kumi 0.0.10 → 0.0.12

data/lib/kumi/core/analyzer/passes/broadcast_detector.rb

@@ -5,11 +5,11 @@ module Kumi
     module Analyzer
       module Passes
         # Detects which operations should be broadcast over arrays
-        # DEPENDENCIES: :inputs, :declarations
+        # DEPENDENCIES: :input_metadata, :declarations
         # PRODUCES: :broadcasts
         class BroadcastDetector < PassBase
           def run(errors)
-            input_meta = get_state(:inputs) || {}
+            input_meta = get_state(:input_metadata) || {}
             definitions = get_state(:declarations) || {}
 
             # Find array fields with their element types
@@ -40,6 +40,10 @@ module Kumi
               result = analyze_value_vectorization(name, decl.expression, array_fields, nested_paths, vectorized_values, errors,
                                                    definitions)
 
+              if ENV["DEBUG_BROADCAST_CLEAN"]
+                puts "#{name}: #{result[:type]} #{format_broadcast_info(result)}"
+              end
+
               case result[:type]
               when :vectorized
                 compiler_metadata[:vectorized_operations][name] = result[:info]
@@ -70,6 +74,43 @@ module Kumi
 
           private
 
+          def infer_argument_scope(arg, array_fields, nested_paths)
+            case arg
+            when Kumi::Syntax::InputElementReference
+              if nested_paths.key?(arg.path)
+                # Extract scope from path - each array dimension in the path
+                arg.path.select.with_index { |_seg, i| nested_paths[arg.path[0..i]] }
+              else
+                arg.path.select { |seg| array_fields.key?(seg) }
+              end
+            when Kumi::Syntax::CallExpression
+              # For nested calls, find the deepest input reference
+              deepest_scope = []
+              arg.args.each do |nested_arg|
+                scope = infer_argument_scope(nested_arg, array_fields, nested_paths)
+                deepest_scope = scope if scope.length > deepest_scope.length
+              end
+              deepest_scope
+            else
+              []
+            end
+          end
+
+          def format_broadcast_info(result)
+            case result[:type]
+            when :vectorized
+              info = result[:info]
+              "→ #{info[:source]} (path: #{info[:path]&.join('.')})"
+            when :reduction
+              info = result[:info]
+              "→ fn:#{info[:function]} (arg: #{info[:argument]&.class&.name&.split('::')&.last})"
+            when :scalar
+              "→ scalar"
+            else
+              "→ #{result[:info]}"
+            end
+          end
+
           def compute_compilation_metadata(name, _decl, compiler_metadata, _vectorized_values, _array_fields)
             metadata = {
               operation_mode: :broadcast, # Default mode
@@ -169,7 +210,7 @@ module Kumi
             current_access_mode = parent_access_mode
             if current_meta[:type] == :array
               array_depth += 1
-              current_access_mode = current_meta[:access_mode] || :object # Default to :object if not specified
+              current_access_mode = current_meta[:access_mode] || :field # Default to :field if not specified
             end
 
             # If this field has children, recurse into them
@@ -208,7 +249,6 @@ module Kumi
               # Check if this path exists in nested_paths metadata (supports nested arrays)
               if nested_paths.key?(expr.path)
                 { type: :vectorized, info: { source: :nested_array_access, path: expr.path, nested_metadata: nested_paths[expr.path] } }
-              # Fallback to old array_fields detection for backward compatibility
               elsif array_fields.key?(expr.path.first)
                 { type: :vectorized, info: { source: :array_field_access, path: expr.path } }
               else
@@ -236,76 +276,106 @@ module Kumi
           end
 
           def analyze_call_vectorization(_name, expr, array_fields, nested_paths, vectorized_values, errors, definitions = nil)
-            # Check if this is a reduction function using function registry metadata
-            if Kumi::Registry.reducer?(expr.fn_name)
-              # Only treat as reduction if the argument is actually vectorized
-              arg_info = analyze_argument_vectorization(expr.args.first, array_fields, nested_paths, vectorized_values, definitions)
-              if arg_info[:vectorized]
-                # Pre-compute which argument indices need flattening
-                flatten_indices = []
-                expr.args.each_with_index do |arg, index|
-                  arg_vectorization = analyze_argument_vectorization(arg, array_fields, nested_paths, vectorized_values, definitions)
-                  flatten_indices << index if arg_vectorization[:vectorized]
-                end
-
-                { type: :reduction, info: {
-                  function: expr.fn_name,
-                  source: arg_info[:source],
-                  argument: expr.args.first,
-                  flatten_argument_indices: flatten_indices
-                } }
-              else
-                # Not a vectorized reduction - just a regular function call
-                { type: :scalar }
-              end
+            entry         = Kumi::Registry.entry(expr.fn_name)
+            is_reducer    = entry&.reducer
+            is_structure  = entry&.structure_function
 
-            else
+            # 1) Analyze all args once
+            arg_infos = expr.args.map do |arg|
+              analyze_argument_vectorization(arg, array_fields, nested_paths, vectorized_values, definitions)
+            end
+            vec_idx   = arg_infos.each_index.select { |i| arg_infos[i][:vectorized] }
+            vec_any   = !vec_idx.empty?
 
-              # Special case: cascade_and takes individual trait arguments
-              if expr.fn_name == :cascade_and
-                # Check if any of the individual arguments are vectorized traits
-                vectorized_trait = expr.args.find do |arg|
-                  arg.is_a?(Kumi::Syntax::DeclarationReference) && vectorized_values[arg.name]&.[](:vectorized)
-                end
-                if vectorized_trait
-                  return { type: :vectorized, info: { source: :cascade_condition_with_vectorized_trait, trait: vectorized_trait.name } }
-                end
+            # 2) Special form: cascade_and (vectorized if any trait arg is vectorized)
+            if expr.fn_name == :cascade_and
+              vectorized_trait = expr.args.find do |arg|
+                arg.is_a?(Kumi::Syntax::DeclarationReference) && vectorized_values[arg.name]&.[](:vectorized)
               end
-
-              # Analyze arguments to determine function behavior
-              arg_infos = expr.args.map do |arg|
-                analyze_argument_vectorization(arg, array_fields, nested_paths, vectorized_values, definitions)
+              if vectorized_trait
+                return { type: :vectorized,
+                         info: { source: :cascade_condition_with_vectorized_trait, trait: vectorized_trait&.name } }
               end
 
-              if arg_infos.any? { |info| info[:vectorized] }
-                # Check for dimension mismatches when multiple arguments are vectorized
-                vectorized_sources = arg_infos.select { |info| info[:vectorized] }.filter_map { |info| info[:array_source] }.uniq
+              return { type: :scalar }
+            end
 
-                if vectorized_sources.length > 1
-                  # Multiple different array sources - this is a dimension mismatch
-                  # Generate enhanced error message with type information
-                  enhanced_message = build_dimension_mismatch_error(expr, arg_infos, array_fields, vectorized_sources)
+            # 3) Reducers: only reduce when the input is actually vectorized
+            if is_reducer
+              return { type: :scalar } unless vec_any
 
-                  report_error(errors, enhanced_message, location: expr.loc, type: :semantic)
-                  return { type: :scalar } # Treat as scalar to prevent further errors
-                end
+              # which args were vectorized?
+              flatten_indices = vec_idx.dup
+              vectorized_arg_index = vec_idx.first
+              argument_ast = expr.args[vectorized_arg_index]
+
+              src_info = arg_infos[vectorized_arg_index]
+
+              return {
+                type: :reduction,
+                info: {
+                  function: expr.fn_name,
+                  source: src_info[:source],
+                  argument: argument_ast, # << keep AST of the vectorized argument
+                  flatten_argument_indices: flatten_indices
+                }
+              }
+            end
 
-                # Check if this is a structure function that should work on the array as-is
-                if structure_function?(expr.fn_name)
-                  # Structure functions like size should work on structure as-is (scalar)
-                  { type: :scalar }
+            # 4) Structure (non-reducer) functions like `size`
+            if is_structure
+              # If any arg is itself a PURE reducer call (e.g., size(sum(x))), the inner collapses first ⇒ outer is scalar
+              # But dual-nature functions (both reducer AND structure) should be treated as structure functions when nested
+              return { type: :scalar } if expr.args.any? do |a|
+                if a.is_a?(Kumi::Syntax::CallExpression)
+                  arg_entry = Kumi::Registry.entry(a.fn_name)
+                  arg_entry&.reducer && !arg_entry&.structure_function # Pure reducer only
                 else
-                  # This is a vectorized operation - broadcast over elements
-                  { type: :vectorized, info: {
-                    operation: expr.fn_name,
-                    vectorized_args: arg_infos.map.with_index { |info, i| [i, info[:vectorized]] }.to_h
-                  } }
+                  false
                 end
-              else
-                # No vectorized arguments - regular scalar function
-                { type: :scalar }
               end
+
+              # Structure fn over a vectorized element path ⇒ per-parent vectorization
+              return { type: :scalar } unless vec_any
+
+              src_info     = arg_infos[vec_idx.first]
+              parent_scope = src_info[:parent_scope] || src_info[:source] # fallback if analyzer encodes parent separately
+              return {
+                type: :vectorized,
+                info: {
+                  operation: expr.fn_name,
+                  source: src_info[:source],
+                  parent_scope: parent_scope,
+                  vectorized_args: vec_idx.to_h { |i| [i, true] }
+                }
+              }
+
+              # Structure fn over a scalar/materialized container ⇒ scalar
+
             end
+
+            # 5) Generic vectorized map (non-structure, non-reducer)
+            if vec_any
+              # Dimension / source compatibility check
+              sources = vec_idx.map { |i| arg_infos[i][:array_source] }.compact.uniq
+              if sources.size > 1
+                enhanced_message = build_dimension_mismatch_error(expr, arg_infos, array_fields, sources)
+                report_error(errors, enhanced_message, location: expr.loc, type: :semantic)
+                return { type: :scalar } # fail safe to prevent cascading errors
+              end
+
+              return {
+                type: :vectorized,
+                info: {
+                  operation: expr.fn_name,
+                  source: arg_infos[vec_idx.first][:source],
+                  vectorized_args: vec_idx.to_h { |i| [i, true] }
+                }
+              }
+            end
+
+            # 6) Pure scalar
+            { type: :scalar }
           end
 
           def structure_function?(fn_name)
@@ -337,9 +407,32 @@ module Kumi
               end
 
             when Kumi::Syntax::CallExpression
-              # Recursively check
+              # Recursively check nested call
               result = analyze_value_vectorization(nil, arg, array_fields, nested_paths, vectorized_values, [], definitions)
-              { vectorized: result[:type] == :vectorized, source: :expression }
+              # Handle different result types appropriately
+              case result[:type]
+              when :reduction
+                # Reductions can produce vectors if they preserve some dimensions
+                # This aligns with lower_to_ir logic for grouped reductions
+                info = result[:info]
+                if info && info[:argument]
+                  # Check if the reduction argument has array scope that would be preserved
+                  arg_scope = infer_argument_scope(info[:argument], array_fields, nested_paths)
+                  if arg_scope.length > 1
+                    # Multi-dimensional reduction - likely preserves outer dimension (per-player)
+                    { vectorized: true, source: :grouped_reduction, array_source: arg_scope.first }
+                  else
+                    # Single dimension or scalar reduction
+                    { vectorized: false, source: :scalar_from_reduction }
+                  end
+                else
+                  { vectorized: false, source: :scalar_from_reduction }
+                end
+              when :vectorized
+                { vectorized: true, source: :expression }
+              else
+                { vectorized: false, source: :scalar }
+              end
 
             else
               { vectorized: false }

data/lib/kumi/core/analyzer/passes/dependency_resolver.rb

@@ -26,7 +26,7 @@ module Kumi
 
           def run(errors)
             definitions = get_state(:declarations)
-            input_meta = get_state(:inputs)
+            input_meta = get_state(:input_metadata)
 
             dependency_graph = Hash.new { |h, k| h[k] = [] }
             reverse_dependencies = Hash.new { |h, k| h[k] = [] }

data/lib/kumi/core/analyzer/passes/input_access_planner_pass.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        class InputAccessPlannerPass < PassBase
+          def run(errors)
+            input_metadata = get_state(:input_metadata)
+
+            options = {
+              on_missing: :error,
+              key_policy: :indifferent
+            }
+
+            # TODO : Allow by input definition on policies or at least general policy definition
+            plans = Kumi::Core::Compiler::AccessPlanner.plan(input_metadata, options)
+
+            # Quick validation
+            validate_plans!(plans, errors)
+
+            # Create new state with access plans
+            state.with(:access_plans, plans.freeze)
+          end
+
+          private
+
+          def validate_plans!(plans, errors)
+            plans.each do |path, plan_list|
+              add_error(errors, nil, "No access plans generated for path: #{path}") if plan_list.nil? || plan_list.empty?
+
+              plan_list&.each do |plan|
+                unless plan[:operations].is_a?(Array)
+                  add_error(errors, nil, "Invalid operations for path #{path}: expected Array, got #{plan[:operations].class}")
+                end
+
+                unless plan[:mode].is_a?(Symbol)
+                  add_error(errors, nil, "Invalid mode for path #{path}: expected Symbol, got #{plan[:mode].class}")
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/input_collector.rb

@@ -4,135 +4,157 @@ module Kumi
   module Core
     module Analyzer
       module Passes
-        # RESPONSIBILITY: Collect field metadata from input declarations and validate consistency
-        # DEPENDENCIES: :definitions
-        # PRODUCES: :inputs - Hash mapping field names to {type:, domain:} metadata
-        # INTERFACE: new(schema, state).run(errors)
+        # Emits per-node metadata:
+        #   :type, :domain
+        #   :container     => :scalar | :field | :array
+        #   :access_mode   => :field | :element          # how THIS node is read once reached
+        #   :enter_via     => :hash | :array           # how we HOP from parent to THIS node
+        #   :consume_alias => true|false               # inline array hop (alias is not a hash key)
+        #   :children      => { name => node_meta }    # optional
+        #
+        # Invariants:
+        # - Any nested array (child depth ≥ 1) must declare its element (i.e., have children).
+        # - Depth-0 inputs always: enter_via :hash, consume_alias false, access_mode :field.
         class InputCollector < PassBase
           def run(errors)
             input_meta = {}
 
-            schema.inputs.each do |field_decl|
-              unless field_decl.is_a?(Kumi::Syntax::InputDeclaration)
-                report_error(errors, "Expected InputDeclaration node, got #{field_decl.class}", location: field_decl.loc)
-                next
-              end
-
-              name = field_decl.name
-              existing = input_meta[name]
-
-              if existing
-                # Check for compatibility and merge
-                merged_meta = merge_field_metadata(existing, field_decl, errors)
-                input_meta[name] = merged_meta if merged_meta
-              else
-                # New field - collect its metadata
-                input_meta[name] = collect_field_metadata(field_decl, errors)
-              end
+            schema.inputs.each do |decl|
+              name = decl.name
+              input_meta[name] = collect_field_metadata(decl, errors, depth: 0, name: name)
             end
 
-            state.with(:inputs, freeze_nested_hash(input_meta))
+            input_meta.each_value(&:deep_freeze!)
+            state.with(:input_metadata, input_meta.freeze)
           end
 
           private
 
-          def collect_field_metadata(field_decl, errors)
-            validate_domain_type(field_decl, errors) if field_decl.domain
-
-            metadata = {
-              type: field_decl.type,
-              domain: field_decl.domain,
-              access_mode: field_decl.access_mode
-            }
-
-            # Process children if present
-            if field_decl.children && !field_decl.children.empty?
-              children_meta = {}
-              field_decl.children.each do |child_decl|
-                unless child_decl.is_a?(Kumi::Syntax::InputDeclaration)
-                  report_error(errors, "Expected InputDeclaration node in children, got #{child_decl.class}", location: child_decl.loc)
-                  next
-                end
-                children_meta[child_decl.name] = collect_field_metadata(child_decl, errors)
+          # ---------- builders ----------
+
+          def collect_field_metadata(decl, errors, depth:, name:)
+            children = nil
+            if decl.children&.any?
+              children = {}
+              decl.children.each do |child|
+                children[child.name] = collect_field_metadata(child, errors, depth: depth + 1, name: child.name)
               end
-              metadata[:children] = children_meta
             end
 
-            metadata
+            access_mode = decl.access_mode || :field
+
+            meta = Structs::InputMeta.new(
+              type: decl.type,
+              domain: decl.domain,
+              container: kind_from_type(decl.type),
+              access_mode: access_mode,
+              enter_via: :hash,
+              consume_alias: false,
+              children: children
+            )
+            stamp_edges_from!(meta, errors, parent_depth: depth)
+            validate_access_modes!(meta, errors, parent_depth: depth)
+            meta
           end
 
-          def merge_field_metadata(existing, field_decl, errors)
-            name = field_decl.name
-
-            # Check for type compatibility
-            if existing[:type] != field_decl.type && field_decl.type && existing[:type]
-              report_error(errors,
-                           "Field :#{name} declared with conflicting types: #{existing[:type]} vs #{field_decl.type}",
-                           location: field_decl.loc)
+          # ---------- edge stamping + validation ----------
+          #
+          # Sets child[:enter_via], child[:consume_alias], child[:access_mode] defaults,
+          # and validates nested arrays declare their element.
+          #
+          # Rules:
+          # - Common: any ARRAY child at child-depth ≥ 1 must have children (no bare nested array).
+          # - Parent :object → any child:
+          #     child.enter_via = :hash; child.consume_alias = false; child.access_mode ||= :field
+          # - Parent :array:
+          #     * If exactly one child:
+          #         - child.container ∈ {:scalar, :array} → via :array, consume_alias true, access_mode :element
+          #         - child.container == :field         → via :hash,  consume_alias false, access_mode :field
+          #     * Else (element object): every child → via :hash, consume_alias false, access_mode :field
+          def stamp_edges_from!(parent_meta, errors, parent_depth:)
+            kids = parent_meta.children || {}
+            return if kids.empty?
+
+            # Validate nested arrays anywhere below root
+            kids.each do |kname, child|
+              next unless child.container == :array
+
+              if !child.children || child.children.empty?
+                report_error(errors, "Nested array at :#{kname} must declare its element", location: nil)
+              end
             end
 
-            # Check for domain compatibility
-            if existing[:domain] != field_decl.domain && field_decl.domain && existing[:domain]
-              report_error(errors,
-                           "Field :#{name} declared with conflicting domains: #{existing[:domain].inspect} vs #{field_decl.domain.inspect}",
-                           location: field_decl.loc)
-            end
+            case parent_meta.container
+            when :object, :hash
+              kids.each_value do |child|
+                child.enter_via = :hash
+                child.consume_alias = false
+                child.access_mode ||= :field  # Only set if not explicitly specified
+              end
 
-            # Validate domain type if provided
-            validate_domain_type(field_decl, errors) if field_decl.domain
-
-            # Merge metadata (later declarations override nil values)
-            merged = {
-              type: field_decl.type || existing[:type],
-              domain: field_decl.domain || existing[:domain],
-              access_mode: field_decl.access_mode || existing[:access_mode]
-            }
-
-            # Merge children if present
-            if field_decl.children && !field_decl.children.empty?
-              existing_children = existing[:children] || {}
-              new_children = {}
-
-              field_decl.children.each do |child_decl|
-                unless child_decl.is_a?(Kumi::Syntax::InputDeclaration)
-                  report_error(errors, "Expected InputDeclaration node in children, got #{child_decl.class}", location: child_decl.loc)
-                  next
+            when :array
+              # Array parents MUST explicitly declare their access mode
+              access_mode = parent_meta.access_mode
+              raise "Array must explicitly declare access_mode (:field or :element)" unless access_mode
+
+              case access_mode
+              when :field
+                # Array of objects: all children are fields accessed via hash
+                kids.each_value do |child|
+                  child.enter_via = :hash
+                  child.consume_alias = false
+                  child.access_mode = :field
                 end
 
-                child_name = child_decl.name
-                new_children[child_name] = if existing_children[child_name]
-                                             merge_field_metadata(existing_children[child_name], child_decl, errors)
-                                           else
-                                             collect_field_metadata(child_decl, errors)
-                                           end
-              end
+              when :element
+                _name, only = kids.first
+                only.enter_via = :array
+                only.consume_alias = true
+                only.access_mode = :element
 
-              merged[:children] = new_children
-            elsif existing[:children]
-              merged[:children] = existing[:children]
+              else
+                raise "Invalid access_mode :#{access_mode} for array (must be :field or :element)"
+              end
             end
-
-            merged
           end
 
-          def freeze_nested_hash(hash)
-            hash.each_value do |value|
-              freeze_nested_hash(value) if value.is_a?(Hash)
-            end
-            hash.freeze
-          end
+          # Enforce access_mode semantics are only used in valid contexts.
+          def validate_access_modes!(parent_meta, errors, parent_depth:)
+            kids = parent_meta.children || {}
+            return if kids.empty?
+
+            kids.each do |kname, child|
+              mode = child.access_mode
+              next unless mode
 
-          def validate_domain_type(field_decl, errors)
-            domain = field_decl.domain
-            return if valid_domain_type?(domain)
+              unless %i[field element].include?(mode)
+                report_error(errors, "Invalid access_mode for :#{kname}: #{mode.inspect}", location: nil)
+                next
+              end
 
-            report_error(errors,
-                         "Field :#{field_decl.name} has invalid domain constraint: #{domain.inspect}. Domain must be a Range, Array, or Proc",
-                         location: field_decl.loc)
+              if mode == :element
+                if parent_meta.container == :array
+                  single = (kids.size == 1)
+                  unless single && %i[scalar array].include?(child.container)
+                    report_error(errors, "access_mode :element only valid for single scalar/array element (at :#{kname})", location: nil)
+                  end
+                else
+                  # Only scalar children under non-array parents are invalid with :element mode
+                  # Arrays under hash/object parents can have :element mode (for arrays of scalars)
+                  if child.container == :scalar
+                    report_error(errors, "access_mode :element only valid under array parent (at :#{kname})", location: nil)
+                  end
+                end
+              end
+            end
           end
 
-          def valid_domain_type?(domain)
-            domain.is_a?(Range) || domain.is_a?(Array) || domain.is_a?(Proc)
+          def kind_from_type(t)
+            return :array if t == :array
+            return :hash if t == :hash
+            return :object if t == :field
+
+            :scalar
           end
         end
       end