kumi 0.0.10 → 0.0.12

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)
+          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 bare trait 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

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

@@ -33,10 +33,14 @@ module Kumi
           end
         end
 
-        def hash(name_or_key_type, val_type = nil, **kwargs)
-          return Kumi::Core::Types.hash(name_or_key_type, val_type) unless val_type.nil?
-
-          create_hash_field(name_or_key_type, kwargs)
+        def hash(name_or_key_type, val_type = nil, **kwargs, &block)
+          if block_given?
+            create_hash_field_with_block(name_or_key_type, kwargs, &block)
+          elsif val_type.nil?
+            create_hash_field(name_or_key_type, kwargs)
+          else
+            Kumi::Core::Types.hash(name_or_key_type, val_type)
+          end
         end
 
         def method_missing(method_name, *_args)
@@ -63,7 +67,7 @@ module Kumi
           elem_type = elem_spec.is_a?(Hash) && elem_spec[:type] ? elem_spec[:type] : :any
 
           array_type = create_array_type(field_name, elem_type)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, array_type, [], :object, loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, array_type, [], :field, loc: @context.current_location)
         end
 
         def create_array_type(field_name, elem_type)
@@ -101,7 +105,7 @@ module Kumi
           children, _, using_elements = collect_array_children(&block)
 
           # Create the InputDeclaration with children and access_mode
-          access_mode = using_elements ? :element : :object
+          access_mode = using_elements ? :element : :field
           @context.inputs << Kumi::Syntax::InputDeclaration.new(
             field_name,
             domain,
@@ -155,11 +159,11 @@ module Kumi
             case type_spec
             when :array
               create_array_field_with_block(name, {}, &block)
-            when :object
+            when :field
               # Create nested object structure
               create_object_element(name, &block)
             else
-              raise_syntax_error("element(#{type_spec.inspect}, #{name.inspect}) with block only supports :array or :object types",
+              raise_syntax_error("element(#{type_spec.inspect}, #{name.inspect}) with block only supports :array or :field types",
                                  location: @context.current_location)
             end
           else
@@ -172,7 +176,24 @@ module Kumi
         def create_object_element(name, &block)
           # Similar to create_array_field_with_block but for objects
           children, = collect_array_children(&block)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, nil, :object, children, nil, loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, nil, :field, children, nil, loc: @context.current_location)
+        end
+
+        def create_hash_field_with_block(field_name, options, &block)
+          domain = options[:domain]
+
+          # Collect children by creating a nested context (reuse array logic)
+          children, = collect_array_children(&block)
+
+          # Create the InputDeclaration with children and :field access_mode for hash objects
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(
+            field_name,
+            domain,
+            :hash,
+            children,
+            :field,
+            loc: @context.current_location
+          )
         end
       end
     end

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

@@ -45,7 +45,7 @@ module Kumi
         end
 
         def build_syntax_tree
-          Root.new(@context.inputs, @context.attributes, @context.traits)
+          Root.new(@context.inputs, @context.values, @context.traits)
         end
 
         def handle_parse_error(error)

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

@@ -19,7 +19,7 @@ module Kumi
           validate_value_args(name, expr, blk)
 
           expression = blk ? build_cascade(&blk) : ensure_syntax(expr)
-          @context.attributes << Kumi::Syntax::ValueDeclaration.new(name, expression, loc: @context.current_location)
+          @context.values << Kumi::Syntax::ValueDeclaration.new(name, expression, loc: @context.current_location)
         end
 
         def trait(*args, **kwargs)
@@ -90,7 +90,7 @@ module Kumi
                                location: @context.current_location)
           end
 
-          has_expr = !expr.nil?
+          has_expr = !expr.is_a?(NilClass)
           has_block = blk
 
           if has_expr && has_block

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

@@ -254,6 +254,13 @@ module Kumi
                 ast_node = to_ast_node
                 Sugar.create_call_expression(:subtract, [Sugar.ensure_literal(0), ast_node])
               end
+
+              # Override Ruby's built-in nil? method to transform into == nil
+              define_method(:nil?) do
+                ast_node = to_ast_node
+                nil_literal = Kumi::Syntax::Literal.new(nil)
+                Sugar.create_call_expression(:==, [ast_node, nil_literal])
+              end
             end
           end
         end

data/lib/kumi/core/types/validator.rb

@@ -5,7 +5,7 @@ module Kumi
     module Types
       # Validates type definitions and structures
       class Validator
