kumi 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4a3efa20727ebc89e39753f240bb6ed8fc3621b32771ea3b6d9096bdc21af5
-  data.tar.gz: 4c0a147c66d2b2ece9bec196b665d7b5fe613bb021caa5ec3efc00f0e0e6ed94
+  metadata.gz: 91e6e3b6ce1e4911d37588ba8aaf9b89f8129d23fe93b05268756c417249da90
+  data.tar.gz: f019de05a9e05957184fc649d187306fa7cd3736cb9d04c56d6080d4a3cde9de
 SHA512:
-  metadata.gz: 4e029e73067c2403290e1af7d9c841a1f8fad6782636275ec24b0626e3086684765e3010c727f839febd4238a61fe3723388ab899e4dece18701a720608a39df
-  data.tar.gz: e9a83993e264eca2a67821a9bc6d3f7bd59815c9c593fcd119fbbaed93fb92c345211023366aab076a35ef248b3580f84531aa52e1726463345e77e32c810ecb
+  metadata.gz: 6d6439258bcb876374c5f7ca3bafa4e59faabf112e3cfe2dac532f752b2b7ef8533bf888c4e6feb1509995069a103a258b37c6b18b0164487e5215e03dd85b10
+  data.tar.gz: 6e64f9725569836d7a17b83aa82f316f01d4a9169a1323cee3d1d5fcf7d3782902b9c0695bcdb3735a4c206906463a4b7ca3e14f39f253ba23bf23d572ce95aa

data/CLAUDE.md

@@ -3,6 +3,7 @@
 !! Remember, this gem is not on production yet, so no backward compatilibity is necessary. But do not change the public interfaces (e.g. DSL, Schema) without explicitly requested or demanded. 
 !! We are using zeitwerk, i.e.: no requires
 !! Do not care about linter or coverage unless asked to do so.
+!! IMPORTANT: Communication style - Write direct, factual statements. Avoid promotional language, unnecessary claims, or marketing speak. State what the system does, not what benefits it provides. Use TODOs for missing information rather than placeholder claims.
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
@@ -60,9 +61,17 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 **Syntax Tree** (`lib/kumi/syntax/`):
 - `node.rb` - Base node class with location tracking
 - `root.rb` - Root schema node containing inputs, attributes, and traits
-- `declarations.rb` - Attribute and trait declaration nodes  
-- `expressions.rb` - Expression nodes (calls, lists, cascades)
-- `terminal_expressions.rb` - Terminal nodes (literals, field references, bindings, field declarations)
+- `value_declaration.rb` - Value declaration nodes (formerly Attribute)
+- `trait_declaration.rb` - Trait declaration nodes (formerly Trait)
+- `input_declaration.rb` - Input field declaration nodes (formerly FieldDecl)
+- `call_expression.rb` - Function call expression nodes
+- `array_expression.rb` - Array expression nodes (formerly ListExpression)
+- `hash_expression.rb` - Hash expression nodes (for future hash literals)
+- `cascade_expression.rb` - Cascade expression nodes (conditional values)
+- `case_expression.rb` - Case expression nodes (formerly WhenCaseExpression)
+- `literal.rb` - Literal value nodes
+- `input_reference.rb` - Input field reference nodes (formerly FieldRef)  
+- `declaration_reference.rb` - Declaration reference nodes (formerly Binding)
 
 **Analyzer** (`lib/kumi/analyzer.rb`):
 - Multi-pass analysis system that validates schemas and builds dependency graphs
@@ -235,6 +244,7 @@ end
 The `examples/` directory contains comprehensive examples showing Kumi usage patterns:
 - `cascade_demonstration.rb` - Demonstrates cascade logic with UnsatDetector fixes (working)
 - `working_comprehensive_schema.rb` - Complete 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` - Simple tax example with explain functionality (working)
 - `wide_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for wide schemas (compilation and evaluation scaling)
@@ -261,11 +271,13 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 7. `lib/kumi/analyzer/passes/type_checker.rb` - Type validation with enhanced error messages
 8. `spec/kumi/input_block_spec.rb` - Input block syntax and behavior
 9. `spec/integration/compiler_integration_spec.rb` - End-to-end test examples
-10. `documents/DSL.md` - Concise DSL syntax reference
-11. `documents/AST.md` - AST node types and structure reference
-12. `documents/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
+10. `docs/DSL.md` - Concise DSL syntax reference
+11. `docs/AST.md` - AST node types and structure reference
+12. `docs/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
 13. `lib/kumi/cli.rb` - CLI implementation with REPL and file execution
 14. `examples/simple_tax_schema.rb` - CLI-compatible schema example
