kumi 0.0.9 → 0.0.11

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

@@ -5,7 +5,7 @@ module Kumi
     module Analyzer
       module Passes
         # RESPONSIBILITY: Detect unsatisfiable constraints and analyze cascade mutual exclusion
-        # DEPENDENCIES: :declarations from NameIndexer, :inputs from InputCollector
+        # DEPENDENCIES: :declarations from NameIndexer, :input_metadata from InputCollector
         # PRODUCES: :cascades - Hash of cascade mutual exclusion analysis results
         # INTERFACE: new(schema, state).run(errors)
         class UnsatDetector < VisitorPass
@@ -16,7 +16,7 @@ module Kumi
 
           def run(errors)
             definitions = get_state(:declarations)
-            @input_meta = get_state(:inputs) || {}
+            @input_meta = get_state(:input_metadata) || {}
             @definitions = definitions
             @evaluator = ConstantEvaluator.new(definitions)
 
@@ -40,12 +40,31 @@ module Kumi
                 atoms = gather_atoms(decl.expression, definitions, Set.new)
                 next if atoms.empty?
 
+                # DEBUG: Add detailed logging for hierarchical broadcasting debugging
+                if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                  puts "DEBUG UNSAT: Checking declaration '#{decl.name}' at #{decl.loc}"
+                  puts "  Expression: #{decl.expression.inspect}"
+                  puts "  Gathered atoms: #{atoms.map(&:inspect)}"
+                  puts "  Input meta: #{@input_meta.keys.inspect}" if @input_meta
+                end
+
                 # Use enhanced solver that can detect cross-variable mathematical constraints
