kumi 0.0.10 → 0.0.12

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 || container == :hash
+              # Root, object, or hash 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, :hash, 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

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class EachIndexedAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy, with_indices = true)
+            walker = build_each_walker(operations, path_key, policy, key_policy)
+            if with_indices
+              lambda do |data, &blk|
+                if blk
+                  walker.call(data, 0, [], ->(val, idx) { blk.call(val, idx) })
+                  nil
+                else
+                  out = []
+                  walker.call(data, 0, [], ->(val, idx) { out << [val, idx] })
+                  out
+                end
+              end
+            else
+              lambda do |data, &blk|
+                if blk
+                  walker.call(data, 0, [], ->(val, _idx) { blk.call(val) })
+                  nil
+                else
+                  out = []
+                  walker.call(data, 0, [], ->(val, _idx) { out << val })
+                  out
+                end
+              end
+            end
+          end
+
+          # Depth-first traversal yielding (value, nd_index)
+          def self.build_each_walker(operations, path_key, policy, key_policy)
+            mode = :each_indexed
+            walk = nil
+            walk = lambda do |node, pc, ndx, y|
+              if pc >= operations.length
+                y.call(node, ndx)
+                return
+              end
+
+              op = operations[pc]
+              case op[:type]
+              when :enter_hash
+                # If the *next* op is an array hop, relax to indifferent for that fetch
+                policy_for = next_enters_array?(operations, pc) ? :indifferent : key_policy
+                next_node = fetch_key(node, op[:key], policy_for)
+                if next_node == Base::MISSING
+                  case missing_key_action(policy)
+                  when :yield_nil then y.call(nil, ndx)
+                  when :skip      then return
+                  when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                  end
+                  return
+                end
+                walk.call(next_node, pc + 1, ndx, y)
+
+              when :enter_array
+                if node.nil?
+                  case missing_array_action(policy)
+                  when :yield_nil then y.call(nil, ndx)
+                  when :skip      then return
+                  when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                  end
+                  return
+                end
+                assert_array!(node, path_key, mode)
+                node.each_with_index { |child, i| walk.call(child, pc + 1, ndx + [i], y) }
+
+              else
+                raise "Unknown operation: #{op.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class MaterializeAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :materialize
+            lambda do |data|
+              walk = nil
+              walk = lambda do |node, pc|
+                return node if pc >= operations.length
+
+                op = operations[pc]
+                case op[:type]
+                when :enter_hash
+                  assert_hash!(node, path_key, mode)
+                  preview_array = next_enters_array?(operations, pc)
+                  policy_for = preview_array ? :indifferent : key_policy
+                  next_node = fetch_key(node, op[:key], policy_for)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return preview_array ? [] : nil
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  walk.call(next_node, pc + 1)
+
+                when :enter_array
+                  if node.nil?
+                    case missing_array_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return []
+                    when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  assert_array!(node, path_key, mode)
+                  node.map { |child| walk.call(child, pc + 1) }
+
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+              walk.call(data, 0)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        # Ravel: collect leaf elements reached by the op sequence.
+        # Invariants guaranteed by the planner for :ravel:
+        # - Every array edge along the path has an :enter_array op.
+        # - If the leaf container is an array, a terminal :enter_array is appended,
+        #   so the leaf we see here is the element, not the array.
+        class RavelAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :ravel
+
+            lambda do |data|
+              out = []
+
+              walk = nil
+              walk = lambda do |node, pc|
+                # Leaf: ops exhausted ⇒ emit this element (scalar/object/array element).
+                if pc >= operations.length
+                  out << node
+                  return
+                end
+
+                op = operations[pc]
+                case op[:type]
+                when :enter_hash
+                  # If the next step is an array, we don’t care about key symbol/string
+                  # (we’ll just iterate) → use indifferent lookup.
+                  preview_array = next_enters_array?(operations, pc)
+                  policy_for = preview_array ? :indifferent : key_policy
+
+                  next_node = fetch_key(node, op[:key], policy_for)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then out << nil
+                    when :skip      then return
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                    return
+                  end
+                  walk.call(next_node, pc + 1)
+
+                when :enter_array
+                  if node.nil?
+                    case missing_array_action(policy)
+                    when :yield_nil then out << nil
+                    when :skip      then return
+                    when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                    end
+                    return
+                  end
+                  assert_array!(node, path_key, mode)
+                  node.each { |child| walk.call(child, pc + 1) }
+
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+
+              walk.call(data, 0)
+              out
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class ReadAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :read
+            lambda do |data|
+              node = data
+              operations.each do |op|
+                case op[:type]
+                when :enter_hash
+                  assert_hash!(node, path_key, mode)
+                  next_node = fetch_key(node, op[:key], key_policy)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return nil
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  node = next_node
+                when :enter_array
+                  # Should never be present for rank-0 plans
+                  raise TypeError, "Array encountered in :read accessor at '#{path_key}'"
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+              node
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler_base.rb

@@ -24,8 +24,8 @@ module Kumi
 
       def build_index
         @index = {}
-        @schema.attributes.each { |a| @index[a.name] = a }
-        @schema.traits.each     { |t| @index[t.name] = t }
+        @schema.values.each { |a| @index[a.name] = a }
+        @schema.traits.each { |t| @index[t.name] = t }
       end
 
       def determine_operation_mode_for_path(_path)

data/lib/kumi/core/error_reporter.rb

@@ -12,7 +12,7 @@ module Kumi
     # 4. Support both immediate raising and error accumulation patterns
     module ErrorReporter
       # Standard error structure for internal use
-      ErrorEntry = Struct.new(:location, :message, :type, :context, keyword_init: true) do
+      ErrorEntry = Struct.new(:location, :message, :type, :context, :backtrace, keyword_init: true) do
         def to_s
           location_str = format_location(location)
           "#{location_str}: #{message}"
@@ -47,12 +47,13 @@ module Kumi
       # @param type [Symbol] Optional error category (:syntax, :semantic, :type, etc.)
       # @param context [Hash] Optional additional context
       # @return [ErrorEntry] Structured error entry
-      def create_error(message, location: nil, type: :semantic, context: {})
+      def create_error(message, location: nil, type: :semantic, context: {}, backtrace: nil)
         ErrorEntry.new(
           location: location,
           message: message,
           type: type,
-          context: context
+          context: context,
+          backtrace: backtrace
         )
       end
 
@@ -76,8 +77,8 @@ module Kumi
       # @param error_class [Class] Exception class to raise
       # @param type [Symbol] Error category
       # @param context [Hash] Additional context
-      def raise_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, context: {})
-        entry = create_error(message, location: location, type: type, context: context)
+      def raise_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, backtrace: nil, context: {})
+        entry = create_error(message, location: location, type: type, context: context, backtrace: backtrace || caller)
         # Pass both the formatted message and the original location to the error constructor
         raise error_class.new(entry.to_s, location)
       end

data/lib/kumi/core/errors.rb

@@ -24,6 +24,8 @@ module Kumi
 
       class UnknownFunction < Error; end
 
+      class AnalysisError < Error; end
+
       class SemanticError < LocatedError; end
 
       class TypeError < SemanticError; end
@@ -32,6 +34,8 @@ module Kumi
 
       class SyntaxError < LocatedError; end
 
+      class CompilationError < Error; end
+
       class RuntimeError < Error; end
 
       class DomainViolationError < Error