+15. `docs/features/analysis-cascade-mutual-exclusion.md` - Cascade mutual exclusion detection feature documentation
+16. `docs/features/array-broadcasting.md` - Array broadcasting and vectorization system documentation
 
 ## CLI Usage and Best Practices
 
@@ -346,6 +358,39 @@ input do
 end
 ```
 
+### Array Broadcasting System
+
+**Automatic Vectorization**: Field access on array inputs (`input.items.price`) applies operations element-wise with intelligent map/reduce detection.
+
+**Basic Broadcasting**:
+```ruby
+input do
+  array :line_items do
+    float   :price
+    integer :quantity  
+    string  :category
+  end
+end
+
+# Element-wise computation - broadcasts over each item
+value :subtotals, input.line_items.price * input.line_items.quantity
+trait :is_taxable, (input.line_items.category != "digital")
+```
+
+**Aggregation Operations**: Functions consuming arrays automatically 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** automatically infers types for array element operations
+- Supports arbitrary depth field access with nested arrays and hashes
+
 ### Trait Syntax Evolution
 
 **Current Syntax** (recommended):

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 computational rules engine for Ruby (plus static validation, dependency tracking, and more)
+Kumi is a Declarative logic framework with static analysis for Ruby.
 
 It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
@@ -11,7 +11,7 @@ It is well-suited for scenarios with complex, interdependent calculations, enfor
 
 ## What can you build?
 
-Calculate U.S. federal taxes in 30 lines of validated, readable code:
+Calculate U.S. federal taxes:
 
 ```ruby
 module FederalTax2024
@@ -62,7 +62,7 @@ result[:after_tax]   # => 78,509.00
 
 Real tax calculation with brackets, deductions, and FICA caps. Validation happens during schema definition.
 
-Is is well-suited for scenarios with complex, interdependent calculations, enforcing ...
+Kumi is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
 ## Installation
 
@@ -74,17 +74,19 @@ gem install kumi
 
 ## Core Features
 
-Here's a concise "Key Concepts" section for your README:
+<details>
+<summary><strong>📊 Schema Primitives</strong> - Four building blocks for business logic</summary>
 
-## Key Concepts
+### Schema Primitives
 
-Kumi schemas are built from four simple primitives that compose into powerful business logic:
+Kumi schemas are built from four primitives:
 
 **Inputs** define the data flowing into your schema with built-in validation:
 ```ruby
 input do
   float :price, domain: 0..1000.0      # Validates range
-  string :category, domain: %w[standard premium]  # Validates inclusion
+  integer :quantity, domain: 1..10000   # Validates range
+  string :tier, domain: %w[standard premium]  # Validates inclusion
 end
 ```
 
@@ -101,7 +103,7 @@ trait :bulk_order, input.quantity >= 100
 trait :premium_customer, input.tier == "premium"
 
 value :discount do
-  on bulk_order & premium_customer, 0.25  # 25% for bulk premium orders
+  on bulk_order, premium_customer, 0.25  # 25% for bulk premium orders
   on bulk_order, 0.15                     # 15% for bulk orders
   on premium_customer, 0.10               # 10% for premium customers
   base 0.0                                # No discount otherwise
@@ -114,73 +116,185 @@ end
 value :final_price, [subtotal - discount_amount, 0].max
 value :monthly_payment, fn(:pmt, rate: 0.05/12, nper: 36, pv: -loan_amount)
 ```
-Note: You can find a list all core functions [FUNCTIONS.md](documents/FUNCTIONS.md)
+Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIONS.md)
 
+These primitives are statically analyzed during schema definition to catch logical errors before runtime.
 
-These primitives are statically analyzed during schema definition, catching logical errors before runtime and ensuring your business rules are internally consistent.
+</details>
 
+<details>
+<summary><strong>🔍 Static Analysis</strong> - Catch business logic errors at definition time</summary>
 
 ### Static Analysis
 
-Kumi catches real business logic errors during schema definition:
+Kumi catches business logic errors that cause runtime failures or silent bugs:
 
 ```ruby
-module CommissionCalculator
+module InsurancePolicyPricer
   extend Kumi::Schema
   
   schema do
     input do
-      float :sales_amount, domain: 0..Float::INFINITY
+      integer :age, domain: 18..80
+      string :risk_category, domain: %w[low medium high]
+      float :coverage_amount, domain: 50_000..2_000_000
       integer :years_experience, domain: 0..50
-      string :region, domain: %w[east west north south]
+      boolean :has_claims
     end
     
