kumi 0.0.10 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98308b4c27cb40488f14215c8da9700c62a51fc54d11b9d822a1eb25d396a724
-  data.tar.gz: 3fbbb50dc0c74ba14d83fbcf71c5866efa814b71b4d2679c45b57d59a1f778da
+  metadata.gz: dc6d1a550925563fbffcc0f4f96e6609d70734dfff031d9e6e2bfd405ecf45f8
+  data.tar.gz: '090999f0550fcd66a79cb3f683b8f27680b5921166267bbdf57dd8c593d3c6fd'
 SHA512:
-  metadata.gz: 4453ea76de50c433696c3ae5ebe4d39ae049cb35e40f34cf9a3cce0e52e5d0967a8ccfd9ca7627eafe33444ea4da186015a59796a59e022fdf5b5edc04c50444
-  data.tar.gz: dfdb9f118ee7c0c16fa30392b3591b88c8320a2d19ff331253a4344e49fa773967e6b8d2451c0fd490f200171846fec2b408ecd000e6ad111e3c2d89bd92c000
+  metadata.gz: 9c18d000d924168fbef1abcc6a19f59f18af8a82fae6d4d7bb14e475ce5b34032f031a14ae3d20faa8deadf96f7e1da9bb2190fca0251da74d629c38f637c139
+  data.tar.gz: 37f124928afe975bb7138c2856093849b6c15fb23694d77a7a0d1628b2c67f7e262576cb734a522105b8f83253fe112f6cbacc00895ad2daba4212eb7a337384

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [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.
+- Scope-aware vector semantics (alignment, lift, hierarchical indices).
+- Debug tooling: IR dump, VM/lowering traces via DEBUG_* flags.
+
+### Changed
+- Analyzer now lowers to IR via `LowerToIRPass`.
+- Access modes: `:read`, `:ravel`, `:each_indexed`, `:materialize`.
+
+### Removed (BREAKING)
+- JavaScript transpiler (legacy compiler).
+
+### Requirements
+- Ruby >= 3.1 (Was >= 3.0)
+
+### Notes
+- No expected DSL changes for typical schemas; report regressions.

data/CLAUDE.md

@@ -18,11 +18,6 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 - `bundle exec rspec spec/path/to/specific_spec.rb` - Run specific test file
 - `bundle exec rspec spec/path/to/specific_spec.rb:123` - Run specific test at line
 
-### Gem Management
-- `bundle install` - Install dependencies
-- `gem build kumi.gemspec` - Build the gem
-- `gem install ./kumi-*.gem` - Install locally built gem
-
 ## Architecture Overview
 
 ### Core Components
@@ -72,50 +67,8 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 - Supports custom function registration with type metadata
 - Each function includes param_types, return_type, arity, and description
 - Core functions include: `==`, `>`, `<`, `add`, `multiply`, `and`, `or`, `clamp`, etc.
-- Maintains backward compatibility with legacy type checking system
 - Function documents are generated by the script ./scripts/generate_function_docs.rb
 
-**Input Validation System** (`lib/kumi/input/` and `lib/kumi/domain/`):
-- `input/validator.rb` - Main validation coordinator for type and domain checking
-- `input/type_matcher.rb` - Type validation logic for primitive and complex types
-- `input/violation_creator.rb` - Creates standardized violation objects with detailed messages
-- `domain/validator.rb` - Domain constraint validation (ranges, arrays, procs)
-- `domain/range_analyzer.rb` - Range domain analysis and validation
-- `domain/enum_analyzer.rb` - Enumeration domain analysis and validation
-- `domain/violation_formatter.rb` - Formats domain violation error messages
-
-## DSL Syntax Requirements
-
-### Critical Syntax Rules
-
-**Module Definition Structure** 
-```ruby
-# CORRECT - CLI can find and load this
-module SchemaName
-  extend Kumi::Schema
-  
-  schema do
-    # schema definition here
-  end
-end
-```
-
-**Function Call Syntax**:
-- **Symbol style**: `fn(:function_name, arg1, arg2, ...)` - The only supported function call syntax 
-
-**Arithmetic Operations**:
-- **Sugar Syntax**: `input.field1 + input.field2` - Works for input fields and value references
-- **Function Syntax**: `fn(:add, input.field1, input.field2)` - Always works, more explicit
-- **Mixed**: Sugar syntax for basic operations, function syntax for complex ones
-
-**Cascade Condition Syntax**:
-```ruby
-value :status do
-  on trait_name, "Result"
-  base "Default"
-end
-```
-
 ### Key Patterns
 **DSL Structure**:
 ```ruby
@@ -133,17 +86,15 @@ schema do
       string  :category
     end
 
-
-
     # Fields with no declared type
     any     :misc_field
   end
 
-  trait :name, (expression)  # Boolean conditions with new syntax
+  trait :name, (expression)  # Boolean conditions
   value :name, expression    # Computed values
   value :name do             # Conditional logic
-    on condition, result
-    base default_result
+    on condition, result     # on <trait> ?,<trait> , <expr>
+    base default_result      # base <expr>
   end
 end
 ```
@@ -151,13 +102,6 @@ end
 **IMPORTANT CASCADE CONDITION SYNTAX:**
 In cascade expressions (`value :name do ... end`), trait references use bare identifiers:
 
-**Input Block System**:
-- **Required**: All schemas must have an `input` block declaring expected fields
-- **Type Declarations**: Preferred via type-specific methods (e.g. `integer :field`, `string :name`, `any :field` for untyped fields)
-- **Complex Types**: Use helper functions: `array(:element_type)` and `hash(:key_type, :value_type)`
-- **Domain Constraints**: Fields can have domains: `integer :age, domain: 18..65` (validated at runtime)
-- **Field Access**: Use `input.field_name` to reference input fields in expressions
-- **Separation**: Input metadata (types, domains) is separate from business logic
 
 **Expression Types**:
 - `input.field_name` - Access input data with operator methods (>=, <=, >, <, ==, !=)
@@ -179,30 +123,6 @@ In cascade expressions (`value :name do ... end`), trait references use bare ide
 - Type inference for all declarations based on expression analysis
 - Type primitives: `:string`, `:integer`, `:float`, `:boolean`, `:any`, `:symbol`, `:regexp`, `:time`, `:date`, `:datetime`
 - Collection types: `array(:element_type)` and `hash(:key_type, :value_type)` helper functions
-- Type compatibility checking and unification algorithms for numeric types
-- Enhanced error messages showing type provenance (declared vs inferred)
-- Legacy compatibility constants maintained for backward compatibility
-
-### Examples Directory
-
-The `examples/` directory contains examples showing Kumi usage patterns:
-- `cascade_demonstration.rb` - Demonstrates cascade logic with UnsatDetector fixes (working)
-- `working_comprehensive_schema.rb` - Feature showcase (current best practices, working)
-- Mathematical predicate examples - Safe mutual recursion patterns using cascade mutual exclusion
-- `federal_tax_calculator_2024.rb` - Real-world tax calculation example (working)
-- `tax_2024.rb` - Tax example with explain functionality (working)
-- `wide_schema_compilation_and_evaluation_benchmark.rb` - Benchmark for wide schemas (compilation and evaluation)
-- `deep_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for deep dependency chains (stack-safe evaluation)
-- `comprehensive_god_schema.rb` - Complex example (currently has UnsatDetector semantic errors)
-
-*Note: Some examples may use deprecated syntax and should be updated to use the new input block system.*
-
-## Test Structure
-
-- `spec/kumi/` - Unit tests for core components
-- `spec/integration/` - Integration tests for full workflows
-- `spec/fixtures/` - Test fixtures and sample schemas
-- `spec/support/` - Test helpers (`ast_factory.rb`, `schema_generator.rb`)
 
 ## Files for Understanding
 
@@ -210,46 +130,8 @@ The `examples/` directory contains examples showing Kumi usage patterns:
 - `examples/*` Random examples of diverse contexts.
 
 ### Troubleshooting Schema Issues
-- **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
-- **Module Not Found**: Check module structure and naming, see examples
-- **UnsatDetector Errors**: Review trait logic for contradictions, add debugs!
-- **Type Errors**: Check input block type declarations match usage, add debugs!
-- **Runtime Errors**: Use explain to trace computation dependencies, add debugs!
+DEBUG, DEBUG. DEBUG LOGS!
 
-## Input Block System Details
-
-### Required Input Blocks
-- **All schemas must have an input block** -
-- Input blocks declare expected fields with optional type and domain constraints
-- **Empty input blocks are allowed** -`input {}` Even if not useful.
-- Fields are accessed via `input.field_name` or `input.field.nested_field.nested_nested_field` which
-works for referencing nested array input declarations.
-
-### Type System Integration
-- **Declared Types**: Explicit type declarations in input blocks (e.g. `integer :field`, `string :name`, `any :field`)
-- **Inferred Types**: Types automatically inferred from expression analysis
-- **Type Checking**: Validates compatibility between declared and inferred types
-- **Enhanced Errors**: Error messages show type provenance (declared vs inferred)
-- **Helper Functions**: Use `array(:type)` and `hash(:key_type, :value_type)` for complex types
-
-### Parser Components
-See `lib/kumi/ruby_parser/parser.rb`
-
-### Domain Constraints
-- Can be declared: `integer :age, domain: 18..65`
-- Supports Range domains (`18..65`), Array domains (`%w[active inactive]`), and Proc domains for custom validation
-- Analyzer do some limited domain UNSAT detection, and its used to validated against input at Runtime
-### Type Examples
-```ruby
-input do
-  string       :name
-  integer      :age, domain: 18..65
-  hash         :metadata, key: { type: :string }, val: { type: :any }
-
-  #generic type
-  any          :misc # this reduces Kumi's analyze/inference capabilities
-end
-```
 
 ### Array Broadcasting System
 
@@ -262,6 +144,9 @@ input do
     float   :price
     integer :quantity  
     string  :category
+    array   :prices do
+      element :integer, :val
+    end
   end
 end
 
@@ -269,112 +154,3 @@ end
 value :subtotals, input.line_items.price * input.line_items.quantity
 trait :is_taxable, (input.line_items.category != "digital")
 ```
-
-**Aggregation Operations**: Functions consuming arrays are detected:
-```ruby
-value :total_subtotal, fn(:sum, subtotals)
-value :avg_price, fn(:avg, input.line_items.price)
-value :max_quantity, fn(:max, input.line_items.quantity)
-```
-
-**Implementation Components**:
-- **InputElementReference** AST nodes for nested field access paths
-- **BroadcastDetector** analyzer pass identifies vectorized vs scalar operations  
-- **Compiler** generates appropriate map/reduce functions based on usage context
-- **Type Inference** infers types for array element operations
-- Supports arbitrary depth field access with nested arrays and hashes
-
-### Trait Syntax Evolution
-
-**Current Syntax** (recommended):
-```ruby
-trait :adult, (input.age >= 18)
-trait :qualified, (input.age >= 21) & (input.score > 80) & (input.verified == true)
-```
-
-**Composite Trait Syntax** (NEW - bare identifier references):
-```ruby
-# Base traits
-trait :adult, (input.age >= 18)
-trait :verified, (input.verified == true)
-trait :high_score, (input.score > 80)
-
-# Composite traits using bare identifier syntax
-trait :eligible, adult & verified & high_score
-trait :mixed, adult & (input.income > 50_000) & verified
-
-# Backward compatibility - both syntaxes work together
-trait :legacy_mix, adult & ref(:verified) & (input.score > 90)
-```
-
-**Deprecated Syntax** (with warnings):
-```ruby
-trait :adult, input.age, :>=, 18                    # OLD - shows deprecation warning
-trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation warning
-```
-
-**Key Changes**:
-- **NEW**: Bare identifier syntax for direct trait reference: `adult` instead of `ref(:adult)`
-- New syntax uses parenthesized expressions: `trait :name, (expression)`  
-- FieldRef nodes have operator methods that create CallExpression nodes
-- Logical AND chaining via `&` operator (Ruby limitation prevents `&&`)
-- Only AND operations supported to maintain constraint satisfaction system
-- **Backward Compatible**: Both `trait_name` and `ref(:trait_name)` work together
-- Old syntax maintained with deprecation warnings for backward compatibility
-
-## Common Development Tasks
-
-### Adding New Analyzer Passes
-1. Create pass class inheriting from `PassBase` in `lib/kumi/analyzer/passes/`
-2. Implement `run(errors)` method that calls `set_state(key, value)` to store results
-3. Add pass to `PASSES` array in `lib/kumi/analyzer.rb` in correct order
-4. Consider dependencies on other passes (e.g., TypeChecker needs TypeInferencer)
-
-## Architecture Design Principles
-
-- **Multi-pass Analysis**: Each analysis pass has a single responsibility and builds on previous passes
-- **Immutable Syntax Tree**: AST nodes are immutable; analysis results stored separately in analyzer state
-- **Dependency-driven Evaluation**: All computation follows dependency graph for correct order
-- **Type Safety**: Optional type checking without breaking existing schemas
-- **Ruby Integration**: Leverages Ruby's metaprogramming with structured analysis
-- **Unified Error Reporting**: Consistent, localized error messages throughout the system with clear interface patterns
-
-## Code Organization Patterns
-
-### Testing Best Practices
-- **Spec Organization**: Tests organized by component with clear separation between unit and integration tests
-- **Error Variable Extraction**: RSpec patterns avoid multiline block chains by extracting error variables for assertion
-
-## Development Guides and Standards
-
-### Error Reporting Standards
-**For Parser Classes**:
-```ruby
-class MyParser
-  include ErrorReporting
-  
-  def parse_something
-    # Error raising
-    raise_syntax_error("Invalid syntax", location: current_location)
-  end
-end
-```
-
-**For Analyzer Passes**:
-```ruby
-class MyAnalyzerPass < PassBase
-  def run(errors)
-    # Error accumulation with enhanced location
-    report_error(errors, "semantic error", location: node.loc, type: :semantic)
-    
-    # Backward compatible method
-    add_error(errors, node.loc, "legacy format error")
-  end
-end
-```
-### Testing Error Scenarios
-- Use `spec/integration/dsl_breakage_spec.rb` patterns for error testing
-- Use `spec/integration/potential_breakage_spec.rb` for edge cases break
-- Use `spec/fixtures/location_tracking_test_schema.rb` fixture for testing different syntax error types  
-
-# 

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.
 
@@ -66,7 +66,7 @@ Validation happens during schema definition.
 ## Installation
 
 ```bash
-# Requires Ruby 3.0+
+# Requires Ruby 3.1+
 # No external dependencies
 gem install kumi
 ```
@@ -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: