kumi 0.0.11 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3eb46e14716bf14c3d9165ffac957211f41ad5a21a74ad37c47b37c37e01b312
-  data.tar.gz: fd0e36d65ac41079c27cf9699a3e092ff762bc76b3af8fc90df2ec763fed3806
+  metadata.gz: 7af4bdb11ef5da5a25b799cef8387752636a8224634c70656efc203b9d923185
+  data.tar.gz: 4e604513e42dcb8754fab54ead4140d5ca2d8443ae4d0461e62dc3b48bb925d4
 SHA512:
-  metadata.gz: 54ed5e72d6acf863e0f7ed0986c8db83fab22526bcffb97b4c1b96343e724b0ae505804baed5554933c452478ced8c46ec24a6568426813e69c4007994588de6
-  data.tar.gz: '09aabb772643aab71d957060c934f05be5838a1056b7c635822b75759106a3119844cc7e20f96b8990ec658d969f2d2e0143ceb43d36f8d48da061c2bb80cb6a'
+  metadata.gz: dcbd93268081ff8f0bcf112101603b180932196b1d6fcb59aae2f363d6bbfe4e9ea07cf3cbe811290222dcd15cdf132ea04f409bea34f81599412f729211a5fa
+  data.tar.gz: 3e0c2e91609e742c2852457b2dd61a114a03b988ae983e0cfb23c9bbf46bc5c6c1714636961ed46b4b9ae924c6a77a79dc0aab9013cadbb73e49d5374f8b8dbc

data/.rubocop.yml

@@ -4,7 +4,7 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
   SuggestExtensions: false
   Exclude:
     - 'bin/*'          

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [Unreleased]
+
+## [0.0.13] – 2025-08-14
+### Added
+- Runtime performance optimizations for interpreter execution
+- Input load deduplication to cache loaded input values and avoid redundant operations
+- Constant folding optimization to evaluate literal expressions during compilation
+- Accessor memoization with proper cache isolation per input context
+- Selective cache invalidation for incremental updates
+
+### Fixed
+- Cache isolation between different input contexts preventing cross-context pollution
+- Cascade mutual exclusion tests now pass correctly with proper trait evaluation
+- Incremental update performance with targeted cache clearing
+
+## [0.0.12] – 2025-08-14
+### Added
+- Hash objects input declarations with `hash :field do ... end` syntax
+- Complete hash object integration with arrays, nesting, and broadcasting
+
 ## [0.0.11] – 2025-08-13
 ### Added
 - Intermediate Representation (IR) and slot-based VM interpreter.

