kumi 0.0.5 → 0.0.6

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,7 +188,7 @@ value :sorted_scores, fn(:sort, input.score_array)
 
 ### Built-in Functions Available
 
-See [FUNCTIONS.md](documents/FUNCTIONS.md)
+See [FUNCTIONS.md](FUNCTIONS.md)
 
 | Category | Sugar | Sugar-Free |
 |----------|-------|------------|
@@ -210,6 +211,97 @@ value :clamped_score, fn(:clamp, input.raw_score, 0, 1600)
 value :formatted_name, fn(:add, fn(:add, input.first_name, " "), input.last_name)
 ```
 
+## Array Broadcasting
+
+Array broadcasting enables element-wise operations on array fields with automatic vectorization.
+
+### Array Input Declarations
+
+```ruby
+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
+
+```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.

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

data/docs/features/array-broadcasting.md

@@ -0,0 +1,170 @@
+# Array Broadcasting
+
+Automatic vectorization of operations over array fields with element-wise computation and aggregation.
+
+## Overview
+
+The array broadcasting system enables natural field access syntax on array inputs (`input.items.price`) that automatically applies operations element-wise across the array, with intelligent detection of map vs reduce operations.
+
+## Core Mechanism
+
+The system uses a three-stage pipeline:
+
+1. **Parser** - Creates InputElementReference AST nodes for nested field access
+2. **BroadcastDetector** - Identifies which operations should be vectorized vs scalar
+3. **Compiler** - Generates appropriate map/reduce functions based on usage context
+
+## Basic Broadcasting
+
+```ruby
+schema do
+  input do
+    array :line_items do
+      float   :price
+      integer :quantity
+      string  :category
+    end
+    scalar :tax_rate, type: :float
+  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")
+  
+  # Conditional logic - element-wise evaluation
+  value :taxes, fn(:if, is_taxable, subtotals * input.tax_rate, 0.0)
+end
+```
+
+## Aggregation Operations
+
+Operations that consume arrays to produce scalars are automatically detected:
+
+```ruby
+schema do
+  # These aggregate the vectorized results
+  value :total_subtotal, fn(:sum, subtotals)
+  value :total_tax, fn(:sum, taxes)
+  value :grand_total, total_subtotal + total_tax
+  
+  # Statistics over arrays
+  value :avg_price, fn(:avg, input.line_items.price)
+  value :max_quantity, fn(:max, input.line_items.quantity)
+end
+```
+
+## Field Access Nesting
+
+Supports arbitrary depth field access with path building:
+
+```ruby
+schema do
+  input do
+    array :orders do
+      array :items do
+        hash :product do
+          string :name
+          float  :base_price
+        end
+        integer :quantity
+      end
+    end
+  end
+
+  # Deep field access - automatically broadcasts over nested arrays  
+  value :all_product_names, input.orders.items.product.name
+  value :total_values, input.orders.items.product.base_price * input.orders.items.quantity
+end
+```
+
+## Type Inference
+
+The type system automatically infers appropriate types for broadcasted operations:
+
+- `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
+
+## Implementation Details
+
+### Parser Layer
+- **InputFieldProxy** - Handles `input.field.subfield...` with path building
+- **InputElementReference** - AST node representing array field access paths
+
+### Analysis Layer  
+- **BroadcastDetector** - Identifies vectorized vs scalar operations
+- **TypeInferencer** - Infers types for array element access patterns
+
+### Compilation Layer
+- **Automatic Dispatch** - Maps element-wise operations to array map functions
+- **Reduction Detection** - Converts aggregation functions to array reduce operations
+
+## Usage Patterns
+
+### Element-wise Operations
+```ruby
+# All of these broadcast element-wise
+value :discounted_prices, input.items.price * 0.9
+trait :expensive, (input.items.price > 100.0)  
+value :categories, input.items.category
+```
+
+### Aggregation Operations
+```ruby
+# These consume arrays to produce scalars
+value :item_count, fn(:size, input.items)
+value :total_price, fn(:sum, input.items.price)
+value :has_expensive, fn(:any?, expensive)
+```
+
+### Mixed Operations
+```ruby
+# Element-wise computation followed by 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)
+```
+
+## Error Handling
+
+### Dimension Mismatch Detection
+
+Array broadcasting operations are only valid within the same array source. Attempting to broadcast across different arrays generates detailed error messages:
+
+```ruby
+schema do
+  input do
+    array :items do
+      string :name
+    end
+    array :logs do  
+      string :user_name
+    end
+  end
+
+  # This will generate a dimension mismatch 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. 
+# Vectorized operations can only work on fields from the same array input.
+```
+
+The error messages provide:
+- **Quick Summary**: Identifies the conflicting array sources
+- **Type Information**: Shows the resolved types of each operand  
+- **Clear Explanation**: Why the operation is ambiguous and not supported
+
+## Performance Characteristics
+
+- **Single Pass** - Each array is traversed once per computation chain
+- **Lazy Evaluation** - Operations are composed into efficient pipelines  
+- **Memory Efficient** - No intermediate array allocations for simple operations
+- **Type Safe** - Full compile-time type checking for array element operations

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

