kumi 0.0.20 → 0.0.22

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

@@ -1,907 +0,0 @@
-# frozen_string_literal: true
-
-module Kumi
-  module Core
-    module Analyzer
-      module Passes
-        # Lowers analyzed AST into Low-level IR for the VM
-        #
-        # INPUTS (from Analyzer state):
-        # - :evaluation_order   → topologically sorted declaration names
-        # - :declarations       → parsed & validated AST nodes
-        # - :access_plans       → AccessPlanner output (plan id, scope, depth, mode, operations)
-        # - :join_reduce_plans  → (optional) precomputed join/reduce strategy
-        # - :input_metadata     → normalized InputMeta tree
-        # - :scope_plans        → (optional) per-declaration scope hints
-        #
-        # OUTPUT:
-        # - :ir_module (Kumi::Core::IR::Module) with IR decls
-        #
-        # RESPONSIBILITIES:
-        # 1) Plan selection & LoadInput emission
-        #    - Choose the correct plan id for each input path:
-        #      * :read           → scalar fetch (no element traversal)
-        #      * :ravel          → leaf values, flattened over path’s array lineage
-        #      * :each_indexed   → vector fetch with hierarchical indices (for lineage)
-        #      * :materialize    → preserves nested structure (used when required)
-        #    - Set LoadInput attrs: scope:, is_scalar:, has_idx:
-        #      * is_scalar = (mode == :read || mode == :materialize)
-        #      * has_idx   = (mode == :each_indexed)
-        #
-        # 2) Shape tracking (SlotShape)
-        #    - Track the kind of every slot: Scalar vs Vec(scope, has_idx)
-        #    - Used to:
-        #      * decide when to emit AlignTo (automatic vector alignment)
-        #      * decide if the declaration needs a twin (:name__vec) + Lift
-        #
-        # 3) Automatic alignment for elementwise maps
-        #    - For Map(fn, args...):
-        #      * Find the carrier vector (max scope length among :elem params)
-        #      * If another arg is a vector with a compatible prefix scope, insert AlignTo(to_scope: carrier_scope)
-        #      * If incompatible, raise "cross-scope map without join"
-        #
-        # 4) Reducers & structure functions
-        #    - Reducers (e.g., sum, min, max, avg, count_if) lower to Reduce on the first vector arg
-        #    - Structure functions (e.g., size, flatten) are executed via Map unless explicitly marked reducer
-        #
-        # 5) Cascades & traits
-        #    - CascadeExpression lowered to nested `if` (switch) form
-        #    - Trait algebra remains purely boolean; no VM special-casing
-        #
-        # 6) Declaration twins & Lift
-        #    - If the final expression shape is a Vec with indices:
-        #      * Store to :name__vec (internal twin)
-        #      * Emit Lift(to_scope: vec.scope) to regroup rows into nested arrays
-        #      * Store lifted scalar to :name
-        #    - If scalar result: store only :name
-        #    - `DeclarationReference` resolves to :name__vec when a vector is required downstream
-        #
-        # INVARIANTS:
-        # - All structural intent (vectorization, grouping, alignment) is decided during lowering.
-        # - VM is mechanical; it does not sniff types or infer structure.
-        # - AlignTo requires prefix-compatible scopes; otherwise we error early.
-        # - Lift consumes a Vec with indices and returns a Scalar(nested_array) by grouping rows with `group_rows`.
-        #
-        # DEBUGGING:
-        # - Set DEBUG_LOWER=1 to print per-declaration IR ops and alignment decisions.
-        SlotShape = Struct.new(:kind, :scope, :has_idx) do
-          def self.scalar
-            new(:scalar, [], false)
-          end
-
-          def self.vec(scope, has_idx: true)
-            new(:vec, Array(scope), has_idx)
-          end
-        end
-
-        class LowerToIRPass < PassBase
-          def run(errors)
-            @vec_names = Set.new
-            @vec_meta = {}
-
-            evaluation_order = get_state(:evaluation_order, required: true)
-            declarations = get_state(:declarations, required: true)
-            access_plans = get_state(:access_plans, required: true)
-            join_reduce_plans = get_state(:join_reduce_plans, required: false) || {}
-            input_metadata = get_state(:input_metadata, required: true)
-            scope_plans = get_state(:scope_plans, required: false) || {}
-
-            ir_decls = []
-
-            @join_reduce_plans = join_reduce_plans
-            @declarations = declarations
-
-            evaluation_order.each do |name|
-              decl = declarations[name]
-              next unless decl
-
-              begin
-                scope_plan = scope_plans[name]
-                @current_decl = name
-                @lower_cache  = {} # reset per declaration
-
-                ir_decl = lower_declaration(name, decl, access_plans, join_reduce_plans, scope_plan)
-                ir_decls << ir_decl
-              rescue StandardError => e
-                location = decl.respond_to?(:loc) ? decl.loc : nil
-                backtrace = e.backtrace.first(5).join("\n")
-                message = "Failed to lower declaration #{name}: #{e.message}\n#{backtrace}"
-                add_error(errors, location, "Failed to lower declaration #{name}: #{message}")
-              end
-            end
-
-            if ENV["DEBUG_LOWER"]
-              puts "DEBUG eval order: #{evaluation_order.inspect}"
-              puts "DEBUG ir decl order: #{ir_decls.map(&:name).inspect}"
-            end
-            order_index = evaluation_order.each_with_index.to_h
-            ir_decls.sort_by! { |d| order_index.fetch(d.name, Float::INFINITY) }
-
-            ir_module = Kumi::Core::IR::Module.new(
-              inputs: input_metadata,
-              decls: ir_decls
-            )
-
-            if ENV["DEBUG_LOWER"]
-              puts "DEBUG Lowered IR Module:"
-              ir_module.decls.each do |decl|
-                puts "  Declaration: #{decl.name} (#{decl.kind})"
-                decl.ops.each_with_index do |op, i|
-                  puts "    Op#{i}: #{op.tag} #{op.attrs.inspect} args=#{op.args.inspect}"
-                end
-              end
-            end
-
-            if ENV["DUMP_IR"]
-              # Collect analysis state that this pass actually uses
-              analysis_state = {
-                evaluation_order: evaluation_order,
-                declarations: declarations,
-                access_plans: access_plans,
-                join_reduce_plans: join_reduce_plans,
-                scope_plans: scope_plans,
-                input_metadata: input_metadata,
-                vec_names: @vec_names,
-                vec_meta: @vec_meta,
-                inferred_types: get_state(:inferred_types, required: false) || {}
-              }
-
-              pretty_ir = Kumi::Support::IRDump.pretty_print(ir_module, analysis_state: analysis_state)
-              File.write(ENV["DUMP_IR"], pretty_ir)
-              puts "DEBUG IR dumped to #{ENV['DUMP_IR']}"
-            end
-
-            state.with(:ir_module, ir_module)
-          end
-
-          private
-
-          def determine_slot_shape(slot, ops, access_plans)
-            return SlotShape.scalar if slot.nil?
-
-            op = ops[slot]
-
-            case op.tag
-            when :const
-              SlotShape.scalar
-
-            when :load_input
-              if op.attrs[:is_scalar]
-                SlotShape.scalar
-              else
-                plan_id = op.attrs[:plan_id]
-                plan = access_plans.values.flatten.find { |p| p.accessor_key == plan_id }
-                SlotShape.vec(op.attrs[:scope] || [], has_idx: plan&.mode == :each_indexed)
-              end
-
-            when :array
-              arg_shapes = op.args.map { |i| determine_slot_shape(i, ops, access_plans) }
-              return SlotShape.scalar if arg_shapes.all? { |s| s.kind == :scalar }
-
-              carrier = arg_shapes.select { |s| s.kind == :vec }.max_by { |s| s.scope.length }
-              SlotShape.vec(carrier.scope, has_idx: carrier.has_idx)
-
-            when :map
-              arg_shapes = op.args.map { |i| determine_slot_shape(i, ops, access_plans) }
-              return SlotShape.scalar if arg_shapes.all? { |s| s.kind == :scalar }
-
-              carrier = arg_shapes.select { |s| s.kind == :vec }.max_by { |s| s.scope.length }
-              SlotShape.vec(carrier.scope, has_idx: carrier.has_idx)
-
-            when :align_to
-              SlotShape.vec(op.attrs[:to_scope], has_idx: true)
-
-            when :reduce
-              rs = Array(op.attrs[:result_scope] || [])
-              rs.empty? ? SlotShape.scalar : SlotShape.vec(rs, has_idx: true)
-            when :switch
-              branch_shapes =
-                op.attrs[:cases].map { |(_, v)| determine_slot_shape(v, ops, access_plans) } +
-                [determine_slot_shape(op.attrs[:default], ops, access_plans)]
-              if (vec = branch_shapes.find { |s| s.kind == :vec })
-                SlotShape.vec(vec.scope, has_idx: vec.has_idx)
-              else
-                SlotShape.scalar
-              end
-
-            when :ref
-              if (m = @vec_meta && @vec_meta[op.attrs[:name]])
-                SlotShape.vec(m[:scope], has_idx: m[:has_idx])
-              else
-                SlotShape.scalar
-              end
-
-            else
-              raise "Op `#{op.tag}` not supported"
-            end
-          end
-
-          def insert_align_to_if_needed(arg_slots, ops, access_plans, on_missing: :error)
-            shapes = arg_slots.map { |s| determine_slot_shape(s, ops, access_plans) }
-
-            vec_is = arg_slots.each_index.select { |i| shapes[i].kind == :vec }
-            return arg_slots if vec_is.size < 2
-
-            carrier_i = vec_is.max_by { |i| shapes[i].scope.length }
-            carrier_scope = shapes[carrier_i].scope
-            carrier_slot  = arg_slots[carrier_i]
-
-            aligned = arg_slots.dup
-            vec_is.each do |i|
-              next if shapes[i].scope == carrier_scope
-
-              short, long = [shapes[i].scope, carrier_scope].sort_by(&:length)
-              unless long.first(short.length) == short
-                raise "cross-scope map without join: #{shapes[i].scope.inspect} vs #{carrier_scope.inspect}"
-              end
-
-              src_slot = aligned[i] # <- chain on the current slot, not the original
-              op = Kumi::Core::IR::Ops.AlignTo(
-                carrier_slot, src_slot,
-                to_scope: carrier_scope, require_unique: true, on_missing: on_missing
-              )
-              ops << op
-              aligned[i] = ops.size - 1
-            end
-
-            aligned
-          end
-
-          def apply_scalar_to_vector_broadcast(scalar_slot, target_scope, ops, access_plans)
-            # Create a carrier vector at the target scope by loading the appropriate input
-            # For scope [:items], we need to load the items array to get the vector shape
-            if target_scope.empty?
-              puts "DEBUG: Empty target scope, returning scalar" if ENV["DEBUG_BROADCAST"]
-              return scalar_slot # Can't broadcast to empty scope
-            end
-
-            # Create a load operation for the target scope to get vector shape
-            # For [:items] scope, load the items array
-            # Access plans are keyed by strings, not arrays
-            if target_scope.length == 1
-              input_key = target_scope.first.to_s
-              plans = access_plans[input_key]
-              puts "DEBUG: Looking for plans for #{input_key.inspect}, found: #{plans&.length || 0} plans" if ENV["DEBUG_BROADCAST"]
-            else
-              puts "DEBUG: Complex target scope #{target_scope.inspect}, not supported yet" if ENV["DEBUG_BROADCAST"]
-              return scalar_slot
-            end
-
-            if plans&.any?
-              # Find an indexed plan that gives us the vector shape
-              indexed_plan = plans.find { |p| p.mode == :each_indexed }
-              puts "DEBUG: Indexed plan found: #{indexed_plan.inspect}" if ENV["DEBUG_BROADCAST"] && indexed_plan
-              if indexed_plan
-                # Load the input to create a carrier vector
-                ops << Kumi::Core::IR::Ops.LoadInput(indexed_plan.accessor_key, scope: indexed_plan.scope, has_idx: true)
-                carrier_slot = ops.size - 1
-                puts "DEBUG: Created carrier at slot #{carrier_slot}" if ENV["DEBUG_BROADCAST"]
-
-                # Now broadcast scalar against the carrier - use first arg from carrier, rest from scalar
-                ops << Kumi::Core::IR::Ops.Map(:if, 3, carrier_slot, scalar_slot, scalar_slot)
-                result_slot = ops.size - 1
-                puts "DEBUG: Created broadcast MAP at slot #{result_slot}" if ENV["DEBUG_BROADCAST"]
-                result_slot
-              else
-                puts "DEBUG: No indexed plan found, returning scalar" if ENV["DEBUG_BROADCAST"]
-                # No indexed plan available, return scalar as-is
-                scalar_slot
-              end
-            else
-              puts "DEBUG: No access plans found, returning scalar" if ENV["DEBUG_BROADCAST"]
-              # No access plans for target scope, return scalar as-is
-              scalar_slot
-            end
-          end
-
-          def lower_declaration(name, decl, access_plans, _join_reduce_plans, scope_plan)
-            ops = []
-
-            plan = @join_reduce_plans[name]
-            req_scope =
-              if plan && plan.respond_to?(:result_scope)
-                Array(plan.result_scope) # [] for full reduction, [:players] for per-player, etc.
-              elsif plan && plan.respond_to?(:policy) && plan.policy == :broadcast
-                Array(plan.target_scope) # Broadcast to target scope
-              elsif top_level_reducer?(decl)
-                [] # collapse all axes by default
-              else
-                scope_plan&.scope # fallback (vector values, arrays, etc.)
-              end
-
-            last_slot = lower_expression(decl.expression, ops, access_plans, scope_plan,
-                                         true, req_scope)
-
-            # Apply broadcasting for scalar-to-vector join plans
-            if plan && plan.respond_to?(:policy) && plan.policy == :broadcast
-              puts "DEBUG: Applying scalar broadcast for #{name} to scope #{plan.target_scope.inspect}" if ENV["DEBUG_BROADCAST"]
-              last_slot = apply_scalar_to_vector_broadcast(last_slot, plan.target_scope, ops, access_plans)
-              puts "DEBUG: Broadcast result slot: #{last_slot}" if ENV["DEBUG_BROADCAST"]
-            end
-
-            shape = determine_slot_shape(last_slot, ops, access_plans)
-            puts "DEBUG: Shape after broadcast for #{name}: #{shape.inspect}" if ENV["DEBUG_BROADCAST"]
-
-            if shape.kind == :vec
-              vec_name = :"#{name}__vec"
-              @vec_meta[vec_name] = { scope: shape.scope, has_idx: shape.has_idx }
-
-              # internal twin for downstream refs
-              ops << Kumi::Core::IR::Ops.Store(vec_name, last_slot)
-
-              # public presentation
-              ops << if shape.has_idx
-                       Kumi::Core::IR::Ops.Lift(shape.scope, last_slot)
-                     else
-                       Kumi::Core::IR::Ops.Reduce(:to_array, [], [], [], last_slot)
-                     end
-              last_slot = ops.size - 1
-            end
-
-            # ➌ store public name (scalar or transformed vec)
-            ops << Kumi::Core::IR::Ops.Store(name, last_slot)
-
-            Kumi::Core::IR::Decl.new(
-              name: name,
-              kind: decl.is_a?(Syntax::ValueDeclaration) ? :value : :trait,
-              shape: (shape.kind == :vec ? :vec : :scalar),
-              ops: ops
-            )
-          end
-
-          # Lowers an analyzed AST node into IR ops and returns the slot index.
-          # - ops: mutable IR ops array (per-declaration)
-          # - need_indices: whether to prefer :each_indexed plan for inputs
-          # - required_scope: consumer-required scope (guides grouped reductions)
-          # - cacheable: whether this lowering may be cached (branch bodies under guards: false)
-          def lower_expression(expr, ops, access_plans, scope_plan, need_indices, required_scope = nil, cacheable: true)
-            @lower_cache ||= {}
-            key = [@current_decl, expr.object_id, Array(required_scope), !!need_indices]
-            if cacheable && (hit = @lower_cache[key])
-              return hit
-            end
-
-            if ENV["DEBUG_LOWER"] && expr.is_a?(Syntax::CallExpression)
-              puts "  LOWER_EXPR[#{@current_decl}] #{expr.fn_name}(#{expr.args.size} args) req_scope=#{required_scope.inspect}"
-            end
-
-            slot =
-              case expr
-              when Syntax::Literal
-                ops << Kumi::Core::IR::Ops.Const(expr.value)
-                ops.size - 1
-
-              when Syntax::InputReference
-                plan_id = pick_plan_id_for_input([expr.name], access_plans,
-                                                 scope_plan: scope_plan, need_indices: need_indices)
-
-                plans    = access_plans.fetch(expr.name.to_s, [])
-                selected = plans.find { |p| p.accessor_key == plan_id }
-                scope    = selected ? selected.scope : []
-                is_scalar = selected && %i[read materialize].include?(selected.mode)
-                has_idx   = selected && selected.mode == :each_indexed
-                ops << Kumi::Core::IR::Ops.LoadInput(plan_id, scope: scope, is_scalar: is_scalar, has_idx: has_idx)
-                ops.size - 1
-
-              when Syntax::InputElementReference
-                plan_id = pick_plan_id_for_input(expr.path, access_plans,
-                                                 scope_plan: scope_plan, need_indices: need_indices)
-                path_str = expr.path.join(".")
-                plans    = access_plans.fetch(path_str, [])
-                selected = plans.find { |p| p.accessor_key == plan_id }
-                scope    = selected ? selected.scope : []
-                is_scalar = selected && %i[read materialize].include?(selected.mode)
-                has_idx   = selected && selected.mode == :each_indexed
-                ops << Kumi::Core::IR::Ops.LoadInput(plan_id, scope: scope, is_scalar: is_scalar, has_idx: has_idx)
-                ops.size - 1
-
-              when Syntax::DeclarationReference
-                # Check if this declaration has a vectorized twin at the required scope
-                twin = :"#{expr.name}__vec"
-                twin_meta = @vec_meta && @vec_meta[twin]
-
-                if required_scope && !Array(required_scope).empty?
-                  # Consumer needs a grouped view of this declaration.
-                  if twin_meta && twin_meta[:scope] == Array(required_scope)
-                    # We have a vectorized twin at exactly the required scope - use it!
-                    ops << Kumi::Core::IR::Ops.Ref(twin)
-                    return ops.size - 1
-                  else
-                    # Need to inline re-lower the referenced declaration's *expression*,
-                    # forcing indices, and grouping to the requested scope.
-                    decl = @declarations.fetch(expr.name) { raise "unknown decl #{expr.name}" }
-                    slot = lower_expression(decl.expression, ops, access_plans, scope_plan,
-                                            true,                    # need_indices (grouping requires indexed source)
-                                            required_scope,          # group-to scope
-                                            cacheable: true)         # per-decl slot cache will dedupe
-                    return slot
-                  end
-                else
-                  # Plain (scalar) use, or already-materialized vec twin
-                  ref  = twin_meta ? twin : expr.name
-                  ops << Kumi::Core::IR::Ops.Ref(ref)
-                  return ops.size - 1
-                end
-
-              when Syntax::CallExpression
-                entry = Kumi::Registry.entry(expr.fn_name)
-
-                # Constant folding optimization: evaluate expressions with all literal arguments
-                if can_constant_fold?(expr, entry)
-                  folded_value = constant_fold(expr, entry)
-                  ops << Kumi::Core::IR::Ops.Const(folded_value)
-                  return ops.size - 1
-                end
-
-                if ENV["DEBUG_LOWER"] && has_nested_reducer?(expr)
-                  puts "  NESTED_REDUCER_DETECTED in #{expr.fn_name} with req_scope=#{required_scope.inspect}"
-                end
-
-                # Special handling for comparison operations containing nested reductions
-                if !entry&.reducer && has_nested_reducer?(expr)
-                  puts "  SPECIAL_NESTED_REDUCTION_HANDLING for #{expr.fn_name}" if ENV["DEBUG_LOWER"]
-
-                  # For comparison ops with nested reducers, we need to ensure
-                  # the nested reducer gets the right required_scope (per-player)
-                  # instead of the full dimensional scope from infer_expr_scope
-                  plan = @join_reduce_plans[@current_decl]
-                  target_scope = if plan.is_a?(Kumi::Core::Analyzer::Plans::Reduce) && plan.result_scope && !plan.result_scope.empty?
-                                   plan.result_scope
-                                 elsif required_scope && !required_scope.empty?
-                                   required_scope
-                                 else
-                                   []
-                                 end
-
-                  puts "  NESTED_REDUCTION target_scope=#{target_scope.inspect}" if ENV["DEBUG_LOWER"]
-
-                  # Lower arguments with the correct scope for nested reducers
-                  arg_slots = expr.args.map do |a|
-                    lower_expression(a, ops, access_plans, scope_plan,
-                                     need_indices, target_scope, cacheable: cacheable)
-                  end
-
-                  aligned = target_scope.empty? ? arg_slots : insert_align_to_if_needed(arg_slots, ops, access_plans, on_missing: :error)
-                  ops << Kumi::Core::IR::Ops.Map(expr.fn_name, expr.args.size, *aligned)
-                  return ops.size - 1
-
-                elsif entry&.reducer
-                  # Need indices iff grouping is requested
-                  child_need_idx = !Array(required_scope).empty?
-
-                  arg_slots = expr.args.map do |a|
-                    lower_expression(a, ops, access_plans, scope_plan,
-                                     child_need_idx,                  # <<< important
-                                     nil,                             # children of reducer don't inherit grouping
-                                     cacheable: true)
-                  end
-                  vec_i = arg_slots.index { |s| determine_slot_shape(s, ops, access_plans).kind == :vec }
-                  if vec_i
-                    src_slot  = arg_slots[vec_i]
-                    src_shape = determine_slot_shape(src_slot, ops, access_plans)
-
-                    # If grouping requested but source lacks indices (e.g. cached ravel), reload it with indices
-                    if !Array(required_scope).empty? && !src_shape.has_idx
-                      src_slot  = lower_expression(expr.args[vec_i], ops, access_plans, scope_plan,
-                                                   true, # force indices
-                                                   nil,
-                                                   cacheable: true)
-                      src_shape = determine_slot_shape(src_slot, ops, access_plans)
-                    end
-
-                    if ENV["DEBUG_LOWER"]
-                      puts "  emit_reduce(#{expr.fn_name}, #{src_slot}, #{src_shape.scope.inspect}, #{Array(required_scope).inspect})"
-                    end
-                    return emit_reduce(ops, expr.fn_name, src_slot, src_shape.scope, required_scope)
-                  else
-                    ops << Kumi::Core::IR::Ops.Map(expr.fn_name, arg_slots.size, *arg_slots)
-                    return ops.size - 1
-                  end
-                end
-
-                # non-reducer path unchanged…
-
-                # Non-reducer: pointwise. Choose carrier = deepest vec among args.
-                target = infer_expr_scope(expr, access_plans) # static, no ops emitted
-                arg_slots = expr.args.map do |a|
-                  lower_expression(a, ops, access_plans, scope_plan,
-                                   need_indices, target, cacheable: cacheable)
-                end
-                aligned = insert_align_to_if_needed(arg_slots, ops, access_plans, on_missing: :error)
-                ops << Kumi::Core::IR::Ops.Map(expr.fn_name, expr.args.size, *aligned)
-                ops.size - 1
-
-              when Syntax::ArrayExpression
-                target = infer_expr_scope(expr, access_plans) # LUB across children
-                puts "DEBUG array target scope=#{target.inspect}" if ENV["DEBUG_LOWER"]
-                elem_slots = expr.elements.map do |e|
-                  lower_expression(e, ops, access_plans, scope_plan,
-                                   need_indices,                   # pass-through
-                                   target,                         # <<< required_scope = target
-                                   cacheable: true)
-                end
-                elem_slots = insert_align_to_if_needed(elem_slots, ops, access_plans, on_missing: :error) unless target.empty?
-                ops << Kumi::Core::IR::Ops.Array(elem_slots.size, *elem_slots)
-                return ops.size - 1
-              when Syntax::HashExpression
-                # Skip
-
-              when Syntax::CascadeExpression
-                # Find a base (true) case, if present
-                base_case    = expr.cases.find { |c| c.condition.is_a?(Syntax::Literal) && c.condition.value == true }
-                default_expr = base_case ? base_case.result : Kumi::Syntax::Literal.new(nil)
-                branches     = expr.cases.reject { |c| c.equal?(base_case) }
-
-                # Lower each condition once to probe shapes (cacheable)
-                precond_slots  = branches.map do |c|
-                  lower_expression(c.condition, ops, access_plans, scope_plan,
-                                   need_indices, nil, cacheable: cacheable)
-                end
-                precond_shapes = precond_slots.map { |s| determine_slot_shape(s, ops, access_plans) }
-                vec_cond_is    = precond_shapes.each_index.select { |i| precond_shapes[i].kind == :vec }
-
-                # Tiny helpers for boolean maps
-                map1 = lambda { |fn, a|
-                  ops << Kumi::Core::IR::Ops.Map(fn, 1, a)
-                  ops.size - 1
-                }
-                map2 = lambda { |fn, a, b|
-                  ops << Kumi::Core::IR::Ops.Map(fn, 2, a, b)
-                  ops.size - 1
-                }
-
-                if vec_cond_is.empty?
-                  # ------------------------------------------------------------------
-                  # SCALAR CASCADE (lazy): evaluate branch bodies under guards
-                  # ------------------------------------------------------------------
-                  any_prev_true = lower_expression(Kumi::Syntax::Literal.new(false), ops, access_plans,
-                                                   scope_plan, need_indices, nil, cacheable: false)
-
-                  cases_attr = [] # [[cond_slot, value_slot], ...]
-
-                  branches.each_with_index do |c, i|
-                    not_any = map1.call(:not, any_prev_true)
-                    guard_i = map2.call(:and, not_any, precond_slots[i])
-
-                    ops << Kumi::Core::IR::Ops.GuardPush(guard_i)
-                    val_slot = lower_expression(c.result, ops, access_plans, scope_plan,
-                                                need_indices, nil, cacheable: false)
-                    ops << Kumi::Core::IR::Ops.GuardPop
-
-                    cases_attr << [precond_slots[i], val_slot]
-                    any_prev_true = map2.call(:or, any_prev_true, precond_slots[i])
-                  end
-
-                  not_any = map1.call(:not, any_prev_true)
-                  ops << Kumi::Core::IR::Ops.GuardPush(not_any)
-                  default_slot = lower_expression(default_expr, ops, access_plans, scope_plan,
-                                                  need_indices, nil, cacheable: false)
-                  ops << Kumi::Core::IR::Ops.GuardPop
-
-                  ops << Kumi::Core::IR::Ops.Switch(cases_attr, default_slot)
-                  ops.size - 1
-                else
-                  # -------------------------
-                  # VECTOR CASCADE (per-row lazy)
-                  # -------------------------
-
-                  # First lower raw conditions to peek at shapes.
-                  raw_cond_slots = branches.map do |c|
-                    lower_expression(c.condition, ops, access_plans, scope_plan,
-                                     need_indices, nil, cacheable: true)
-                  end
-                  raw_shapes     = raw_cond_slots.map { |s| determine_slot_shape(s, ops, access_plans) }
-                  vec_is         = raw_shapes.each_index.select { |i| raw_shapes[i].kind == :vec }
-
-                  # Choose cascade_scope: prefer scope_plan (from scope resolution),
-                  # fallback to LUB of vector condition scopes.
-                  if scope_plan && !scope_plan.scope.nil? && !scope_plan.scope.empty?
-                    cascade_scope = Array(scope_plan.scope)
-                  else
-                    candidate_scopes = vec_is.map { |i| raw_shapes[i].scope }
-                    cascade_scope    = lub_scopes(candidate_scopes)
-                    cascade_scope    = [] if cascade_scope.nil?
-                  end
-
-                  # Re-lower each condition *properly* at cascade_scope (reproject deeper ones).
-                  conds_at_scope = branches.map do |c|
-                    lower_cascade_pred(c.condition, cascade_scope, ops, access_plans, scope_plan)
-                  end
-
-                  # Booleans utilities
-                  map1 = lambda { |fn, a|
-                    ops << Kumi::Core::IR::Ops.Map(fn, 1, a)
-                    ops.size - 1
-                  }
-                  map2 = lambda { |fn, a, b|
-                    ops << Kumi::Core::IR::Ops.Map(fn, 2, a, b)
-                    ops.size - 1
-                  }
-
-                  # Build lazy guards per branch at cascade_scope
-                  any_prev = lower_expression(Kumi::Syntax::Literal.new(false), ops, access_plans,
-                                              scope_plan, need_indices, nil, cacheable: false)
-                  val_slots = []
-
-                  branches.each_with_index do |c, i|
-                    not_prev = map1.call(:not, any_prev)
-                    need_i = map2.call(:and, not_prev, conds_at_scope[i]) # @ cascade_scope
-
-                    ops << Kumi::Core::IR::Ops.GuardPush(need_i)
-                    vslot = lower_expression(c.result, ops, access_plans, scope_plan,
-                                             need_indices, cascade_scope, cacheable: false)
-                    # ensure vector results live at cascade_scope
-                    vslot = align_to_cascade_if_vec(vslot, cascade_scope, ops, access_plans)
-                    ops << Kumi::Core::IR::Ops.GuardPop
-
-                    val_slots << vslot
-                    any_prev = map2.call(:or, any_prev, conds_at_scope[i]) # still @ cascade_scope
-                  end
-
-                  # Default branch
-                  not_prev = map1.call(:not, any_prev)
-                  ops << Kumi::Core::IR::Ops.GuardPush(not_prev)
-                  default_slot = lower_expression(default_expr, ops, access_plans, scope_plan,
-                                                  need_indices, cascade_scope, cacheable: false)
-                  default_slot = align_to_cascade_if_vec(default_slot, cascade_scope, ops, access_plans)
-                  ops << Kumi::Core::IR::Ops.GuardPop
-
-                  # Assemble via nested element-wise selection
-                  nested = default_slot
-                  (branches.length - 1).downto(0) do |i|
-                    ops << Kumi::Core::IR::Ops.Map(:if, 3, conds_at_scope[i], val_slots[i], nested)
-                    nested = ops.size - 1
-                  end
-                  nested
-
-                end
-
-              else
-                raise "Unsupported expression type: #{expr.class.name}"
-              end
-
-            @lower_cache[key] = slot if cacheable
-            slot
-          end
-
-          def pick_plan_id_for_input(path, access_plans, scope_plan:, need_indices:)
-            path_str = path.join(".")
-            plans = access_plans.fetch(path_str) { raise "No access plan for #{path_str}" }
-            depth = plans.first.depth
-            if depth > 0
-              mode = need_indices ? :each_indexed : :ravel
-              plans.find { |p| p.mode == mode }&.accessor_key or
-                raise("No #{mode.inspect} plan for #{path_str}")
-            else
-              plans.find { |p| p.mode == :read }&.accessor_key or
-                raise("No :read plan for #{path_str}")
-            end
-          end
-
-          def align_to_cascade_if_vec(slot, cascade_scope, ops, access_plans)
-            sh = determine_slot_shape(slot, ops, access_plans)
-            return slot if sh.kind == :scalar && cascade_scope.empty? # scalar cascade, keep scalar
-            return slot if sh.scope == cascade_scope
-
-            # Handle scalar-to-vector broadcasting for vectorized cascades
-            if sh.kind == :scalar && !cascade_scope.empty?
-              # Find a carrier vector at cascade scope to broadcast scalar against
-              target_slot = nil
-              ops.each_with_index do |op, i|
-                next unless %i[load_input map].include?(op.tag)
-
-                shape = determine_slot_shape(i, ops, access_plans)
-                if shape.kind == :vec && shape.scope == cascade_scope && shape.has_idx
-                  target_slot = i
-                  break
-                end
-              end
-
-              raise "Cannot broadcast scalar to cascade scope #{cascade_scope.inspect} - no carrier vector found" unless target_slot
-
-              # Use MAP with a special broadcast function - but first I need to create one
-              # For now, let's try using the 'if' function to broadcast: if(true, scalar, carrier) -> broadcasts scalar
-              const_true = ops.size
-              ops << Kumi::Core::IR::Ops.Const(true)
-
-              ops << Kumi::Core::IR::Ops.Map(:if, 3, const_true, slot, target_slot)
-              return ops.size - 1
-
-              # No carrier found, can't broadcast
-
-            end
-
-            short, long = [sh.scope, cascade_scope].sort_by(&:length)
-            unless long.first(short.length) == short
-              raise "cascade branch result scope #{sh.scope.inspect} not compatible with cascade scope #{cascade_scope.inspect}"
-            end
-
-            raise "unsupported cascade scope #{cascade_scope.inspect} for slot #{slot}" if cascade_scope.empty?
-          end
-
-          def prefix?(short, long)
-            long.first(short.length) == short
-          end
-
-          def infer_expr_scope(expr, access_plans)
-            case expr
-            when Syntax::DeclarationReference
-              meta = @vec_meta && @vec_meta[:"#{expr.name}__vec"]
-              meta ? Array(meta[:scope]) : []
-            when Syntax::InputElementReference
-              key  = expr.path.join(".")
-              plan = access_plans.fetch(key, []).find { |p| p.mode == :each_indexed }
-              plan ? Array(plan.scope) : []
-            when Syntax::InputReference
-              plans = access_plans.fetch(expr.name.to_s, [])
-              plan  = plans.find { |p| p.mode == :each_indexed }
-              plan ? Array(plan.scope) : []
-            when Syntax::CallExpression
-              # reducers: use source vec scope; non-reducers: deepest carrier among args
-              scopes = expr.args.map { |a| infer_expr_scope(a, access_plans) }
-              scopes.max_by(&:length) || []
-            when Syntax::ArrayExpression
-              scopes = expr.elements.map { |e| infer_expr_scope(e, access_plans) }
-              lub_scopes(scopes) # <-- important
-            else
-              []
-            end
-          end
-
-          def lower_cascade_pred(cond, cascade_scope, ops, access_plans, scope_plan)
-            case cond
-            when Syntax::DeclarationReference
-              # Check if this declaration has a vectorized twin at the required scope
-              twin = :"#{cond.name}__vec"
-              twin_meta = @vec_meta && @vec_meta[twin]
-
-              raise "Missing cascade_scope" unless cascade_scope && !Array(cascade_scope).empty?
-
-              # Consumer needs a grouped view of this declaration.
-              if twin_meta && twin_meta[:scope] == Array(cascade_scope)
-                # We have a vectorized twin at exactly the required scope - use it!
-                ops << Kumi::Core::IR::Ops.Ref(twin)
-                ops.size - 1
-              else
-                # Need to inline re-lower the referenced declaration's *expression*
-                decl = @declarations.fetch(cond.name) { raise "unknown decl #{cond.name}" }
-                slot = lower_expression(decl.expression, ops, access_plans, scope_plan,
-                                        true, Array(cascade_scope), cacheable: true)
-                project_mask_to_scope(slot, cascade_scope, ops, access_plans)
-              end
-            when Syntax::CallExpression
-              parts = cond.args.map { |a| lower_cascade_pred(a, cascade_scope, ops, access_plans, scope_plan) }
-              # They’re all @ cascade_scope (or scalar) now; align scalars broadcast, vecs already match.
-              parts.reduce do |acc, s|
-                ops << Kumi::Core::IR::Ops.Map(:and, 2, acc, s)
-                ops.size - 1
-              end
-            else
-              raise "Unexpected Expression #{cond.class} in Cascade"
-            end
-          end
-
-          def common_prefix(a, b)
-            a = Array(a)
-            b = Array(b)
-            i = 0
-            i += 1 while i < a.length && i < b.length && a[i] == b[i]
-            a.first(i)
-          end
-
-          def lub_scopes(scopes)
-            scopes = scopes.reject { |s| s.nil? || s.empty? }
-            return [] if scopes.empty?
-
-            scopes.reduce(scopes.first) { |acc, s| common_prefix(acc, s) }
-          end
-
-          def emit_reduce(ops, fn_name, src_slot, src_scope, required_scope)
-            rs = Array(required_scope || [])
-            ss = Array(src_scope)
-
-            # No-op: grouping to full source scope
-            return src_slot if !rs.empty? && rs == ss
-
-            axis = rs.empty? ? ss : (ss - rs)
-            puts "  emit_reduce #{fn_name} on #{src_slot} with axis #{axis.inspect} and result scope #{rs.inspect}" if ENV["DEBUG_LOWER"]
-            ops << Kumi::Core::IR::Ops.Reduce(fn_name, axis, rs, [], src_slot)
-            ops.size - 1
-          end
-
-          def vec_twin_name(base, scope)
-            scope_tag = Array(scope).map(&:to_s).join("_") # e.g. "players"
-            :"#{base}__vec__#{scope_tag}"
-          end
-
-          def find_vec_twin(name, scope)
-            t = vec_twin_name(name, scope)
-            @vec_meta[t] ? t : nil
-          end
-
-          def top_level_reducer?(decl)
-            ce = decl.expression
-            return false unless ce.is_a?(Kumi::Syntax::CallExpression)
-
-            entry = Kumi::Registry.entry(ce.fn_name)
-            entry&.reducer && !entry&.structure_function
-          end
-
-          def has_nested_reducer?(expr)
-            return false unless expr.is_a?(Kumi::Syntax::CallExpression)
-
-            expr.args.any? do |arg|
-              case arg
-              when Kumi::Syntax::CallExpression
-                entry = Kumi::Registry.entry(arg.fn_name)
-                return true if entry&.reducer
-
-                has_nested_reducer?(arg) # recursive check
-              else
-                false
-              end
-            end
-          end
-
-          # Make sure a boolean mask lives at exactly cascade_scope.
-          def project_mask_to_scope(slot, cascade_scope, ops, access_plans)
-            sh = determine_slot_shape(slot, ops, access_plans)
-            return slot if sh.scope == cascade_scope
-            return slot if sh.kind == :scalar
-
-            cascade_scope = Array(cascade_scope)
-            slot_scope = Array(sh.scope)
-
-            # Check prefix compatibility
-            short, long = [cascade_scope, slot_scope].sort_by(&:length)
-            unless long.first(short.length) == short
-              raise "cascade condition scope #{slot_scope.inspect} is not prefix-compatible with #{cascade_scope.inspect}"
-            end
-
-            return unless slot_scope.length < cascade_scope.length
-
-            # Need to broadcast UP: slot scope is shorter, needs to be aligned to cascade scope
-            # Find a target vector that already has the cascade scope
-            target_slot = nil
-            ops.each_with_index do |op, i|
-              next unless %i[load_input map].include?(op.tag)
-
-              shape = determine_slot_shape(i, ops, access_plans)
-              if shape.kind == :vec && shape.scope == cascade_scope && shape.has_idx
-                target_slot = i
-                break
-              end
-            end
-
-            ops << Kumi::Core::IR::Ops.AlignTo(target_slot, slot, to_scope: cascade_scope, on_missing: :error, require_unique: true)
-            ops.size - 1
-          end
-
-          # Constant folding optimization helpers
-          def can_constant_fold?(expr, entry)
-            return false unless entry&.fn # Skip if function not found
-            return false if entry.reducer # Skip reducer functions for now
-            return false if expr.args.empty? # Need at least one argument
-
-            # Check if all arguments are literals
-            expr.args.all? { |arg| arg.is_a?(Syntax::Literal) }
-          end
-
-          def constant_fold(expr, entry)
-            literal_values = expr.args.map(&:value)
-
-            begin
-              # Call the function with literal values at compile time
-              entry.fn.call(*literal_values)
-            rescue StandardError => e
-              # If constant folding fails, fall back to runtime evaluation
-              # This shouldn't happen with pure functions, but be defensive
-              puts "Constant folding failed for #{expr.fn_name}: #{e.message}" if ENV["DEBUG_LOWER"]
-              raise "Cannot constant fold #{expr.fn_name}: #{e.message}"
-            end
-          end
-        end
-      end
-    end
-  end
-end