kumi 0.0.4 → 0.0.6

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)
 ])
 ```

data/{documents → docs}/DSL.md

@@ -109,13 +109,13 @@ For conditional logic, a `value` takes a block to create a **cascade**. Cascades
 ```ruby
 value :access_level do
   # `on` implies AND: user must be :premium AND :verified.
-  on :premium, :verified, "Full Access"
+  on premium,verified, "Full Access"
 
   # `on_any` implies OR: user can be :staff OR :admin.
-  on_any :staff, :admin, "Elevated Access"
+  on_any staff,admin, "Elevated Access"
 
   # `on_none` implies NOT (A OR B): user is neither :blocked NOR :suspended.
-  on_none :blocked, :suspended, "Limited Access"
+  on_none blocked,suspended, "Limited Access"
 
   # `base` is the default if no other conditions match.
   base "No Access"

data/{documents → docs}/SYNTAX.md

@@ -10,6 +10,7 @@ This document provides a comprehensive comparison of Kumi's DSL syntax showing b
 - [Trait Declarations](#trait-declarations)
 - [Expressions](#expressions)
 - [Functions](#functions)
+- [Array Broadcasting](#array-broadcasting)
 - [Cascade Logic](#cascade-logic)
 - [References](#references)
 
@@ -187,11 +188,13 @@ value :sorted_scores, fn(:sort, input.score_array)
 
 ### Built-in Functions Available
 
+See [FUNCTIONS.md](FUNCTIONS.md)
+
 | Category | Sugar | Sugar-Free |
 |----------|-------|------------|
 | **Arithmetic** | `+`, `-`, `*`, `/`, `**` | `fn(:add, a, b)`, `fn(:subtract, a, b)`, etc. |
 | **Comparison** | `>`, `<`, `>=`, `<=`, `==`, `!=` | `fn(:>, a, b)`, `fn(:<, a, b)`, etc. |
-| **Logical** | `&` (AND only) | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
+| **Logical** | `&` `|` | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
 | **Math** | `abs`, `round`, `ceil`, `floor` | `fn(:abs, x)`, `fn(:round, x)`, etc. |
 | **String** | `.length`, `.upcase`, `.downcase` | `fn(:string_length, s)`, `fn(:upcase, s)`, etc. |
 | **Collection** | `.sum`, `.size`, `.max`, `.min` | `fn(:sum, arr)`, `fn(:size, arr)`, etc. |
@@ -208,31 +211,110 @@ value :clamped_score, fn(:clamp, input.raw_score, 0, 1600)
 value :formatted_name, fn(:add, fn(:add, input.first_name, " "), input.last_name)
 ```
 
-## Cascade Logic
+## Array Broadcasting
+
+Array broadcasting enables element-wise operations on array fields with automatic vectorization.
 
-Cascade syntax is the same in both approaches, but conditions use different syntax:
+### Array Input Declarations
 
 ```ruby
-# With Sugar
-value :grade_letter do
-  on :excellent_student, "A+"
-  on :high_scorer, "A"
-  on :above_average, "B"
-  on :needs_improvement, "C"
-  base "F"
+input do
+  array :line_items do
+    float   :price
+    integer :quantity
+    string  :category
+  end
+  
+  array :orders do
+    array :items do
+      hash :product do
+        string :name
+        float  :base_price
+      end
+      integer :quantity
+    end
+  end
 end
+```
+
+### Element-wise Operations
+
+```ruby
+# With Sugar - Automatic Broadcasting
+value :subtotals, input.line_items.price * input.line_items.quantity
+trait :is_taxable, (input.line_items.category != "digital")
+value :discounted_prices, input.line_items.price * 0.9
+
+# Sugar-Free - Explicit Broadcasting  
+value :subtotals, fn(:multiply, input.line_items.price, input.line_items.quantity)
+trait :is_taxable, fn(:!=, input.line_items.category, "digital")
+value :discounted_prices, fn(:multiply, input.line_items.price, 0.9)
+```
+
+### Aggregation Operations
 
-# Sugar-Free  
+```ruby
+# With Sugar - Automatic Aggregation Detection
+value :total_subtotal, fn(:sum, subtotals)
+value :avg_price, fn(:avg, input.line_items.price)
+value :max_quantity, fn(:max, input.line_items.quantity)
+value :item_count, fn(:size, input.line_items)
+
+# Sugar-Free - Same Syntax
+value :total_subtotal, fn(:sum, subtotals)
+value :avg_price, fn(:avg, input.line_items.price)
+value :max_quantity, fn(:max, input.line_items.quantity)
+value :item_count, fn(:size, input.line_items)
+```
+
+### Nested Array Access
+
+```ruby
+# With Sugar - Deep Field Access
+value :all_product_names, input.orders.items.product.name
+value :total_values, input.orders.items.product.base_price * input.orders.items.quantity
+
+# Sugar-Free - Same Deep Access
+value :all_product_names, input.orders.items.product.name
+value :total_values, fn(:multiply, input.orders.items.product.base_price, input.orders.items.quantity)
+```
+
+### Mixed Operations
+
+```ruby
+# With Sugar - Element-wise then Aggregation
+value :line_totals, input.items.price * input.items.quantity
+value :order_total, fn(:sum, line_totals)
+value :avg_line_total, fn(:avg, line_totals)
+trait :has_expensive, fn(:any?, expensive_items)
+
+# Sugar-Free - Same Pattern
+value :line_totals, fn(:multiply, input.items.price, input.items.quantity)
+value :order_total, fn(:sum, line_totals)
+value :avg_line_total, fn(:avg, line_totals)
+trait :has_expensive, fn(:any?, expensive_items)
+```
+
+### Broadcasting Type Inference
+
+The type system automatically infers appropriate types:
+- `input.items.price` (float array) → inferred as `:float` per element
+- `input.items.price * input.items.quantity` → element-wise `:float` result
+- `fn(:sum, input.items.price)` → scalar `:float` result
+
+## Cascade Logic
+
+Cascades are similar to Ruby when case, where each case is one of more trait reference and finally the value if that branch is true.
+```ruby
 value :grade_letter do
-  on :excellent_student, "A+"
-  on :high_scorer, "A"
-  on :above_average, "B"
-  on :needs_improvement, "C"
+  on excellent_student, "A+"       
+  on high_scorer, "A"              
+  on above_average, "B"            
+  on needs_improvement, "C"        
   base "F"
 end
 ```
 
-The difference is in how the traits referenced in cascade conditions are defined (see Trait Declarations above).
 
 ## References
 
@@ -287,9 +369,9 @@ module StudentEvaluation
 
     # Cascade with sugar-defined traits
     value :scholarship_amount do
-      on :scholarship_candidate, 10000
-      on :high_performer, 5000
-      on :math_excellence, 2500
+      on scholarship_candidate, 10000
+      on high_performer, 5000
+      on math_excellence, 2500
       base 0
     end
   end
@@ -324,9 +406,9 @@ module StudentEvaluation
 
     # Cascade with sugar-free defined traits
     value :scholarship_amount do
-      on :scholarship_candidate, 10000
-      on :high_performer, 5000
-      on :math_excellence, 2500
+      on scholarship_candidate, 10000
+      on high_performer, 5000
+      on math_excellence, 2500
       base 0
     end
   end
@@ -351,10 +433,11 @@ end
 ## Syntax Limitations
 
 ### Sugar Syntax Limitations:
-- Only supports `&` for logical AND (no `&&` due to Ruby precedence)
-- No logical OR sugar syntax (must use `fn(:or, a, b)`)
+- Supports `&` for logical AND (no `&&` due to Ruby precedence)
+- Supports `|` for logical OR
 - Limited operator precedence control
 - Some Ruby methods not available as sugar
+- **Refinement scope**: Array methods like `.max` on syntax expressions may not work in certain contexts (e.g., test helpers, Ruby < 3.0). Use `fn(:max, array)` instead.
 
 ### Sugar-Free Advantages:
 - Full access to all registered functions

data/docs/features/README.md

@@ -0,0 +1,45 @@
+# Features
+
+## Core Features
+
+### [Unsatisfiability Detection](analysis-unsat-detection.md)
+Analyzes rule combinations to detect logical impossibilities across dependency chains.
+
+- Detects impossible combinations at compile-time
+- Validates domain constraints
+- Reports multiple errors
+
+### [Cascade Mutual Exclusion](analysis-cascade-mutual-exclusion.md)
+Enables safe mutual recursion when cascade conditions are mutually exclusive.
+
+- Allows mathematically sound recursive patterns
+- Detects mutually exclusive conditions
+- Prevents unsafe cycles while enabling safe ones
+
+### [Type Inference](analysis-type-inference.md)  
+Determines types from expressions and propagates them through dependencies.
+
+- Infers types from literals and function calls
+- Propagates types through dependency graph
+- Validates function arguments
+
+### [Input Declarations](input-declaration-system.md)
+Defines expected inputs with types and constraints.
+
+- Type-specific declaration methods
+- Domain validation at runtime
+- Separates input metadata from business logic
+
+### [Performance](performance.md)
+TODO: Add benchmark data
+Processes large schemas with optimized algorithms.
+
+- Result caching
+- Selective evaluation
+
+## Integration
+
+- Type inference uses input declarations
+- Unsatisfiability detection uses type information for validation
+- Cascade mutual exclusion integrates with dependency analysis and cycle detection
+- Performance optimizations apply to all analysis passes

data/docs/features/analysis-cascade-mutual-exclusion.md

@@ -0,0 +1,89 @@
+# Cascade Mutual Exclusion Detection
+
+Analyzes cascade expressions to allow safe recursive patterns when conditions are mutually exclusive.
+
+## Overview
+
+The cascade mutual exclusion detector identifies when all conditions in a cascade expression cannot be true simultaneously, enabling safe mutual recursion patterns that would otherwise be rejected as cycles.
+
+## Core Mechanism
+
+The system performs three-stage analysis:
+
+1. **Conditional Dependency Tracking** - DependencyResolver marks base case dependencies as conditional
+2. **Mutual Exclusion Analysis** - UnsatDetector determines if cascade conditions are mutually exclusive  
+3. **Safe Cycle Detection** - Toposorter allows cycles where all edges are conditional and conditions are mutually exclusive
+
+## Example: Processing Workflow
+
+```ruby
+schema do
+  input do
+    string :operation  # "forward", "reverse", "unknown"
+    integer :value
+  end
+
+  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"               # Fallback for unknown operations
+  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"               # Fallback for unknown operations
+  end
+end
+```
+
+## Safety Guarantees
+
+**Allowed**: Cycles where conditions are mutually exclusive
+- `is_forward` and `is_reverse` cannot both be true (operation has single value)
+- Each recursion executes exactly one step before hitting direct calculation
+- Bounded recursion with guaranteed termination
+
+**Rejected**: Cycles with overlapping conditions
+```ruby
+# This would be rejected - conditions can overlap
+value :unsafe_cycle do
+  on input.n > 0, "positive"
+  on input.n > 5, "large"  # Both can be true!
+  base fn(:not, unsafe_cycle)
+end
+```
+
+## Implementation Details
+
+### Conditional Dependencies
+Base case dependencies are marked as conditional because they only execute when no explicit conditions match.
+
+### Mutual Exclusion Analysis
+Conditions are analyzed for mutual exclusion:
+- Same field equality comparisons: `field == value1` vs `field == value2`
+- Domain constraints ensuring impossibility
+- All condition pairs must be mutually exclusive
+
+### Metadata Generation
+Analysis results stored in `cascade_metadata` state:
+```ruby
+{
+  condition_traits: [:is_forward, :is_reverse],
+  condition_count: 2,
+  all_mutually_exclusive: true,
+  exclusive_pairs: 1,
+  total_pairs: 1
+}
+```
+
+## Use Cases
+
+- Processing workflows with bidirectional logic
+- State machine fallback patterns  
+- Recursive decision trees with termination conditions
+- Complex business rules with safe delegation patterns

data/docs/features/analysis-type-inference.md

@@ -0,0 +1,42 @@
+# Type Inference
+
+Infers types from expressions and propagates them through dependency chains for compile-time type checking.
+
+## Type Inference Rules
+
+**Literals:**
+- `42` → `:integer`
+- `3.14` → `:float` 
+- `"hello"` → `:string`
+- `true` → `:boolean`
+- `[1, 2, 3]` → `{ array: :integer }`
+
+**Operations:**
+- Integer arithmetic → `:integer`
+- Mixed numeric operations → `:numeric`
+- Comparisons → `:boolean`
+
+**Functions:**
+- Return types defined in function registry
+- Arguments validated against parameter types
+
+## Error Detection
+
+**Type mismatches:**
+```
+TypeError: argument 2 of addition expects numeric, got input field `age` of declared type integer,
+but argument 1 is input field `customer_name` of declared type string
+```
+
+**Function validation:**
+- Arity validation (correct number of arguments)
+- Type compatibility validation
+- Unknown function detection
+
+## Inference Process
+
+- Processes declarations in topological order to resolve dependencies
+- Literal types determined from values
+- Function return types from function registry
+- Array types unified from element types
+- Cascade types inferred from result expressions

data/docs/features/analysis-unsat-detection.md

@@ -0,0 +1,71 @@
+# Unsatisfiability Detection
+
+Analyzes logical relationships across dependency chains to detect impossible rule combinations at compile time.
+
+## Example: Credit Card Approval System
+
+This schema contains impossible rule combinations:
+
+```ruby
+module CreditCardApproval
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      integer :annual_income
+      integer :monthly_debt
+      integer :credit_score, domain: 300..850
+      string  :employment_type, domain: %w[full_time part_time contract self_employed]
+    end
+
+    # Financial calculations
+    value :monthly_income, input.annual_income / 12
+    value :available_monthly, monthly_income - input.monthly_debt
+    value :credit_limit_base, input.annual_income * 0.3
+    value :score_multiplier, (input.credit_score - 600) * 0.01
+    value :final_credit_limit, credit_limit_base * score_multiplier
+    value :employment_stability_factor, 
+          input.employment_type == "full_time" ? 1.0 :
+          input.employment_type == "part_time" ? 0.7 :
+          input.employment_type == "contract" ? 0.5 : 0.3
+    
+    # Business rules
+    trait :stable_income, (input.annual_income >= 60_000)
+    trait :good_credit, (input.credit_score >= 700)
+    trait :high_available_income, (available_monthly >= 4_000)
+    trait :premium_limit_qualified, (final_credit_limit >= 50_000)
+    trait :stable_employment, (input.employment_type == "full_time")
+    trait :high_stability_factor, (employment_stability_factor >= 0.8)
+    trait :excellent_credit, (input.credit_score == 900)
+
+    # Approval tiers - which combinations are impossible?
+    value :approval_tier do
+      on stable_income,good_credit,premium_limit_qualified, "platinum_tier"
+      on stable_employment,high_stability_factor, "executive_tier"  
+      on excellent_credit,good_credit, "perfect_score_tier"
+      on stable_income,good_credit, "standard_tier"
+      base "manual_review"
+    end
+  end
+end
+```
+
+**Detected errors:**
+
+```
+SemanticError: 
+conjunction `excellent_credit AND good_credit` is impossible
+conjunction `excellent_credit` is impossible
+```
+
+**Root cause:**
+- `excellent_credit` requires `credit_score == 900`
+- Input domain constrains `credit_score` to `300..850`
+- Any cascade condition using `excellent_credit` becomes impossible
+
+## Detection Mechanisms
+
+- Domain constraint violations: `field == value` where value is outside declared domain
+- Cascade condition analysis: each `on` condition checked independently  
+- OR expression handling: impossible only if both sides are impossible
+- Cross-variable mathematical constraint analysis