-        VALID_TYPES = %i[string integer float boolean any symbol regexp time date datetime array].freeze
+        VALID_TYPES = %i[string integer float boolean any symbol regexp time date datetime array hash].freeze
 
         def self.valid_type?(type)
           return true if VALID_TYPES.include?(type)

data/lib/kumi/registry.rb

@@ -1,96 +1,31 @@
 # frozen_string_literal: true
 
 module Kumi
-  # Public interface for registering custom functions in Kumi schemas
-  #
-  # Usage:
-  #   Kumi::Registry.register(:my_function) do |x|
-  #     x * 2
-  #   end
+  # Public facade for the function registry.
+  # Delegates to Kumi::Core::FunctionRegistry.
   module Registry
-    extend Core::FunctionRegistry
-
-    Entry = Core::FunctionRegistry::FunctionBuilder::Entry
-
-    @functions = Core::FunctionRegistry::CORE_FUNCTIONS.transform_values(&:dup)
-    @frozen    = false
-    @lock      = Mutex.new
-
-    class FrozenError < RuntimeError; end
+    Entry       = Core::FunctionRegistry::FunctionBuilder::Entry
+    FrozenError = Core::FunctionRegistry::FrozenError
 
     class << self
-      def reset!
-        @lock.synchronize do
-          @functions = Core::FunctionRegistry::CORE_FUNCTIONS.transform_values(&:dup)
-          @frozen    = false
-        end
+      def auto_register(*mods)
+        Core::FunctionRegistry.auto_register(*mods)
       end
 
-      # Register a custom function with the Kumi function registry
-      #
-      # Example:
-      #   Kumi::Registry.register(:double) do |x|
-      #     x * 2
-      #   end
-      #
-      #   # Use in schema:
-      #   value :doubled, fn(:double, input.number)
-      def register(name, &block)
-        @lock.synchronize do
-          raise FrozenError, "registry is frozen" if @frozen
-          raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
-
-          fn_lambda = block.is_a?(Proc) ? block : ->(*args) { yield(*args) }
-          @functions[name] = Entry.new(
-            fn: fn_lambda,
-            arity: fn_lambda.arity,
-            param_types: [:any],
-            return_type: :any,
-            description: nil,
-            inverse: nil,
-            reducer: false
-          )
+      def method_missing(name, ...)
+        if Core::FunctionRegistry.respond_to?(name)
+          Core::FunctionRegistry.public_send(name, ...)
+        else
+          super
         end
       end
 
-      # Register a custom function with detailed metadata for type and domain validation
-      #
-      # Example:
-      #   Kumi::Registry.register_with_metadata(
-      #     :add_tax,
-      #     ->(amount, rate) { amount * (1 + rate) },
-      #     arity: 2,
-      #     param_types: [:float, :float],
-      #     return_type: :float,
-      #     description: "Adds tax to an amount",
-      #   )
-      #
-      #   # Use in schema:
-      #   value :total, fn(:add_tax, input.price, input.tax_rate)
-      def register_with_metadata(name, fn_lambda, arity:, param_types: [:any], return_type: :any, description: nil, inverse: nil,
-                                 reducer: false)
-        @lock.synchronize do
-          raise FrozenError, "registry is frozen" if @frozen
-          raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
-
-          @functions[name] = Entry.new(
-            fn: fn_lambda,
-            arity: arity,
-            param_types: param_types,
-            return_type: return_type,
-            description: description,
-            inverse: inverse,
-            reducer: reducer
-          )
-        end
+      def respond_to_missing?(name, include_private = false)
+        Core::FunctionRegistry.respond_to?(name, include_private) || super
       end
 
       def freeze!
-        @lock.synchronize do
-          @functions.each_value(&:freeze)
-          @functions.freeze
-          @frozen = true
-        end
+        Core::FunctionRegistry.freeze!
       end
     end
   end