-    # Commission tiers based on experience
-    trait :junior, input.years_experience < 2
-    trait :senior, input.years_experience >= 5
-    trait :veteran, input.years_experience >= 10
-    
-    # Base commission rates
-    value :base_rate do
-      on veteran, 0.08
-      on senior, 0.06
-      on junior, 0.04
-      base 0.05
+    # Risk assessment with subtle interdependencies
+    trait :young_driver, input.age < 25
+    trait :experienced, input.years_experience >= 5
+    trait :high_risk, input.risk_category == "high"
+    trait :senior_driver, input.age >= 65
+    
+    # Base premium calculation
+    value :base_premium, input.coverage_amount * 0.02
+    
+    # Experience adjustment with subtle circular reference
+    value :experience_factor do
+      on experienced & young_driver, experience_discount * 0.8  # ❌ Uses experience_discount before it's defined
+      on experienced, 0.85
+      on young_driver, 1.25
+      base 1.0
     end
     
-    # Regional multipliers
-    value :regional_bonus do
-      on input.region == "west", 1.2  # West coast bonus
-      on input.region == "east", 1.1  # East coast bonus
+    # Risk multipliers that create impossible combinations
+    value :risk_multiplier do
+      on high_risk & experienced, 1.5    # High risk but experienced
+      on high_risk, 2.0                  # Just high risk
+      on low_risk & young_driver, 0.9    # ❌ low_risk is undefined (typo for input.risk_category)
       base 1.0
     end
     
-    # Problem: Veteran bonus conflicts with senior cap
-    value :experience_bonus do
-      on veteran, 2.0      # Veterans get 2x bonus
-      on senior, 1.5       # Seniors get 1.5x bonus  
+    # Claims history impact
+    trait :claims_free, fn(:not, input.has_claims)
+    trait :perfect_record, claims_free & experienced & fn(:not, young_driver)
+    
+    # Discount calculation with type error
+    value :experience_discount do
+      on perfect_record, input.years_experience + "%" # ❌ String concatenation with integer
+      on claims_free, 0.95
       base 1.0
     end
     
-    value :total_rate, base_rate * regional_bonus * experience_bonus
+    # Premium calculation chain
+    value :adjusted_premium, base_premium * experience_factor * risk_multiplier
+    
+    # Age-based impossible logic
+    trait :mature_professional, senior_driver & experienced & young_driver  # ❌ Can't be senior AND young
     
-    # Business rule error: Veterans (10+ years) are also seniors (5+ years)
-    # This creates impossible logic in commission caps
-    trait :capped_senior, :senior & (total_rate <= 0.10)  # Senior cap
-    trait :uncapped_veteran, :veteran & (total_rate > 0.10)  # Veteran override
+    # Final premium with self-referencing cascade
+    value :final_premium do
+      on mature_professional, adjusted_premium * 0.8
+      on senior_driver, adjusted_premium * senior_adjustment  # ❌ senior_adjustment undefined
+      base final_premium * 1.1  # ❌ Self-reference in base case
+    end
     
-    value :final_commission do
-      on capped_senior & uncapped_veteran, "Impossible!"  # Can't be both
-      on uncapped_veteran, input.sales_amount * total_rate
-      on capped_senior, input.sales_amount * 0.10
-      base input.sales_amount * total_rate
+    # Monthly payment calculation with function arity error
+    value :monthly_payment, fn(:divide, final_premium)  # ❌ divide needs 2 arguments, got 1
+  end
+end
+
+# Static analysis catches these errors:
+# ❌ Circular reference: experience_factor → experience_discount → experience_factor
+# ❌ Undefined reference: low_risk (should be input.risk_category == "low")
+# ❌ Type mismatch: integer + string in experience_discount
+# ❌ Impossible conjunction: senior_driver & young_driver
+# ❌ Undefined reference: senior_adjustment
+# ❌ Self-reference cycle: final_premium references itself in base case
+# ❌ Function arity error: divide expects 2 arguments, got 1
+```
+
+**Bounded Recursion**: Kumi allows mutual recursion when cascade conditions are mutually exclusive:
+
+```ruby
+trait :is_forward, input.operation == "forward"
+trait :is_reverse, input.operation == "reverse"
+
+# Safe mutual recursion - conditions are mutually exclusive
+value :forward_processor do
+  on is_forward, input.value * 2        # Direct calculation
+  on is_reverse, reverse_processor + 10  # Delegates to reverse (safe)
+  base "invalid operation"
+end
+
+value :reverse_processor do
+  on is_forward, forward_processor - 5   # Delegates to forward (safe) 
+  on is_reverse, input.value / 2         # Direct calculation
+  base "invalid operation"
+end
+
+# Usage examples:
+# operation="forward", value=10  => forward: 20, reverse: 15
+# operation="reverse", value=10  => forward: 15, reverse: 5  
+# operation="unknown", value=10  => both: "invalid operation"
+```
+
+This compiles because `operation` can only be "forward" or "reverse", never both. Each recursion executes one step before hitting a direct calculation.
+
+</details>
+
+<details>
+<summary><strong>🔍 Array Broadcasting</strong> - Automatic vectorization over array fields</summary>
+
+### Array Broadcasting
+
+Kumi broadcasts operations over array fields for element-wise computation:
+
+```ruby
+schema do
+  input do
+    array :line_items do
+      float   :price
+      integer :quantity
+      string  :category
     end