@@ -0,0 +1,42 @@
+# Input Declarations
+
+Declares expected inputs with types and domain constraints, separating input metadata from business logic.
+
+## Declaration Syntax
+
+```ruby
+schema do
+  input do
+    string  :customer_name
+    integer :age, domain: 18..120
+    float   :balance, domain: 0.0..Float::INFINITY
+    boolean :verified
+    array   :tags, elem: { type: :string }
+    hash    :metadata, key: { type: :string }, val: { type: :any }
+    any     :flexible
+  end
+  
+  trait :adult, (input.age >= 18)
+  value :status, input.verified ? "verified" : "pending"
+end
+```
+
+## Domain Constraints
+
+**Validation occurs at runtime:**
+```ruby
+schema.from(credit_score: 900)  # Domain: 300..850
+# => InputValidationError: Field :credit_score value 900 is outside domain 300..850
+```
+
+**Constraint types:**
+- Range domains: `domain: 18..120`
+- Array domains: `domain: %w[active inactive]`
+- Regex domains: `domain: /^[a-zA-Z]+$/`
+
+## Validation Process
+
+- Input data validated against declared field metadata
+- Type validation checks value matches declared type
+- Domain validation checks value satisfies constraints
+- Detailed error messages for violations

data/docs/features/performance.md

@@ -0,0 +1,16 @@
+# Performance
+
+TODO: Add benchmark data
+
+Processes large schemas with optimized algorithms for analysis, compilation, and execution.
+
+## Execution Model
+
+**Compilation:**
+- Each expression compiled to executable lambda
+- Direct function calls for operations
+
+**Runtime:**
+- Result caching to avoid recomputation
+- Selective evaluation: only requested keys computed
+- Direct lambda invocation

data/examples/federal_tax_calculator_2024.rb

@@ -28,7 +28,7 @@ module FederalTaxCalculator
   schema do
     input do
       float  :income
-      string :filing_status, domain: %(single married_joint married_separate head_of_household)
+      string :filing_status, domain: %w[single married_joint married_separate head_of_household]
     end
 
     # ── standard deduction table ───────────────────────────────────────
@@ -59,7 +59,7 @@ module FederalTaxCalculator
 
     value :fed_tax,       fed_calc[0]
     value :fed_marginal,  fed_calc[1]
-    value :fed_eff,       fed_tax / f[input.income, 1.0].max
+    value :fed_eff,       fed_tax / [input.income, 1.0].max
 
     # ── FICA (employee share) ─────────────────────────────────────────────
     value :ss_wage_base, 168_600.0
@@ -96,10 +96,11 @@ module FederalTaxCalculator
   end
 end
 
-def calculate_tax(calculator, income: 1_000_000, status: "single")
+def print_tax_summary(args)
+  r = FederalTaxCalculator.from(args)
   puts "\n=== 2024 U.S. Income‑Tax Example ==="
-  printf "Income:                      $%0.2f\n", income
-  puts   "Filing status:               #{status}\n\n"
+  printf "Income:                      $%0.2f\n", args[:income]
+  puts   "Filing status:               #{args[:filing_status]}\n\n"
 
   puts "Federal tax:             $#{r[:fed_tax].round(2)} (#{(r[:fed_eff] * 100).round(2)}% effective)"
   puts "FICA tax:                $#{r[:fica_tax].round(2)} (#{(r[:fica_eff] * 100).round(2)}% effective)"
@@ -107,4 +108,8 @@ def calculate_tax(calculator, income: 1_000_000, status: "single")
   puts "After-tax income:        $#{r[:after_tax].round(2)}"
 end
 
-calculate_tax(FederalTaxCalculator, income: 1_000_000, status: "single")
+
+input = {  income: 1_000_000,
+  filing_status: "single"
+}
+print_tax_summary(input)

data/lib/kumi/analyzer/constant_evaluator.rb

@@ -23,7 +23,7 @@ module Kumi
         return node.value if node.is_a?(Literal)
 
         result = case node
-                 when Binding then evaluate_binding(node, visited)
+                 when DeclarationReference then evaluate_binding(node, visited)
                  when CallExpression then evaluate_call_expression(node, visited)
                  else :unknown
                  end