data/lib/kumi/runtime/executable.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Runtime
+    # Executable / Reader: evaluation interface for compiled schemas
+    #
+    # BUILD:
+    # - Executable.from_analysis(state) consumes:
+    #   * :ir_module (lowered IR)
+    #   * :access_plans (for AccessBuilder)
+    #   * function registry
+    # - Builds accessor lambdas once per plan id.
+    #
+    # EVALUATION:
+    # - program.read(inputs, mode: :public|:wrapped, target: nil)
+    #   * mode=:public  → returns “user values” (scalars and plain Ruby arrays). Vec results are exposed as their lifted scalar.
+    #   * mode=:wrapped → returns internal VM structures for introspection:
+    #       - Scalars as {k: :scalar, v: ...}
+    #       - Vec twins available as :name__vec (and :name for lifted scalar)
+    #   * target: symbol → short-circuit after computing the requested declaration and its dependencies.
+    #
+    # NAMING & TWINS (TODO: we are not exposing for now):
+    # - Every vectorized declaration with indices has:
+    #   * :name__vec  → internal vec form (rows with idx)
+    #   * :name       → lifted scalar form (nested arrays shaped by scope)
+    # - only :name is visible (TODO: For now, we do not expose the twins)
+    #
+    # CACHING / MEMOIZATION:
+    # - Values are computed once per evaluation; dependent requests reuse cached slots.
+    #
+    # ERROR SURFACE:
+    # - VM errors are wrapped as Kumi::Core::Errors::RuntimeError with op context (decl/op index).
+    # - Accessors raise descriptive KeyError for missing fields/arrays (policy-aware).
+    #
+    # DEBUGGING:
+    # - DEBUG_LOWER=1 to print IR at build time
+    # - DEBUG_VM_ARGS=1 to trace VM execution
+    # - Accessors can be debugged independently with DEBUG_ACCESSOR_OPS=1
+    class Executable
+      def self.from_analysis(state, registry: nil)
+        ir = state.fetch(:ir_module)
+        access_plans = state.fetch(:access_plans)
+        input_metadata = state[:input_metadata] || {}
+        accessors = Kumi::Core::Compiler::AccessBuilder.build(access_plans)
+
+        access_meta = {}
+        access_plans.each_value do |plans|
+          plans.each do |p|
+            access_meta[p.accessor_key] = { mode: p.mode, scope: p.scope }
+          end
+        end
+
+        # Use the internal functions hash that VM expects
+        registry ||= Kumi::Registry.functions
+        new(ir: ir, accessors: accessors, access_meta: access_meta, registry: registry, input_metadata: input_metadata)
+      end
+
+      def initialize(ir:, accessors:, access_meta:, registry:, input_metadata:)
+        @ir = ir.freeze
+        @acc = accessors.freeze
+        @meta = access_meta.freeze
+        @reg = registry
+        @input_metadata = input_metadata.freeze
+        @decl = @ir.decls.map { |d| [d.name, d] }.to_h
+      end
+
+      def decl?(name) = @decl.key?(name)
+
+      def read(input, mode: :ruby)
+        Run.new(self, input, mode: mode, input_metadata: @input_metadata)
+      end
+
+      # API compatibility for backward compatibility
+      def evaluate(ctx, *key_names)
+        target_keys = key_names.empty? ? @decl.keys : validate_keys(key_names)
+
+        # Handle context wrapping for backward compatibility  
+        input = ctx.respond_to?(:ctx) ? ctx.ctx : ctx
+
+        target_keys.each_with_object({}) do |key, result|
+          result[key] = eval_decl(key, input, mode: :ruby)
+        end
+      end
+
+      def eval_decl(name, input, mode: :ruby)
+        raise Kumi::Core::Errors::RuntimeError, "unknown decl #{name}" unless decl?(name)
+
+        out = Kumi::Core::IR::ExecutionEngine.run(@ir, { input: input, target: name },
+                                              accessors: @acc, registry: @reg).fetch(name)
+
+        mode == :ruby ? unwrap(@decl[name], out) : out
+      end
+
+      private
+
+      def validate_keys(keys)
+        unknown_keys = keys - @decl.keys
+        return keys if unknown_keys.empty?
+
+        raise Kumi::Errors::RuntimeError, "No binding named #{unknown_keys.first}"
+      end
+
+      private
+
+      def unwrap(_decl, v)
+        v[:k] == :scalar ? v[:v] : v # no grouping needed
+      end
+    end
+
+    class Run
+      def initialize(program, input, mode:, input_metadata:)
+        @program = program
+        @input = input
+        @mode = mode
+        @input_metadata = input_metadata
+        @cache = {}
+      end
+
+      def get(name)
+        @cache[name] ||= @program.eval_decl(name, @input, mode: @mode)
+      end
+
+      def [](name)
+        get(name)
+      end
+
+      def slice(*keys)
+        return {} if keys.empty?
+        keys.each_with_object({}) { |key, result| result[key] = get(key) }
+      end
+
+      def compiled_schema
+        @program
+      end
+
+      def method_missing(sym, *args, **kwargs, &blk)
+        return super unless args.empty? && kwargs.empty? && @program.decl?(sym)
+
+        get(sym)
+      end
+
+      def respond_to_missing?(sym, priv = false)
+        @program.decl?(sym) || super
+      end
+
+      def update(**changes)
+        changes.each do |field, value|
+          # Validate field exists
+          raise ArgumentError, "unknown input field: #{field}" unless input_field_exists?(field)
+
+          # Validate domain constraints
+          validate_domain_constraint(field, value)
+
+          # Update the input data
+          @input = deep_merge(@input, { field => value })
+        end
+
+        # Clear cache after all updates
+        @cache.clear
+        self
+      end
+
+      def wrapped!
+        @mode = :wrapped
+        @cache.clear
+        self
+      end
+
+      def ruby!
+        @mode = :ruby
+        @cache.clear
+        self
+      end
+
+      private
+
+      def input_field_exists?(field)
+        # Check if field is declared in input block
+        @input_metadata.key?(field) || @input.key?(field)
+      end
+
+      def validate_domain_constraint(field, value)
+        field_meta = @input_metadata[field]
+        return unless field_meta&.dig(:domain)
+
+        domain = field_meta[:domain]
+        return unless violates_domain?(value, domain)
+
+        raise ArgumentError, "value #{value} is not in domain #{domain}"
+      end
+
+      def violates_domain?(value, domain)
+        case domain
+        when Range
+          !domain.include?(value)
+        when Array
+          !domain.include?(value)
+        when Proc
+          # For Proc domains, we can't statically analyze
+          false
+        else
+          false
+        end
+      end
+
+      def deep_merge(a, b)
+        return b unless a.is_a?(Hash) && b.is_a?(Hash)
+
+        a.merge(b) { |_k, v1, v2| deep_merge(v1, v2) }
+      end
+    end
+  end
+end