+    float :tax_rate
   end
+
+  # Element-wise computation - broadcasts over each item
+  value :subtotals, input.line_items.price * input.line_items.quantity
+  
+  # Element-wise traits - applied to each item
+  trait :is_taxable, (input.line_items.category != "digital")
+  
+  # Aggregation operations - consume arrays to produce scalars
+  value :total_subtotal, fn(:sum, subtotals)
+  value :item_count, fn(:size, input.line_items)
 end
+```
+
+**Dimension Mismatch Detection**: Operations across different arrays generate error messages:
 
-# => conjunction `capped_senior AND uncapped_veteran` is impossible
+```ruby
+schema do
+  input do
+    array :items do
+      string :name
+    end
+    array :logs do  
+      string :user_name
+    end
+  end
+
+  # This generates an error
+  trait :same_name, input.items.name == input.logs.user_name
+end
+
+# Error:
+# Cannot broadcast operation across arrays from different sources: items, logs. 
+# Problem: Multiple operands are arrays from different sources:
+#   - Operand 1 resolves to array(string) from array 'items'
+#   - Operand 2 resolves to array(string) from array 'logs'
+# Direct operations on arrays from different sources is ambiguous and not supported.
 ```
 
+</details>
+
+<details>
+<summary><strong>💾 Automatic Memoization</strong> - Each value computed exactly once</summary>
+
 ### Automatic Memoization
 
 Each value is computed exactly once:
@@ -189,16 +303,21 @@ Each value is computed exactly once:
 runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
 
 # First access computes full dependency chain
-runner[:total_tax]     # => 52,937.50
+runner[:total_tax]     # => 53,155.20
 
 # Subsequent access uses cached values
-runner[:fed_tax]       # => 37,437.50 (cached)
-runner[:after_tax]     # => 197,062.50 (cached)
+runner[:fed_tax]       # => 39,077.00 (cached)
+runner[:after_tax]     # => 196,844.80 (cached)
 ```
 
+</details>
+
+<details>
+<summary><strong>🔍 Introspection</strong> - See exactly how values are calculated</summary>
+
 ### Introspection
 
-See exactly how any value was calculated:
+Show how values are calculated:
 
 ```ruby
 Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
@@ -209,10 +328,13 @@ Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_st
 #    = 15,099.50
 ```
 
-## Suggested Use Cases
+</details>
+
+## Usage
 
+**Suitable for:**
 - Complex interdependent business rules
-- Tax calculation engines (as demonstrated)
+- Tax calculation engines
 - Insurance premium calculators
 - Loan amortization schedules
 - Commission structures with complex tiers
@@ -233,7 +355,7 @@ Benchmarks on Linux with Ruby 3.3.8 on a Dell Latitude 7450:
 
 ## Learn More
 
-- [DSL Syntax Reference](documents/SYNTAX.md)
+- [DSL Syntax Reference](docs/SYNTAX.md)
 - [Examples](examples/)/
 
 ## Contributing

data/{documents → docs}/AST.md

@@ -7,22 +7,22 @@
 Root = Struct.new(:inputs, :attributes, :traits)
 ```
 
-**FieldDecl**: Input field metadata  
+**InputDeclaration**: Input field metadata  
 ```ruby
-FieldDecl = Struct.new(:name, :domain, :type)
-# DSL: integer :age, domain: 18..65 → FieldDecl(:age, 18..65, :integer)
+InputDeclaration = Struct.new(:name, :domain, :type)
+# DSL: integer :age, domain: 18..65 → InputDeclaration(:age, 18..65, :integer)
 ```
 
-**Trait**: Boolean predicate
+**TraitDeclaration**: Boolean predicate
 ```ruby  
-Trait = Struct.new(:name, :expression)
-# DSL: trait :adult, (input.age >= 18) → Trait(:adult, CallExpression(...))
+TraitDeclaration = Struct.new(:name, :expression)
+# DSL: trait :adult, (input.age >= 18) → TraitDeclaration(:adult, CallExpression(...))
 ```
 
-**Attribute**: Computed value
+**ValueDeclaration**: Computed value
 ```ruby