data/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/amuta/kumi/workflows/CI/badge.svg)](https://github.com/amuta/kumi/actions)
 [![Gem Version](https://badge.fury.io/rb/kumi.svg)](https://badge.fury.io/rb/kumi)
 
-Kumi is a Declarative logic and rules engine framework with static analysis for Ruby.
+**Kumi** is a declarative rules-and-calculation DSL for Ruby. It compiles business logic into a **typed, analyzable dependency graph** with **vector semantics** over nested data, performs **static checks** at definition time, **lowers to a compact IR**, and executes **deterministically**.
 
 It handles complex, interdependent calculations with validation and consistency checking.
 
@@ -436,8 +436,8 @@ runner[:after_tax]     # => 196,844.80 (cached)
 - Sequential procedural workflows  
 - High-frequency processing
 
-## JavaScript Transpiler
-
+## JavaScript Transpiler (V 0.0.10)
+Note: On the current 0.0.11 this is disabled but will be back in later versions. reason: IR/Interpreter update.
 Transpiles compiled schemas to standalone JavaScript code. See [docs/features/javascript-transpiler.md](docs/features/javascript-transpiler.md) for details.
 
 ```ruby
@@ -465,7 +465,7 @@ See [docs/features/performance.md](docs/features/performance.md) for detailed be
 
 ## What Kumi does not guarantee 
 
-Lambdas (e.g. -> inside the schema), external IO, floating-point vs bignum, JS transpiler edge cases, time-zone math differences, etc.
+Lambdas (e.g. -> inside the schema), external IO, floating-point vs bignum, time-zone math differences, etc.
 
 ## Learn More
 

data/docs/SYNTAX.md

@@ -214,12 +214,14 @@ Array broadcasting enables element-wise operations on array fields with automati
 
 ```ruby
 input do
+  # Structured array with defined fields
   array :line_items do
     float   :price
     integer :quantity
     string  :category
   end
   
+  # Nested arrays with hash objects
   array :orders do
     array :items do
       hash :product do
@@ -229,6 +231,15 @@ input do
       integer :quantity
     end
   end
+  
+  # Dynamic arrays with flexible element types
+  array :api_responses do
+    element :any, :response_data    # For dynamic/unknown hash structures
+  end
+  
+  array :measurements do
+    element :float, :value          # For simple scalar arrays
+  end
 end
 ```
 
@@ -290,6 +301,61 @@ value :avg_line_total, fn(:avg, line_totals)
 trait :has_expensive, fn(:any?, expensive_items)
 ```
 
+### Dynamic Hash Elements with `element :any`
+
+For arrays containing hash data with unknown or flexible structure, use `element :any` instead of defining explicit hash objects:
+
+```ruby
+input do
+  array :api_responses do
+    element :any, :response_data
+  end
+  
+  array :user_profiles do
+    element :any, :profile_info
+  end
+end
+
+# Access hash data using fn(:fetch)
+value :response_codes, fn(:fetch, input.api_responses.response_data, "status")
+value :user_names, fn(:fetch, input.user_profiles.profile_info, "name")
+value :user_ages, fn(:fetch, input.user_profiles.profile_info, "age")
+
+# Mathematical operations on extracted values
+value :avg_response_time, fn(:mean, fn(:fetch, input.api_responses.response_data, "response_time"))
+value :total_users, fn(:size, input.user_profiles.profile_info)
+
+# Traits using dynamic data
+trait :success_responses, fn(:any?, fn(:fetch, input.api_responses.response_data, "status") == 200)
+trait :adult_users, fn(:any?, fn(:fetch, input.user_profiles.profile_info, "age") >= 18)
+```
+
+**Use Cases for `element :any`:**
+- API responses with varying schemas
+- Configuration data with flexible structure  
+- Dynamic hash structures (unknown keys at schema definition time)
+- Legacy data where hash structure may vary
+- When you need maximum flexibility without type constraints
+
+**Comparison: `element :any` vs Hash Objects**
+
+```ruby
+# element :any approach (flexible, dynamic)
+array :users do
+  element :any, :data
+end
+value :names, fn(:fetch, input.users.data, "name")
+
+# hash object approach (typed, structured)  
+array :users do
+  hash :data do
+    string :name
+    integer :age
+  end
+end
+value :names, input.users.data.name
+```
+
 ### Broadcasting Type Inference
 
 The type system automatically infers appropriate types:

data/docs/features/hierarchical-broadcasting.md

@@ -67,6 +67,72 @@ value :cell_data, input.cube.layer.row.cell     # 1D values
 - **Ranked polymorphism**: Same operations work across different dimensional arrays
 - **Clean code**: `fn(:size, input.cube.layer.row)` instead of `fn(:size, fn(:flatten_one, input.cube.layer))`
 
+### Dynamic Hash Elements with `element :any`
+
+For arrays containing hash data with flexible or unknown structure, use `element :any` to access dynamic hash content:
+
+```ruby
+input do
+  array :api_responses do
+    element :any, :response_data    # Flexible hash structure
+  end
+  
+  array :user_events do
+    element :any, :event_data       # Dynamic event properties (includes event_type)
+  end
+end
+
+# Access hash fields using fn(:fetch)
+value :response_codes, fn(:fetch, input.api_responses.response_data, "status")
+value :error_messages, fn(:fetch, input.api_responses.response_data, "error")
+value :event_types, fn(:fetch, input.user_events.event_data, "event_type")
+value :user_ids, fn(:fetch, input.user_events.event_data, "user_id")
+value :timestamps, fn(:fetch, input.user_events.event_data, "timestamp")
+
+# Mathematical operations on extracted values
+value :avg_response_time, fn(:mean, fn(:fetch, input.api_responses.response_data, "response_time"))
+value :total_events, fn(:size, input.user_events.event_data)
+
+# Traits and cascades with dynamic data
+trait :has_errors, fn(:any?, fn(:fetch, input.api_responses.response_data, "status") >= 400)
+trait :recent_events, fn(:any?, fn(:fetch, input.user_events.event_data, "timestamp") > 1640995200)
+
+value :system_status do
+  on has_errors, "Error State"
+  on recent_events, "Active"
+  base "Idle"
+end
+```
+
+**When to use `element :any`:**
+- API responses with varying JSON schemas
+- Configuration files with flexible key-value structures
+- Event data where properties vary by event type
+- Legacy systems where data structure may change
+- Prototyping when exact hash structure is unknown
+
+**Comparison with Hash Objects:**
+
+| Approach | Use Case | Flexibility | Type Safety |
+|----------|----------|-------------|-------------|
+| `hash :field do ... end` | Known structure, strong typing | Limited | High |
+| `element :any, :field` | Unknown/flexible structure | High | Low |
+
+```ruby
+# Known structure - use hash objects
+array :orders do
+  hash :customer do
+    string :name
+    string :email
+  end
+end
+
+# Unknown/flexible structure - use element :any
+array :api_calls do
+  element :any, :response    # Could be any JSON structure
+end
+```
+
 ## Business Use Cases
 
 Element access mode is essential for common business scenarios involving simple nested arrays:

data/docs/features/input-declaration-system.md

@@ -14,10 +14,26 @@ schema do
     array   :tags, elem: { type: :string }
     hash    :metadata, key: { type: :string }, val: { type: :any }
     any     :flexible
+    
+    # Structured arrays with defined fields
+    array :orders do
+      hash :customer do
+        string :name
+        string :email
+      end
+      float :total
+    end
+    
+    # Dynamic arrays with flexible elements
+    array :api_responses do
+      element :any, :response_data    # For unknown/flexible hash structures
+    end
   end
   
   trait :adult, (input.age >= 18)
   value :status, input.verified ? "verified" : "pending"
+  value :customer_emails, input.orders.customer.email                           # Structured access
+  value :response_codes, fn(:fetch, input.api_responses.response_data, "status") # Dynamic access
 end
 ```
 

data/examples/deep_schema_compilation_and_evaluation_benchmark.rb

@@ -86,27 +86,21 @@ puts
 # ------------------------------------------------------------------
 Benchmark.ips do |x|
   schemas.each do |d, schema|
-    # 1) HOT (memoized): expect ~flat, nanosecond-level if cached
-    hot = schema.from(seed: 0)
-    x.report("HOT fetch #{d}-deep") do
-      hot[:final_result]
-    end
-
-    # 2) COLD via UPDATE (no memoized result): change a dependent input each iter
-    upd = schema.from(seed: 0)
-    i = 0
-    x.report("COLD update #{d}-deep") do
-      i += 1
-      upd.update(seed: i)      # invalidates v0..vN; forces recompute
-      upd[:final_result]
-    end
-
-    # 3) COLD new runner (includes construction)
-    prng = Random.new(42)
-    x.report("COLD new #{d}-deep") do
-      r = schema.from(seed: prng.rand(1_000_000))
-      r[:final_result]
-    end
+    runner = schema.from(seed: 0)          # memoised runner
+    x.report("eval #{d}-deep") { runner[:final_result] }
   end
   x.compare!
 end
+# Warming up --------------------------------------
+#         eval 50-deep   222.000 i/100ms
+#        eval 100-deep    57.000 i/100ms
+#        eval 150-deep    26.000 i/100ms
+# Calculating -------------------------------------
+#         eval 50-deep      2.166k (± 1.9%) i/s  (461.70 μs/i) -     10.878k in   5.024320s
+#        eval 100-deep    561.698 (± 1.4%) i/s    (1.78 ms/i) -      2.850k in   5.075057s
+#        eval 150-deep    253.732 (± 0.8%) i/s    (3.94 ms/i) -      1.274k in   5.021499s
+
+# Comparison:
+#         eval 50-deep:     2165.9 i/s
+#        eval 100-deep:      561.7 i/s - 3.86x  slower
+#        eval 150-deep:      253.7 i/s - 8.54x  slower

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

@@ -85,11 +85,11 @@ module Kumi
             end
 
             case parent_meta.container
-            when :object
+            when :object, :hash
               kids.each_value do |child|
                 child.enter_via = :hash
                 child.consume_alias = false
-                child.access_mode = :field
+                child.access_mode ||= :field  # Only set if not explicitly specified
               end
 
             when :array
@@ -139,7 +139,11 @@ module Kumi
                     report_error(errors, "access_mode :element only valid for single scalar/array element (at :#{kname})", location: nil)
                   end
                 else
-                  report_error(errors, "access_mode :element only valid under array parent (at :#{kname})", location: nil)
+                  # Only scalar children under non-array parents are invalid with :element mode
+                  # Arrays under hash/object parents can have :element mode (for arrays of scalars)
+                  if child.container == :scalar
+                    report_error(errors, "access_mode :element only valid under array parent (at :#{kname})", location: nil)
+                  end
                 end
               end
             end
@@ -147,7 +151,8 @@ module Kumi
 
           def kind_from_type(t)
             return :array if t == :array
-            return :field if t == :field
+            return :hash if t == :hash
+            return :object if t == :field
 
             :scalar
           end

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

@@ -139,9 +139,9 @@ module Kumi
               analysis_state = {
                 evaluation_order: evaluation_order,
                 declarations: declarations,
-                # access_plans: access_plans,
+                access_plans: access_plans,
                 join_reduce_plans: join_reduce_plans,
-                # scope_plans: scope_plans,
+                scope_plans: scope_plans,
                 input_metadata: input_metadata,
                 vec_names: @vec_names,
                 vec_meta: @vec_meta,
@@ -379,6 +379,7 @@ module Kumi
               when Syntax::InputReference
                 plan_id = pick_plan_id_for_input([expr.name], access_plans,
                                                  scope_plan: scope_plan, need_indices: need_indices)
+                
                 plans    = access_plans.fetch(expr.name.to_s, [])
                 selected = plans.find { |p| p.accessor_key == plan_id }
                 scope    = selected ? selected.scope : []
@@ -430,6 +431,13 @@ module Kumi
               when Syntax::CallExpression
                 entry = Kumi::Registry.entry(expr.fn_name)
 
+                # Constant folding optimization: evaluate expressions with all literal arguments
+                if can_constant_fold?(expr, entry)
+                  folded_value = constant_fold(expr, entry)
+                  ops << Kumi::Core::IR::Ops.Const(folded_value)
+                  return ops.size - 1
+                end
+
                 if ENV["DEBUG_LOWER"] && has_nested_reducer?(expr)
                   puts "  NESTED_REDUCER_DETECTED in #{expr.fn_name} with req_scope=#{required_scope.inspect}"
                 end
@@ -986,6 +994,31 @@ module Kumi
               end
             end
           end
+
+          # Constant folding optimization helpers
+          def can_constant_fold?(expr, entry)
+            return false unless entry&.fn # Skip if function not found
+            return false if entry.reducer # Skip reducer functions for now
+            return false if expr.args.empty? # Need at least one argument
+            
+            # Check if all arguments are literals
+            expr.args.all? { |arg| arg.is_a?(Syntax::Literal) }
+          end
+
+          def constant_fold(expr, entry)
+            literal_values = expr.args.map(&:value)
+            
+            begin
+              # Call the function with literal values at compile time
+              entry.fn.call(*literal_values)
+            rescue StandardError => e
+              # If constant folding fails, fall back to runtime evaluation
+              # This shouldn't happen with pure functions, but be defensive
+              puts "Constant folding failed for #{expr.fn_name}: #{e.message}" if ENV["DEBUG_LOWER"]
+              raise "Cannot constant fold #{expr.fn_name}: #{e.message}"
+            end
+          end
+
         end
       end
     end

data/lib/kumi/core/compiler/access_planner.rb

@@ -143,12 +143,12 @@ module Kumi
               else
                 raise ArgumentError, "Invalid :enter_via '#{enter_via}' for array child '#{seg}'. Must be :hash or :array"
               end
-            elsif container.nil? || container == :object
-              # Root or object parent - always emit enter_hash
+            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, or nil (root)"
+              raise ArgumentError, "Invalid parent :container '#{container}' for segment '#{seg}'. Expected :array, :object, :hash, or nil (root)"
             end
 
             parent_meta = node

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

@@ -39,7 +39,7 @@ module Kumi
         end
 
         private_class_method def self.should_validate_type?(meta)
-          meta[:type] && meta[:type] != :any
+          meta[:type] && meta[:type] != :any && !(meta[:children] && !meta[:children].empty?)
         end
 
         private_class_method def self.should_validate_domain?(meta)

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

@@ -42,7 +42,36 @@ module Kumi
       # - 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)
+          # Use persistent accessor cache if available, otherwise create temporary one
+          if ctx[:accessor_cache]
+            # Include input data in cache key to avoid cross-context pollution
+            input_key = ctx[:input]&.hash || ctx["input"]&.hash || 0
+            memoized_accessors = add_persistent_memoization(accessors, ctx[:accessor_cache], input_key)
+          else
+            memoized_accessors = add_temporary_memoization(accessors)
+          end
+          
+          Interpreter.run(ir_module, ctx, accessors: memoized_accessors, registry: registry)
+        end
+
+        private
+
+        def self.add_persistent_memoization(accessors, cache, input_key)
+          accessors.map do |plan_id, accessor_fn|
+            [plan_id, lambda do |input_data|
+              cache_key = [plan_id, input_key]
+              cache[cache_key] ||= accessor_fn.call(input_data)
+            end]
+          end.to_h
+        end
+
+        def self.add_temporary_memoization(accessors)
+          cache = {}
+          accessors.map do |plan_id, accessor_fn|
+            [plan_id, lambda do |input_data|
+              cache[plan_id] ||= accessor_fn.call(input_data)
+            end]
+          end.to_h
         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)
@@ -174,6 +178,23 @@ module Kumi
           children, = collect_array_children(&block)
           @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
   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/runtime/executable.rb

@@ -62,6 +62,7 @@ module Kumi
         @reg = registry
         @input_metadata = input_metadata.freeze
         @decl = @ir.decls.map { |d| [d.name, d] }.to_h
+        @accessor_cache = {} # Persistent accessor cache across evaluations
       end
 
       def decl?(name) = @decl.key?(name)
@@ -85,12 +86,20 @@ module Kumi
       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 },
+        out = Kumi::Core::IR::ExecutionEngine.run(@ir, { input: input, target: name, accessor_cache: @accessor_cache },
                                               accessors: @acc, registry: @reg).fetch(name)
 
         mode == :ruby ? unwrap(@decl[name], out) : out
       end
 
+      def clear_field_accessor_cache(field_name)
+        # Clear cache entries for all accessor plans related to this field
+        # Cache keys are now [plan_id, input_key] arrays
+        @accessor_cache.delete_if { |cache_key, _| 
+          cache_key.is_a?(Array) && cache_key[0].to_s.start_with?("#{field_name}:")
+        }
+      end
+
       private
 
       def validate_keys(keys)
@@ -153,9 +162,12 @@ module Kumi
 
           # Update the input data
           @input = deep_merge(@input, { field => value })
+          
+          # Clear accessor cache for this specific field
+          @program.clear_field_accessor_cache(field)
         end
 
-        # Clear cache after all updates
+        # Clear declaration evaluation cache after all updates
         @cache.clear
         self
       end

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.11"
+  VERSION = "0.0.13"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kumi
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.13
 platform: ruby
 authors:
 - André Muta
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -23,6 +24,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.6.0
+description: 
 email:
 - andremuta@gmail.com
 executables: []
@@ -198,6 +200,7 @@ metadata:
   source_code_uri: https://github.com/amuta/kumi
   changelog_uri: https://github.com/amuta/kumi/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -205,14 +208,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.5.22
+signing_key: 
 specification_version: 4
-summary: A Declarative logic framework with static analysis for Ruby.
+summary: Kumi is a declarative rules-and-calculation DSL for Ruby that compiles your
+  business logic into a typed, analyzable                   dependency graph with
+  vector semantics over nested data. It does static checks at definition time, lowers
+  to a small                   IR, and runs with consistent, predictable behavior.
 test_files: []