data/lib/kumi/schema.rb

@@ -13,22 +13,24 @@ module Kumi
     end
 
     def from(context)
+      # VERY IMPORTANT: This method is overriden on specs in order to use dual mode.
+
       raise("No schema defined") unless @__compiled_schema__
 
       # Validate input types and domain constraints
-      input_meta = @__analyzer_result__.state[:inputs] || {}
+      input_meta = @__analyzer_result__.state[:input_metadata] || {}
       violations = Core::Input::Validator.validate_context(context, input_meta)
 
       raise Errors::InputValidationError, violations unless violations.empty?
 
-      Core::SchemaInstance.new(@__compiled_schema__, @__analyzer_result__.state, context)
+      @__compiled_schema__.read(context, mode: :ruby)
     end
 
     def explain(context, *keys)
       raise("No schema defined") unless @__compiled_schema__
 
       # Validate input types and domain constraints
-      input_meta = @__analyzer_result__.state[:inputs] || {}
+      input_meta = @__analyzer_result__.state[:input_metadata] || {}
       violations = Core::Input::Validator.validate_context(context, input_meta)
 
       raise Errors::InputValidationError, violations unless violations.empty?
@@ -40,8 +42,17 @@ module Kumi
       nil
     end
 
+    def build_syntax_tree(&block)
+      @__syntax_tree__ = Core::RubyParser::Dsl.build_syntax_tree(&block).freeze
+    end
+
     def schema(&block)
+      # from_location = caller_locations(1, 1).first
+      # raise "Called from #{from_location.path}:#{from_location.lineno}"
       @__syntax_tree__ = Core::RubyParser::Dsl.build_syntax_tree(&block).freeze
+
+      puts Support::SExpressionPrinter.print(@__syntax_tree__, indent: 2) if ENV["KUMI_DEBUG"] || ENV["KUMI_PRINT_SYNTAX_TREE"]
+
       @__analyzer_result__ = Analyzer.analyze!(@__syntax_tree__).freeze
       @__compiled_schema__ = Compiler.compile(@__syntax_tree__, analyzer: @__analyzer_result__).freeze
 

data/lib/kumi/schema_metadata.rb

@@ -341,9 +341,9 @@ module Kumi
     end
 
     def extract_inputs
-      return {} unless @state[:inputs]
+      return {} unless @state[:input_metadata]
 
-      @state[:inputs].transform_values do |field_info|
+      @state[:input_metadata].transform_values do |field_info|
         {
           type: normalize_type(field_info[:type]),
           domain: normalize_domain(field_info[:domain]),