-Attribute = Struct.new(:name, :expression)  
-# DSL: value :total, fn(:add, a, b) → Attribute(:total, CallExpression(:add, [...]))
+ValueDeclaration = Struct.new(:name, :expression)  
+# DSL: value :total, fn(:add, a, b) → ValueDeclaration(:total, CallExpression(:add, [...]))
 ```
 
 ## Expression Nodes
@@ -33,18 +33,18 @@ CallExpression = Struct.new(:fn_name, :args)
 def &(other) = CallExpression.new(:and, [self, other])  # Enable chaining
 ```
 
-**FieldRef**: Field access (`input.field_name`)
+**InputReference**: Field access (`input.field_name`)
 ```ruby
-FieldRef = Struct.new(:name)
+InputReference = Struct.new(:name)
 # Has operator methods: >=, <=, >, <, ==, != that create CallExpression nodes
 ```
 
-**Binding**: References to other declarations
+**DeclarationReference**: References to other declarations
 ```ruby
-Binding = Struct.new(:name)
+DeclarationReference = Struct.new(:name)
 # Created by: ref(:name) OR bare identifier (trait_name) in composite traits
-# DSL: ref(:adult) → Binding(:adult)
-# DSL: adult & verified → CallExpression(:and, [Binding(:adult), Binding(:verified)])
+# DSL: ref(:adult) → DeclarationReference(:adult)
+# DSL: adult & verified → CallExpression(:and, [DeclarationReference(:adult), DeclarationReference(:verified)])
 ```
 
 **Literal**: Constants (`18`, `"text"`, `true`) 
@@ -52,9 +52,9 @@ Binding = Struct.new(:name)
 Literal = Struct.new(:value)
 ```
 
-**ListExpression**: Arrays (`[1, 2, 3]`)
+**ArrayExpression**: Arrays (`[1, 2, 3]`)
 ```ruby
-ListExpression = Struct.new(:elements)
+ArrayExpression = Struct.new(:elements)
 ```
 
 ## Cascade Expressions (Conditional Values)
@@ -64,9 +64,9 @@ ListExpression = Struct.new(:elements)
 CascadeExpression = Struct.new(:cases)
 ```
 
-**WhenCaseExpression**: Individual conditions
+**CaseExpression**: Individual conditions
 ```ruby
-WhenCaseExpression = Struct.new(:condition, :result)
+CaseExpression = Struct.new(:condition, :result)
 ```
 
 **Case type mappings**:
@@ -76,7 +76,7 @@ WhenCaseExpression = Struct.new(:condition, :result)
 
 ## Key Nuances
 
-**Operator methods on FieldRef**: Enable `input.age >= 18` syntax by defining operators that create `CallExpression` nodes
+**Operator methods on InputReference**: Enable `input.age >= 18` syntax by defining operators that create `CallExpression` nodes
 
 **CallExpression `&` method**: Enables expression chaining like `(expr1) & (expr2)`
 
@@ -92,14 +92,14 @@ WhenCaseExpression = Struct.new(:condition, :result)
 
 **Simple**: `(input.age >= 18)`
 ```
-CallExpression(:>=, [FieldRef(:age), Literal(18)])
+CallExpression(:>=, [InputReference(:age), Literal(18)])
 ```
 
 **Chained AND**: `(input.age >= 21) & (input.verified == true)`  
 ```
 CallExpression(:and, [
-  CallExpression(:>=, [FieldRef(:age), Literal(21)]),
-  CallExpression(:==, [FieldRef(:verified), Literal(true)])
+  CallExpression(:>=, [InputReference(:age), Literal(21)]),
+  CallExpression(:==, [InputReference(:verified), Literal(true)])
 ])
 ```
 
@@ -107,10 +107,10 @@ CallExpression(:and, [
 ```
 CallExpression(:and, [
   CallExpression(:and, [
-    Binding(:adult),
-    Binding(:verified)
+    DeclarationReference(:adult),
+    DeclarationReference(:verified)
   ]),
-  Binding(:high_income)
+  DeclarationReference(:high_income)
 ])
 ```
 
@@ -118,9 +118,9 @@ CallExpression(:and, [
 ```
 CallExpression(:and, [
   CallExpression(:and, [
-    Binding(:adult),
-    CallExpression(:>, [FieldRef(:score), Literal(80)])
+    DeclarationReference(:adult),
+    CallExpression(:>, [InputReference(:score), Literal(80)])
   ]),
-  Binding(:verified)
+  DeclarationReference(:verified)
 ])
 ```