kumi 0.0.9 → 0.0.11

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

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module IR
+      module ExecutionEngine
+        # Interpreter for IR modules - thin layer that delegates to combinators
+        module Interpreter
+          PRODUCES_SLOT = %i[const load_input ref array map reduce lift align_to switch].freeze
+          NON_PRODUCERS = %i[guard_push guard_pop assign store].freeze
+
+          def self.run(ir_module, ctx, accessors:, registry:)
+            # Validate registry is properly initialized
+            raise ArgumentError, "Registry cannot be nil" if registry.nil?
+            raise ArgumentError, "Registry must be a Hash, got #{registry.class}" unless registry.is_a?(Hash)
+
+            outputs = {}
+            target = ctx[:target]
+            guard_stack = [true]
+
+            ir_module.decls.each do |decl|
+              slots = []
+              guard_stack = [true] # reset per decl
+
+              decl.ops.each_with_index do |op, op_index|
+                if ENV["ASSERT_VM_SLOTS"] == "1"
+                  expected = op_index
+                  unless slots.length == expected
+                    raise "slot drift: have=#{slots.length} expect=#{expected} at #{decl.name}@op#{op_index} #{op.tag}"
+                  end
+                end
+
+                case op.tag
+                when :guard_push
+                  cond_slot = op.attrs[:cond_slot]
+                  raise "guard_push: cond slot OOB" if cond_slot >= slots.length
+
+                  c = slots[cond_slot]
+
+                  guard_stack << case c[:k]
+                                 when :scalar
+                                   guard_stack.last && !!c[:v] # same as today
+                                 when :vec
+                                   # vector mask: push the mask value itself; truthiness handled inside ops
+                                   c
+                                 else
+                                   false
+                                 end
+                  slots << nil # keep slot_id == op_index
+                  next
+
+                when :guard_pop
+                  guard_stack.pop
+                  slots << nil
+                  next
+                end
+
+                # Skip body when guarded off, but keep indices aligned
+                unless guard_stack.last
+                  slots << nil if PRODUCES_SLOT.include?(op.tag) || NON_PRODUCERS.include?(op.tag)
+                  next
+                end
+
+                case op.tag
+
+                when :assign
+                  dst = op.attrs[:dst]
+                  src = op.attrs[:src]
+                  raise "assign: dst/src OOB" if dst >= slots.length || src >= slots.length
+
+                  slots[dst] = slots[src]
+
+                when :const
+                  result = Values.scalar(op.attrs[:value])
+                  puts "DEBUG Const #{op.attrs[:value].inspect}: result=#{result}" if ENV["DEBUG_VM_ARGS"]
+                  slots << result
+
+                when :load_input
+                  plan_id = op.attrs[:plan_id]
+                  scope = op.attrs[:scope] || []
+                  scalar = op.attrs[:is_scalar]
+                  indexed = op.attrs[:has_idx]
+                  raw = accessors.fetch(plan_id).call(ctx[:input] || ctx["input"])
+
+                  puts "DEBUG LoadInput plan_id: #{plan_id} raw_values: #{raw.inspect}" if ENV["DEBUG_VM_ARGS"]
+                  slots << if scalar
+                             Values.scalar(raw)
+                           elsif indexed
+                             Values.vec(scope, raw.map { |v, idx| { v: v, idx: Array(idx) } }, true)
+                           else
+                             Values.vec(scope, raw.map { |v| { v: v } }, false)
+                           end
+
+                when :ref
+                  name = op.attrs[:name]
+                  referenced_value = outputs.fetch(name) { raise "Missing output for reference: #{name}" }
+                  if ENV["DEBUG_VM_ARGS"]
+                    puts "DEBUG Ref #{name}: #{referenced_value[:k] == :scalar ? "scalar(#{referenced_value[:v].inspect})" : "#{referenced_value[:k]}(#{referenced_value[:rows]&.size || 0} rows)"}"
+                  end
+                  slots << referenced_value
+
+                when :array
+                  # Validate slot indices before accessing
+                  op.args.each do |slot_idx|
+                    if slot_idx >= slots.length
+                      raise "Array operation: slot index #{slot_idx} out of bounds (slots.length=#{slots.length})"
+                    elsif slots[slot_idx].nil?
+                      raise "Array operation: slot #{slot_idx} is nil " \
+                            "(available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                    end
+                  end
+
+                  parts = op.args.map { |i| slots[i] }
+                  if parts.all? { |p| p[:k] == :scalar }
+                    slots << Values.scalar(parts.map { |p| p[:v] })
+                  else
+                    base = parts.find { |p| p[:k] == :vec } or raise "Array literal needs a vec carrier"
+                    # Preserve original order: broadcast scalars in-place
+                    arg_vecs = parts.map { |p| p[:k] == :scalar ? Combinators.broadcast_scalar(p, base) : p }
+                    # All vectors must share scope
+                    scopes = arg_vecs.map { |v| v[:scope] }.uniq
+                    raise "Cross-scope array literal" unless scopes.size <= 1
+
+                    zipped = Combinators.zip_same_scope(*arg_vecs)
+                    rows = zipped[:rows].map do |row|
+                      vals = Array(row[:v])
+                      row.key?(:idx) ? { v: vals, idx: row[:idx] } : { v: vals }
+                    end
+                    slots << Values.vec(base[:scope], rows, base[:has_idx])
+                  end
+
+                when :map
+                  fn_name = op.attrs[:fn]
+                  fn_entry = registry[fn_name] or raise "Function #{fn_name} not found in registry"
+                  fn = fn_entry.fn
+                  puts "DEBUG Map #{fn_name}: args=#{op.args.inspect}" if ENV["DEBUG_VM_ARGS"]
+
+                  # Validate slot indices before accessing
+                  op.args.each do |slot_idx|
+                    if slot_idx >= slots.length
+                      raise "Map operation #{fn_name}: slot index #{slot_idx} out of bounds (slots.length=#{slots.length})"
+                    elsif slots[slot_idx].nil?
+                      raise "Map operation #{fn_name}: slot #{slot_idx} is nil " \
+                            "(available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                    end
+                  end
+
+                  args = op.args.map { |slot_idx| slots[slot_idx] }
+
+                  if args.all? { |a| a[:k] == :scalar }
+                    puts "DEBUG Scalar call #{fn_name}: args=#{args.map { |a| a[:v] }.inspect}" if ENV["DEBUG_VM_ARGS"]
+                    scalar_args = args.map { |a| a[:v] }
+                    result = fn.call(*scalar_args)
+                    slots << Values.scalar(result)
+                  else
+                    base = args.find { |a| a[:k] == :vec } or raise "Map needs a vec carrier"
+                    puts "DEBUG Vec call #{fn_name}: base=#{base.inspect}" if ENV["DEBUG_VM_ARGS"]
+                    # Preserve original order: broadcast scalars in-place
+                    arg_vecs = args.map { |a| a[:k] == :scalar ? Combinators.broadcast_scalar(a, base) : a }
+                    puts "DEBUG Vec call #{fn_name}: arg_vecs=#{arg_vecs.inspect}" if ENV["DEBUG_VM_ARGS"]
+                    scopes = arg_vecs.map { |v| v[:scope] }.uniq
+                    puts "DEBUG Vec call #{fn_name}: scopes=#{scopes.inspect}" if ENV["DEBUG_VM_ARGS"]
+                    raise "Cross-scope Map without Join" unless scopes.size <= 1
+
+                    zipped = Combinators.zip_same_scope(*arg_vecs)
+
+                    # if ENV["DEBUG_VM_ARGS"] && fn_name == :if
+                    #   puts "DEBUG Vec call #{fn_name}: zipped rows:"
+                    #   zipped[:rows].each_with_index do |row, i|
+                    #     puts "  [#{i}] args=#{Array(row[:v]).inspect}"
+                    #   end
+                    # end
+
+                    puts "DEBUG Vec call #{fn_name}: zipped rows=#{zipped[:rows].inspect}" if ENV["DEBUG_VM_ARGS"]
+                    rows = zipped[:rows].map do |row|
+                      row_args = Array(row[:v])
+                      vr = fn.call(*row_args)
+                      row.key?(:idx) ? { v: vr, idx: row[:idx] } : { v: vr }
+                    end
+                    puts "DEBUG Vec call #{fn_name}: result rows=#{rows.inspect}" if ENV["DEBUG_VM_ARGS"]
+
+                    slots << Values.vec(base[:scope], rows, base[:has_idx])
+                  end
+
+                when :switch
+                  chosen = op.attrs[:cases].find do |(cond_slot, _)|
+                    if cond_slot >= slots.length
+                      raise "Switch operation: condition slot #{cond_slot} out of bounds (slots.length=#{slots.length})"
+                    elsif slots[cond_slot].nil?
+                      raise "Switch operation: condition slot #{cond_slot} is nil (available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                    end
+
+                    c = slots[cond_slot]
+                    if c[:k] == :scalar
+                      !!c[:v]
+                    else
+                      # TODO: Proper vectorized cascade handling
+                      false
+                    end
+                  end
+                  result_slot = chosen ? chosen[1] : op.attrs[:default]
+                  if result_slot >= slots.length
+                    raise "Switch operation: result slot #{result_slot} out of bounds (slots.length=#{slots.length})"
+                  elsif slots[result_slot].nil?
+                    raise "Switch operation: result slot #{result_slot} is nil (available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                  end
+
+                  slots << slots[result_slot]
+
+                when :store
+                  name = op.attrs[:name]
+                  src  = op.args[0] or raise "store: missing source slot"
+                  if src >= slots.length
+                    raise "Store operation '#{name}': source slot #{src} out of bounds (slots.length=#{slots.length})"
+                  elsif slots[src].nil?
+                    raise "Store operation '#{name}': source slot #{src} is nil (available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                  end
+
+                  outputs[name] = slots[src]
+
+                  # keep slot_id == op_index invariant
+                  slots << nil
+
+                  return outputs if target && name == target
+
+                when :reduce
+                  fn_entry = registry[op.attrs[:fn]] or raise "Function #{op.attrs[:fn]} not found in registry"
+                  fn = fn_entry.fn
+
+                  src = slots[op.args[0]]
+                  raise "Reduce expects Vec" unless src[:k] == :vec
+
+                  result_scope = Array(op.attrs[:result_scope] || [])
+                  axis         = Array(op.attrs[:axis] || [])
+
+                  if result_scope.empty?
+                    # === GLOBAL REDUCE ===
+                    # Accept either ravel or indexed.
+                    vals = src[:rows].map { |r| r[:v] }
+                    slots << Values.scalar(fn.call(vals))
+                  else
+                    # === GROUPED REDUCE ===
+                    # Must have indices to group by prefix keys.
+                    unless src[:has_idx]
+                      raise "Grouped reduce requires indexed input (got ravel) for #{op.attrs[:fn]} at #{result_scope.inspect}"
+                    end
+
+                    group_len = result_scope.length
+
+                    # Preserve stable source order so zips with other @result_scope vecs line up.
+                    groups = {}         # { key(Array<Integer>) => Array<value> }
+                    order  = []         # Array<key> in first-seen order
+
+                    src[:rows].each do |row|
+                      key = Array(row[:idx]).first(group_len)
+                      unless groups.key?(key)
+                        groups[key] = []
+                        order << key
+                      end
+                      groups[key] << row[:v]
+                    end
+
+                    out_rows = order.map { |key| { v: fn.call(groups[key]), idx: key } }
+
+                    slots << Values.vec(result_scope, out_rows, true)
+                  end
+
+                when :lift
+                  src_slot = op.args[0]
+                  if src_slot >= slots.length
+                    raise "Lift operation: source slot #{src_slot} out of bounds (slots.length=#{slots.length})"
+                  elsif slots[src_slot].nil?
+                    raise "Lift operation: source slot #{src_slot} is nil (available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                  end
+
+                  v = slots[src_slot]
+                  to_scope = op.attrs[:to_scope] || []
+                  depth    = [to_scope.length, v[:rank] || v[:rows].first&.dig(:idx)&.length || 0].min
+                  slots << Values.scalar(Combinators.group_rows(v[:rows], depth))
+
+                when :align_to
+                  tgt_slot = op.args[0]
+                  src_slot = op.args[1]
+
+                  if tgt_slot >= slots.length
+                    raise "AlignTo operation: target slot #{tgt_slot} out of bounds (slots.length=#{slots.length})"
+                  elsif slots[tgt_slot].nil?
+                    raise "AlignTo operation: target slot #{tgt_slot} is nil " \
+                          "(available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                  end
+
+                  if src_slot >= slots.length
+                    raise "AlignTo operation: source slot #{src_slot} out of bounds (slots.length=#{slots.length})"
+                  elsif slots[src_slot].nil?
+                    raise "AlignTo operation: source slot #{src_slot} is nil " \
+                          "(available slots: #{slots.length}, non-nil slots: #{slots.compact.length})"
+                  end
+
+                  tgt = slots[tgt_slot]
+                  src = slots[src_slot]
+
+                  to_scope = op.attrs[:to_scope] || []
+                  require_unique = op.attrs[:require_unique] || false
+                  on_missing = op.attrs[:on_missing] || :error
+
+                  aligned = Combinators.align_to(tgt, src, to_scope: to_scope,
+                                                           require_unique: require_unique,
+                                                           on_missing: on_missing)
+                  slots << aligned
+
+                when :join
+                  raise NotImplementedError, "Join not implemented yet"
+
+                else
+                  raise "Unknown operation: #{op.tag}"
+                end
+              rescue StandardError => e
+                op_index = decl.ops.index(op) || "?"
+                context_info = []
+                context_info << "slots.length=#{slots.length}"
+                context_info << "non_nil_slots=#{slots.compact.length}" if slots.any?(&:nil?)
+                context_info << "op_attrs=#{op.attrs.inspect}" if op.attrs && !op.attrs.empty?
+                context_info << "op_args=#{op.args.inspect}" if op.args && !op.args.empty?
+
+                context_str = context_info.empty? ? "" : " (#{context_info.join(', ')})"
+                raise "#{decl.name}@op#{op_index} #{op.tag}#{context_str}: #{e.message}"
+              end
+            end
+
+            outputs
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module IR
+      module ExecutionEngine
+        # Value constructors and helpers for VM data representation
+        module Values
+          # Create a scalar value
+          def self.scalar(v)
+            { k: :scalar, v: v }
+          end
+
+          # Create a vector with scope and rows
+          def self.vec(scope, rows, has_idx)
+            if has_idx
+              rank = rows.empty? ? 0 : rows.first[:idx].length
+              # TODO: > Make sure this is not costly
+              # raise if rows.any? { |r| r[:idx].length != rank }
+              rows = rows.sort_by { |r| r[:idx] } # one-time sort
+            else
+              rank = 0
+            end
+
+            { k: :vec, scope: scope, rows: rows, has_idx: has_idx, rank: rank }
+          end
+
+          # Create a row with optional index
+          def self.row(v, idx = nil)
+            idx ? { v: v, idx: Array(idx) } : { v: v }
+          end
+
+          # Check if value is scalar
+          def self.scalar?(val)
+            val[:k] == :scalar
+          end
+
+          # Check if value is vector
+          def self.vec?(val)
+            val[:k] == :vec
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module IR
+      # ExecutionEngine interpreter for IR execution
+      #
+      # ARCHITECTURE:
+      # - Values:
+      #   * Scalar(v)                    → { k: :scalar, v: v }
+      #   * Vec(scope, rows, has_idx)    → { k: :vec, scope: [:axis, ...], rows: [{ v:, idx:[...] }, ...], has_idx: true/false }
+      #     - Rank = idx length; scope length is the logical axes carried by the vector
+      #
+      # - Combinators (pure, stateless, delegate to Executor):
+      #   * broadcast_scalar(scalar, vec)        → replicate scalar across vec rows (preserves idx/scope)
+      #   * zip_same_scope(vec1, vec2, ...)      → positional zip for equal scope & equal row count
+      #   * align_to(tgt_vec, src_vec, to_scope) → expand src by prefix indices to match a higher-rank scope
+      #   * group_rows(rows, depth)              → stable grouping by idx prefix to nested Ruby arrays
+      #
+      # - Executor:
+      #   * Executes IR ops in order; delegates to combinators; maintains a slot stack
+      #   * No structural inference; trusts IR attributes (scope, has_idx, is_scalar)
+      #
+      # OP SEMANTICS (subset):
+      # - const(value)               → push Scalar(value)
+      # - ref(name)                  → push previous slot by stored name (twins allowed: :name__vec)
+      # - load_input(plan_id, attrs) → call accessor; return Scalar or Vec according to attrs/mode
+      # - map(fn, argc, *args)       → elementwise or scalar call; auto alignment already handled by IR
+      # - reduce(fn, axis, ...)      → reduce one vector arg; returns Scalar
+      # - align_to(to_scope, a, b)   → align b to a’s to_scope (prefix-compat only)
+      # - array(count, *args)        → collect args into a Scalar(Array)
+      # - lift(to_scope, slot)       → require Vec(has_idx), group rows with `group_rows` to nested Scalar
+      # - store(name, slot)          → bind slot to name in env (used for :name and :name__vec twins)
+      #
+      # PRINCIPLES:
+      # - Mechanical execution only; “smarts” live in LowerToIR.
+      # - Never sniff Ruby types to guess shapes.
+      # - Errors early and clearly if invariants are violated (e.g., align_to expects vecs with indices).
+      #
+      # DEBUGGING:
+      # - DEBUG_VM_ARGS=1 prints per-op execution and arguments.
+      # - DEBUG_GROUP_ROWS=1 prints grouping decisions during Lift.
+      module ExecutionEngine
+        def self.run(ir_module, ctx, accessors:, registry:)
+          Interpreter.run(ir_module, ctx, accessors: accessors, registry: registry)
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/ir.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module IR
+      Op = Struct.new(:tag, :attrs, :args, keyword_init: true) do
+        def initialize(**args)
+          super
+          freeze
+        end
+      end
+      Decl = Struct.new(:name, :kind, :shape, :ops, keyword_init: true) do
+        def initialize(**args)
+          super
+          ops&.each(&:freeze)
+          freeze
+        end
+      end
+      Module = Struct.new(:inputs, :decls, keyword_init: true) do
+        def initialize(**args)
+          super
+          decls&.each(&:freeze)
+          freeze
+        end
+      end
+    end
+
+    module IR::Ops
+      def self.Const(v)                      = IR::Op.new(tag: :const, attrs: { value: v }, args: [])
+      def self.LoadInput(plan_id, scope: [], is_scalar: false, has_idx: false) = IR::Op.new(tag: :load_input, attrs: { plan_id: plan_id, scope: scope, is_scalar: is_scalar, has_idx: has_idx }, args: [])
+      def self.Ref(name)                     = IR::Op.new(tag: :ref, attrs: { name: name }, args: [])
+      def self.Map(fn, argc, *slots)         = IR::Op.new(tag: :map, attrs: { fn: fn, argc: argc }, args: slots)
+      def self.Array(count, *slots)          = IR::Op.new(tag: :array, attrs: { count: count }, args: slots)
+      def self.Switch(cases, default) = IR::Op.new(tag: :switch, attrs: { cases: cases, default: default }, args: [])
+      def self.GuardPush(cond_slot) = IR::Op.new(tag: :guard_push, attrs: { cond_slot: cond_slot }, args: [])
+      def self.GuardPop             = IR::Op.new(tag: :guard_pop,  attrs: {},                      args: [])
+      def self.Assign(dst:, src:)   = IR::Op.new(tag: :assign,     attrs: { dst: dst, src: src },  args: [])
+      def self.Store(name, slot)             = IR::Op.new(tag: :store, attrs: { name: name }, args: [slot])
+      def self.Lift(to_scope, slot)          = IR::Op.new(tag: :lift, attrs: { to_scope: to_scope }, args: [slot])
+      def self.Join(*slots)                  = IR::Op.new(tag: :join, attrs: {}, args: slots)
+      
+      # Up-sample `source` to the scope (and order) of `target` by index-prefix.
+      # Policies: :error | :nil for missing; require_unique: true enforces 1:1 on prefix.
+      def self.AlignTo(target_slot, source_slot, to_scope:, on_missing: :error, require_unique: true)
+        scope_array = to_scope.is_a?(::Array) ? to_scope : [to_scope]
+        IR::Op.new(
+          tag: :align_to,
+          attrs: { to_scope: scope_array, on_missing: on_missing, require_unique: require_unique },
+          args: [target_slot, source_slot]
+        )
+      end
+
+      def self.Reduce(fn, axis, result_scope, flatten, slot)
+        IR::Op.new(tag: :reduce, attrs: { fn: fn, axis: axis, result_scope: result_scope, flatten: flatten }, args: [slot])
+      end
+    end
+  end
+end

data/lib/kumi/core/ruby_parser/build_context.rb

@@ -4,12 +4,12 @@ module Kumi
   module Core
     module RubyParser
       class BuildContext
-        attr_reader :inputs, :attributes, :traits
+        attr_reader :inputs, :values, :traits
         attr_accessor :current_location
 
         def initialize
           @inputs = []
-          @attributes = []
+          @values = []
           @traits = []
           @input_block_defined = false
         end

data/lib/kumi/core/ruby_parser/declaration_reference_proxy.rb

@@ -20,18 +20,6 @@ module Kumi
         def to_ast_node
           Kumi::Syntax::DeclarationReference.new(@name, loc: @context.current_location)
         end
-
-        private
-
-        def method_missing(method_name, *args, &block)
-          # All operators are handled by ProxyRefinement methods
-          # Field access should use input.field.subfield syntax, not bare identifiers
-          super
-        end
-
-        def respond_to_missing?(_method_name, _include_private = false)
-          true
-        end
       end
     end
   end

data/lib/kumi/core/ruby_parser/dsl_cascade_builder.rb

@@ -15,39 +15,36 @@ module Kumi
         end
 
         def on(*args)
-          on_loc = current_location
-          validate_on_args(args, "on", on_loc)
+          validate_on_args(args, "on", @loc)
 
           trait_names = args[0..-2]
           expr = args.last
 
-          trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
-          condition = create_fn(:all?, trait_bindings)
+          trait_bindings = convert_trait_names_to_bindings(trait_names, @loc)
+          condition = @context.fn(:cascade_and, *trait_bindings)
           result = ensure_syntax(expr)
           add_case(condition, result)
         end
 
         def on_any(*args)
-          on_loc = current_location
-          validate_on_args(args, "on_any", on_loc)
+          validate_on_args(args, "on_any", @loc)
 
           trait_names = args[0..-2]
           expr = args.last
 
-          trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
+          trait_bindings = convert_trait_names_to_bindings(trait_names, @loc)
           condition = create_fn(:any?, trait_bindings)
           result = ensure_syntax(expr)
           add_case(condition, result)
         end
 
         def on_none(*args)
-          on_loc = current_location
-          validate_on_args(args, "on_none", on_loc)
+          validate_on_args(args, "on_none", @loc)
 
           trait_names = args[0..-2]
           expr = args.last
 
-          trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
+          trait_bindings = convert_trait_names_to_bindings(trait_names, @loc)
           condition = create_fn(:none?, trait_bindings)
           result = ensure_syntax(expr)
           add_case(condition, result)
@@ -71,11 +68,6 @@ module Kumi
 
         private
 
-        def current_location
-          caller_info = caller_locations(1, 1).first
-          Location.new(file: caller_info.path, line: caller_info.lineno, column: 0)
-        end
-
         def validate_on_args(args, method_name, location)
           raise_error("cascade '#{method_name}' requires at least one trait name", location) if args.empty?
 
@@ -92,7 +84,36 @@ module Kumi
             when DeclarationReference
               name # Already a binding from method_missing
             else
-              raise_error("trait reference must be a symbol or bare identifier, got #{name.class}", location)
+              # TODO: MOVE THESE TO ANALYZER- GRAMMAR CHECKS!
+              case name
+              when Kumi::Syntax::CallExpression
+                if name.fn_name == :==
+                  raise_error(
+                    "cascade conditions must be bare trait identifiers, not expressions like 'ref(...) == ...'. " \
+                    "Use fn(:==, ref(:tier), \"gold\") or define the comparison as a separate trait.",
+                    location
+                  )
+                else
+                  raise_error(
+                    "cascade conditions must be bare trait identifiers, not function calls (CallExpression). " \
+                    "Define the function call as a separate trait first.",
+                    location
+                  )
+                end
+              when Kumi::Syntax::DeclarationReference
+                raise_error(
+                  "cascade conditions must be bare trait identifiers, not value references (DeclarationReference). " \
+                  "Use just 'my_trait' instead of 'ref(:my_trait)'.",
+                  location
+                )
+              else
+                expression_type = name.class.name.split("::").last
+                raise_error(
+                  "cascade conditions must be bare trait identifiers, not #{expression_type} expressions. " \
+                  "Define complex expressions as separate traits first.",
+                  location
+                )
+              end
             end
           end
         end