kumi 0.0.9 → 0.0.11

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

@@ -13,13 +13,13 @@ module Kumi
 
         def key(name, type: :any, domain: nil)
           normalized_type = normalize_type(type, name)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, normalized_type, [], loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, normalized_type, [], nil, loc: @context.current_location)
         end
 
         %i[integer float string boolean any scalar].each do |type_name|
           define_method(type_name) do |name, type: nil, domain: nil|
             actual_type = type || (type_name == :scalar ? :any : type_name)
-            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, actual_type, [], loc: @context.current_location)
+            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, domain, actual_type, [], nil, loc: @context.current_location)
           end
         end
 
@@ -40,7 +40,7 @@ module Kumi
         end
 
         def method_missing(method_name, *_args)
-          allowed_methods = "'key', 'integer', 'float', 'string', 'boolean', 'any', 'scalar', 'array', and 'hash'"
+          allowed_methods = "'key', 'integer', 'float', 'string', 'boolean', 'any', 'scalar', 'array', 'hash', and 'element'"
           raise_syntax_error("Unknown method '#{method_name}' in input block. Only #{allowed_methods} are allowed.",
                              location: @context.current_location)
         end
@@ -63,7 +63,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, [], 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)
@@ -81,7 +81,7 @@ module Kumi
           val_type = extract_type(val_spec)
 
           hash_type = create_hash_type(field_name, key_type, val_type)
-          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, hash_type, [], loc: @context.current_location)
+          @context.inputs << Kumi::Syntax::InputDeclaration.new(field_name, domain, hash_type, [], nil, loc: @context.current_location)
         end
 
         def extract_type(spec)
@@ -98,14 +98,16 @@ module Kumi
           domain = options[:domain]
 
           # Collect children by creating a nested context
-          children = collect_array_children(&block)
+          children, _, using_elements = collect_array_children(&block)
 
-          # Create the InputDeclaration with children
+          # Create the InputDeclaration with children and access_mode
+          access_mode = using_elements ? :element : :field
           @context.inputs << Kumi::Syntax::InputDeclaration.new(
             field_name,
             domain,
             :array,
             children,
+            access_mode,
             loc: @context.current_location
           )
         end
@@ -119,7 +121,58 @@ module Kumi
           # Execute the block in the nested context
           nested_builder.instance_eval(&block)
 
-          nested_inputs
+          # Determine element type based on what was declared
+          elem_type = determine_element_type(nested_builder, nested_inputs)
+
+          # Check if element() was used
+          using_elements = nested_builder.instance_variable_get(:@using_elements) || false
+
+          [nested_inputs, elem_type, using_elements]
+        end
+
+        def determine_element_type(_builder, inputs)
+          # Since element() always creates named children now,
+          # we just use the standard logic
+          if inputs.any?
+            # If fields were declared, it's a hash/object structure
+            :hash
+          else
+            # No fields declared, default to :any
+            :any
+          end
+        end
+
+        def primitive_element_type?(elem_type)
+          %i[string integer float boolean bool any symbol].include?(elem_type)
+        end
+
+        # New method: element() declaration - always requires a name
+        def element(type_spec, name, &block)
+          @using_elements = true
+          if block_given?
+            # Named element with nested structure: element(:array, :rows) do ... end
+            # These DO set @using_elements to enable element access mode for multi-dimensional arrays
+            case type_spec
+            when :array
+              create_array_field_with_block(name, {}, &block)
+            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 :field types",
+                                 location: @context.current_location)
+            end
+          else
+            # Named primitive element: element(:boolean, :active)
+            # Only primitive elements mark the parent as using element access
+            @context.inputs << Kumi::Syntax::InputDeclaration.new(name, nil, type_spec, [], nil, loc: @context.current_location)
+          end
+        end
+
+        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, :field, children, nil, 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/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Kumi
   module Errors
     include Core::Errors

data/lib/kumi/js.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Js
+    # JavaScript transpiler for Kumi schemas
+    # Extends the existing compiler architecture to output JavaScript instead of Ruby lambdas
+
+    # Export a compiled schema to JavaScript
+    def self.compile(schema_class, **options)
+      syntax_tree = schema_class.__syntax_tree__
+      analyzer_result = schema_class.__analyzer_result__
+
+      compiler = Compiler.new(syntax_tree, analyzer_result)
+      compiler.compile(**options)
+    end
+
+    # Export to JavaScript file
+    def self.export_to_file(schema_class, filename, **options)
+      js_code = compile(schema_class, **options)
+      File.write(filename, js_code)
+    end
+  end
+end

data/lib/kumi/registry.rb

@@ -1,36 +1,31 @@
+# frozen_string_literal: true
+
 module Kumi
+  # 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
 
-      def register(name, &block)
-        @lock.synchronize do
-          raise FrozenError, "registry is frozen" if @frozen
-
+      def method_missing(name, ...)
+        if Core::FunctionRegistry.respond_to?(name)
+          Core::FunctionRegistry.public_send(name, ...)
+        else
           super
         end
       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

@@ -8,27 +8,29 @@ module Kumi
 
     Inspector = Struct.new(:syntax_tree, :analyzer_result, :compiled_schema) do
       def inspect
-        "#<#{self.class} syntax_tree: #{syntax_tree.inspect}, analyzer_result: #{analyzer_result.inspect}, schema: #{schema.inspect}>"
+        "#<#{self.class} syntax_tree: #{syntax_tree.inspect}, analyzer_result: #{analyzer_result.inspect}, compiled_schema: #{compiled_schema.inspect}>"
       end
     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]),