-                impossible = if definitions && !definitions.empty?
-                               Kumi::Core::ConstraintRelationshipSolver.unsat?(atoms, definitions, input_meta: @input_meta)
-                             else
-                               Kumi::Core::AtomUnsatSolver.unsat?(atoms)
-                             end
+                if definitions && !definitions.empty?
+                  result = Kumi::Core::ConstraintRelationshipSolver.unsat?(atoms, definitions, input_meta: @input_meta)
+                  if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                    puts "  Enhanced solver result: #{result}"
+                  end
+                else
+                  result = Kumi::Core::AtomUnsatSolver.unsat?(atoms)
+                  if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                    puts "  Basic solver result: #{result}"
+                  end
+                end
+                impossible = result
+
+                if impossible && (ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257"))
+                  puts "  -> FLAGGING AS IMPOSSIBLE: #{decl.name}"
+                end
 
                 report_error(errors, "conjunction `#{decl.name}` is impossible", location: decl.loc) if impossible
               end
@@ -63,15 +82,24 @@ module Kumi
             decl.expression.cases[0...-1].each do |when_case|
               next unless when_case.condition
 
-              next unless when_case.condition.fn_name == :all?
+              next unless when_case.condition.fn_name == :cascade_and
 
               when_case.condition.args.each do |arg|
-                next unless arg.is_a?(ArrayExpression)
-
-                arg.elements.each do |element|
-                  next unless element.is_a?(DeclarationReference)
-
-                  trait_name = element.name
+                if arg.is_a?(ArrayExpression)
+                  # Handle array elements (for array broadcasting)
+                  arg.elements.each do |element|
+                    next unless element.is_a?(DeclarationReference)
+
+                    trait_name = element.name
+                    trait = definitions[trait_name]
+                    if trait
+                      conditions << trait.expression
+                      condition_traits << trait_name
+                    end
+                  end
+                elsif arg.is_a?(DeclarationReference)
+                  # Handle direct trait references (simple case)
+                  trait_name = arg.name
                   trait = definitions[trait_name]
                   if trait
                     conditions << trait.expression
@@ -183,8 +211,8 @@ module Kumi
                 # We should NOT add OR children to the stack as they would be treated as AND
                 # OR expressions need separate analysis in the main run() method
                 next
-              elsif current.is_a?(CallExpression) && current.fn_name == :all?
-                # For all? function, add all trait arguments to the stack
+              elsif current.is_a?(CallExpression) && current.fn_name == :cascade_and
+                # cascade_and takes individual arguments (not wrapped in array)
                 current.args.each { |arg| stack << arg }
               elsif current.is_a?(ArrayExpression)
                 # For ArrayExpression, add all elements to the stack
@@ -212,7 +240,18 @@ module Kumi
             # This is the correct behavior: each 'on' condition should be checked separately
             # since only ONE will be evaluated at runtime (they're mutually exclusive by design)
 
-            decl.expression.cases.each_with_index do |when_case, _index|
+            # DEBUG: Add detailed logging for hierarchical broadcasting debugging
+            if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+              puts "DEBUG UNSAT CASCADE: Checking cascade '#{decl.name}' at #{decl.loc}"
+              puts "  Total cases: #{decl.expression.cases.length}"
+            end
+
+            decl.expression.cases.each_with_index do |when_case, index|
+              # DEBUG: Log each case
+              if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                puts "  Case #{index}: condition=#{when_case.condition.inspect}"
+              end
+
               # Skip the base case (it's typically a literal true condition)
               next if when_case.condition.is_a?(Literal) && when_case.condition.value == true
 
@@ -220,52 +259,51 @@ module Kumi
               next if when_case.condition.is_a?(CallExpression) && %i[any? none?].include?(when_case.condition.fn_name)
 
               # Skip single-trait 'on' branches: trait-level unsat detection covers these
-              if when_case.condition.is_a?(CallExpression) && when_case.condition.fn_name == :all?
-                # Handle both ArrayExpression (old format) and multiple args (new format)
-                if when_case.condition.args.size == 1 && when_case.condition.args.first.is_a?(ArrayExpression)
-                  list = when_case.condition.args.first
-                  next if list.elements.size == 1
-                elsif when_case.condition.args.size == 1
-                  # Multiple args format
-                  next
-                end
+              if when_case.condition.is_a?(CallExpression) && when_case.condition.fn_name == :cascade_and && (when_case.condition.args.size == 1)
+                # cascade_and uses individual arguments - skip if only one trait
+                next
               end
+
               # Gather atoms from this individual condition only
               condition_atoms = gather_atoms(when_case.condition, definitions, Set.new, [])
-              # DEBUG
-              # if when_case.condition.is_a?(CallExpression) && [:all?, :any?, :none?].include?(when_case.condition.fn_name)
-              #   puts "  Args: #{when_case.condition.args.inspect}"
-              #   puts "  Atoms found: #{condition_atoms.inspect}"
-              # end
 
-              # Only flag if this individual condition is impossible
-              # if !condition_atoms.empty?
-              #   is_unsat = Kumi::Core::AtomUnsatSolver.unsat?(condition_atoms)
-              #   puts "  Is unsat? #{is_unsat}"
-              # end
+              # DEBUG: Add detailed logging for hierarchical broadcasting debugging
+              if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                puts "    Condition atoms: #{condition_atoms.map(&:inspect)}"
+              end
+
               # Use enhanced solver for cascade conditions too
-              impossible = if definitions && !definitions.empty?
-                             Kumi::Core::ConstraintRelationshipSolver.unsat?(condition_atoms, definitions, input_meta: @input_meta)
-                           else
-                             Kumi::Core::AtomUnsatSolver.unsat?(condition_atoms)
-                           end
+              if definitions && !definitions.empty?
+                result = Kumi::Core::ConstraintRelationshipSolver.unsat?(condition_atoms, definitions, input_meta: @input_meta)
+                if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                  puts "    Enhanced solver result: #{result}"
+                end
+              else
+                result = Kumi::Core::AtomUnsatSolver.unsat?(condition_atoms)
+                if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                  puts "    Basic solver result: #{result}"
+                end
+              end
+              impossible = result
               next unless !condition_atoms.empty? && impossible
 
               # For multi-trait on-clauses, report the trait names rather than the value name
-              if when_case.condition.is_a?(CallExpression) && when_case.condition.fn_name == :all?
-                # Handle both ArrayExpression (old format) and multiple args (new format)
-                trait_bindings = if when_case.condition.args.size == 1 && when_case.condition.args.first.is_a?(ArrayExpression)
-                                   when_case.condition.args.first.elements
-                                 else
-                                   when_case.condition.args
-                                 end
+              if when_case.condition.is_a?(CallExpression) && when_case.condition.fn_name == :cascade_and
+                # cascade_and uses individual arguments
+                trait_bindings = when_case.condition.args
 
                 if trait_bindings.all?(DeclarationReference)
                   traits = trait_bindings.map(&:name).join(" AND ")
+                  if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                    puts "    -> FLAGGING AS IMPOSSIBLE CASCADE CONDITION: #{traits}"
+                  end
                   report_error(errors, "conjunction `#{traits}` is impossible", location: decl.loc)
                   next
                 end
               end
+              if ENV["DEBUG_UNSAT"] || decl.loc&.to_s&.include?("hierarchical_broadcasting_spec.rb:257")
+                puts "    -> FLAGGING AS IMPOSSIBLE CASCADE: #{decl.name}"
+              end
               report_error(errors, "conjunction `#{decl.name}` is impossible", location: decl.loc)
             end
           end
@@ -275,6 +313,12 @@ module Kumi
             when InputReference, DeclarationReference
               val = @evaluator.evaluate(node)
               val == :unknown ? node.name : val
+            when InputElementReference
+              # For hierarchical paths like input.companies.regions.offices.teams.department,
+              # create a unique identifier that represents the specific path
+              # This prevents false positives where different paths are treated as the same :unknown
+              path_identifier = node.path.join(".").to_s
+              path_identifier.to_sym
             when Literal
               node.value
             else

data/lib/kumi/core/analyzer/plans.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      # Typed plan structures for HIR (High-level Intermediate Representation)
+      # These plans are produced by analyzer passes and consumed by LowerToIRPass
+      # to generate LIR (Low-level IR) operations.
+      module Plans
+        # Scope plan: defines the dimensional execution context for a declaration
+        Scope = Struct.new(:scope, :lifts, :join_hint, :arg_shapes, keyword_init: true) do
+          def initialize(scope: [], lifts: [], join_hint: nil, arg_shapes: {})
+            super
+            freeze
+          end
+
+          def depth
+            scope.size
+          end
+
+          def scalar?
+            scope.empty?
+          end
+        end
+
+        # Join plan: defines how to align multiple arguments at a target scope
+        Join = Struct.new(:policy, :target_scope, keyword_init: true) do
+          def initialize(policy: :zip, target_scope: [])
+            super
+            freeze
+          end
+        end
+
+        # Reduce plan: defines how to reduce dimensions in array operations
+        Reduce = Struct.new(:function, :axis, :source_scope, :result_scope, :flatten_args, keyword_init: true) do
+          def initialize(function:, axis: [], source_scope: [], result_scope: [], flatten_args: [])
+            super
+            freeze
+          end
+
+          def total_reduction?
+            axis == :all || result_scope.empty?
+          end
+
+          def partial_reduction?
+            !total_reduction?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/structs/access_plan.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      # One plan for a specific path and mode (path:mode)
+      AccessPlan = Struct.new(:path, :containers, :leaf, :scope, :depth, :mode,
+                              :on_missing, :key_policy, :operations, keyword_init: true) do
+        def initialize(path:, containers:, leaf:, scope:, depth:, mode:, on_missing:, key_policy:, operations:)
+          super
+          freeze
+        end
+
+        def accessor_key = "#{path}:#{mode}"
+        def ndims        = depth
+        def scalar?      = depth.zero?
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/structs/input_meta.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Structs
+        # Represents metadata for a single input field produced by InputCollector
+        InputMeta = Struct.new(
+          :type,
+          :domain,
+          :container,
+          :access_mode,
+          :enter_via,
+          :consume_alias,
+          :children,
+          keyword_init: true
+        ) do
+          def deep_freeze!
+            if children
+              children.each_value(&:deep_freeze!)
+              children.freeze
+            end
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/access_builder.rb

@@ -0,0 +1,36 @@
+module Kumi
+  module Core
+    module Compiler
+      class AccessBuilder
+        def self.build(plans)
+          accessors = {}
+          plans.each_value do |variants|
+            variants.each do |plan|
+              key = plan.respond_to?(:accessor_key) ? plan.accessor_key : "#{plan.path}:#{mode}"
+              accessors[key] = build_proc_for(
+                mode: plan.mode,
+                path_key: plan.path,
+                missing: (plan.on_missing || :error).to_sym,
+                key_policy: (plan.key_policy || :indifferent).to_sym,
+                operations: plan.operations
+              )
+            end
+          end
+          accessors.freeze
+        end
+
+        def self.build_proc_for(mode:, path_key:, missing:, key_policy:, operations:)
+          case mode
+          when :read        then Accessors::ReadAccessor.build(operations, path_key, missing, key_policy)
+          when :materialize then Accessors::MaterializeAccessor.build(operations, path_key, missing, key_policy)
+          when :ravel       then Accessors::RavelAccessor.build(operations, path_key, missing, key_policy)
+          when :each_indexed then Accessors::EachIndexedAccessor.build(operations, path_key, missing, key_policy, true)
+          when :each then Accessors::EachAccessor.build(operations, path_key, missing, key_policy)
+          else
+            raise "Unknown accessor mode: #{mode.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/access_planner.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require_relative "../analyzer/structs/input_meta"
+require_relative "../analyzer/structs/access_plan"
+
+module Kumi
+  module Core
+    module Compiler
+      # Generates deterministic access plans from normalized input metadata.
+      #
+      # Metadata expectations (produced by InputCollector):
+      # - Each node has:
+      #     :container   => :scalar | :read | :array
+      #     :children    => { name => meta }  (optional)
+      # - Each non-root node (i.e., any child) carries edge hints from its parent:
+      #     :enter_via     => :field | :array   # how the parent reaches THIS node
+      #     :consume_alias => true|false        # inline array edge; planner does not need this to emit ops
+      #
+      # Planning rules (single source of truth):
+      # - Root is an implicit object.
+      # - If parent is :array, always emit :enter_array before stepping to the child.
+      #     - If child.enter_via == :field → also emit :enter_hash(child_name).
+      #     - If child.enter_via == :array → inline edge, do NOT emit :enter_hash for the alias.
+      # - If parent is :read (or root), emit :enter_hash(child_name).
+      #
+      # Modes (one plan per mode):
+      # - Scalar paths (no array in lineage)    → [:read]
+      # - Vector paths (≥1 array in lineage)    → [:each_indexed, :materialize, :ravel]
+      # - If @defaults[:mode] is set, emit only that mode (alias :read → :read).
+      class AccessPlanner
+        def self.plan(meta, options = {}) = new(meta, options).plan
+        def self.plan_for(meta, path, options = {}) = new(meta, options).plan_for(path)
+
+        def initialize(meta, options = {})
+          @meta = meta
+          @defaults = { on_missing: :error, key_policy: :indifferent, mode: nil }.merge(options)
+          @plans = {}
+        end
+
+        def plan
+          @meta.each_key { |root| walk_and_emit([root.to_s]) }
+          @plans
+        end
+
+        def plan_for(path)
+          segs = path.split(".")
+          ensure_path!(segs)
+          emit_for_segments(segs, explicit_mode: @defaults[:mode])
+          @plans
+        end
+
+        private
+
+        def walk_and_emit(path)
+          emit_for_segments(path)
+          node = meta_node_for(path)
+          return if node[:children].nil?
+
+          node[:children].each_key do |c|
+            walk_and_emit(path + [c.to_s])
+          end
+        end
+
+        def emit_for_segments(path, explicit_mode: nil)
+          lineage = container_lineage(path)
+          base    = build_base_plan(path, lineage)
+          node    = meta_node_for(path)
+
+          modes = explicit_mode || infer_modes(lineage, node)
+          modes = [modes] unless modes.is_a?(Array)
+
+          list = (@plans[base[:path]] ||= [])
+          modes.each do |mode|
+            operations = build_operations(path, mode)
+
+            list << Kumi::Core::Analyzer::AccessPlan.new(
+              path: base[:path],
+              containers: base[:containers],
+              leaf: base[:leaf],
+              scope: base[:scope],
+              depth: base[:depth],
+              mode: mode, # :read | :each_indexed | :materialize | :ravel
+              on_missing: base[:on_missing],
+              key_policy: base[:key_policy],
+              operations: operations
+            )
+          end
+        end
+
+        def build_base_plan(path, lineage)
+          {
+            path: path.join("."),
+            containers: lineage, # symbols of array segments in the path
+            leaf: path.last.to_sym,
+            scope: lineage.dup,            # alias kept for analyzer symmetry
+            depth: lineage.length,         # rank
+            on_missing: @defaults[:on_missing],
+            key_policy: @defaults[:key_policy]
+
+          }.freeze
+        end
+
+        def infer_modes(lineage, _node)
+          lineage.empty? ? [:read] : %i[each_indexed materialize ravel]
+        end
+
+        # Core op builder: apply the parent→child edge rule per segment.
+        def build_operations(path, mode)
+          ops = []
+          parent_meta = nil
+          cur = @meta
+
+          puts "\n🔨 Building operations for path: #{path.join('.')}:#{mode}" if ENV["DEBUG_ACCESSOR_OPS"]
+
+          path.each_with_index do |seg, idx|
+            node = ig(cur, seg) or raise ArgumentError, "Unknown segment '#{seg}' in '#{path.join('.')}'"
+
+            puts "  Segment #{idx}: '#{seg}'" if ENV["DEBUG_ACCESSOR_OPS"]
+
+            # Validate required fields before using them
+            container = parent_meta&.[](:container)
+            enter_via = if is_root_segment?(idx)
+                          nil
+                        else
+                          node[:enter_via] do
+                            raise ArgumentError,
+                                  "Missing :enter_via for non-root segment '#{seg}' at '#{path.join('.')}'. Contract violation."
+                          end
+                        end
+
+            if container == :array
+              # Array parent: always step into elements first
+              ops << enter_array
+              puts "      Added: enter_array" if ENV["DEBUG_ACCESSOR_OPS"]
+
+              # Then either inline (no hash) or field hop to named member
+              if enter_via == :hash
+                ops << enter_hash(seg)
+                puts "      Added: enter_hash('#{seg}')" if ENV["DEBUG_ACCESSOR_OPS"]
+              elsif enter_via == :array
+                # Inline alias, no hash operation needed
+                puts "      Skipped enter_hash (inline alias)" if ENV["DEBUG_ACCESSOR_OPS"]
+              else
+                raise ArgumentError, "Invalid :enter_via '#{enter_via}' for array child '#{seg}'. Must be :hash or :array"
+              end
+            elsif container.nil? || container == :object
+              # Root or object parent - always emit enter_hash
+              ops << enter_hash(seg)
+              puts "      Added: enter_hash('#{seg}')" if ENV["DEBUG_ACCESSOR_OPS"]
+            else
+              raise ArgumentError, "Invalid parent :container '#{container}' for segment '#{seg}'. Expected :array, :object, or nil (root)"
+            end
+
+            parent_meta = node
+            cur = node[:children] || {}
+          end
+
+          terminal = parent_meta
+
+          if terminal && terminal[:container] == :array && %i[each_indexed ravel].include?(mode)
+            ops << enter_array
+            # :materialize and :read do not step into elements
+          end
+
+          # # If we land on an array and this mode iterates elements, step into it.
+          puts "  Final operations: #{ops.inspect}" if ENV["DEBUG_ACCESSOR_OPS"]
+
+          ops
+        end
+
+        def container_lineage(path)
+          lineage = []
+          cur = @meta
+          path.each do |seg|
+            m = ig(cur, seg)
+            container = m[:container] do
+              raise ArgumentError, "Missing :container for '#{seg}' in path '#{path.join('.')}'. Contract violation."
+            end
+            lineage << seg.to_sym if container == :array
+            cur = m[:children] || {}
+          end
+          lineage
+        end
+
+        def meta_node_for(path)
+          cur = @meta
+          last = nil
+          path.each do |seg|
+            m = ig(cur, seg)
+            last = m
+            cur = m[:children] || {}
+          end
+          last
+        end
+
+        def ensure_path!(path)
+          raise ArgumentError, "Unknown path: #{path.join('.')}" unless meta_node_for(path)
+        end
+
+        def ig(h, k)
+          h[k.to_sym] or raise ArgumentError, "Missing required field '#{k}' in metadata. Available keys: #{h.keys.inspect}"
+        end
+
+        def enter_hash(key)
+          { type: :enter_hash, key: key.to_s,
+            on_missing: @defaults[:on_missing], key_policy: @defaults[:key_policy] }
+        end
+
+        def enter_array
+          { type: :enter_array, on_missing: @defaults[:on_missing] }
+        end
+
+        def is_root_segment?(idx)
+          idx == 0
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/accessors/base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        module Base
+          MISSING = :__missing__
+
+          # -------- assertions --------
+          def assert_hash!(node, path_key, mode)
+            raise TypeError, "Expected Hash at '#{path_key}' (#{mode})" unless node.is_a?(Hash)
+          end
+
+          def assert_array!(node, path_key, mode)
+            return if node.is_a?(Array)
+
+            warn_mismatch(node, path_key) if ENV["DEBUG_ACCESS_BUILDER"]
+            raise TypeError, "Expected Array at '#{path_key}' (#{mode}); got #{node.class}"
+          end
+
+          def warn_mismatch(node, path_key)
+            puts "DEBUG AccessBuilder error at #{path_key}: got #{node.class}, value=#{node.inspect}"
+          end
+
+          # -------- key fetch with policy --------
+          def fetch_key(hash, key, policy)
+            case policy
+            when :indifferent
+              return hash[key] if hash.key?(key)
+              return hash[key.to_sym] if hash.key?(key.to_sym)
+              return hash[key.to_s]   if hash.key?(key.to_s)
+
+              MISSING
+            when :string
+              hash.key?(key.to_s) ? hash[key.to_s] : MISSING
+            when :symbol
+              hash.key?(key.to_sym) ? hash[key.to_sym] : MISSING
+            else
+              hash.key?(key) ? hash[key] : MISSING
+            end
+          end
+
+          # -------- op helpers --------
+          def next_enters_array?(operations, pc)
+            nxt = operations[pc + 1]
+            nxt && nxt[:type] == :enter_array
+          end
+
+          def missing_key_action(policy)
+            if policy == :nil
+              :yield_nil
+            else
+              (policy == :skip ? :skip : :raise)
+            end
+          end
+
+          def missing_array_action(policy)
+            if policy == :nil
+              :yield_nil
+            else
+              (policy == :skip ? :skip : :raise)
+            end
+          end
+        end
+      end
+    end
+  end
+end