kumi 0.0.5 → 0.0.7

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
+    float :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/docs/schema_metadata/broadcasts.md

@@ -0,0 +1,53 @@
+# Broadcasts Metadata
+
+Array broadcasting operation analysis for vectorized computations.
+
+## Structure
+
+```ruby
+state[:broadcasts] = {
+  array_fields: Hash,
+  vectorized_operations: Hash,
+  reduction_operations: Hash
+}
+```
+
+## Array Fields
+
+```ruby
+array_fields: {
+  :line_items => {
+    element_fields: [:price, :quantity, :name],
+    element_types: { price: :float, quantity: :integer, name: :string }
+  }
+}
+```
+
+## Vectorized Operations
+
+```ruby
+vectorized_operations: {
+  :item_totals => {
+    operation: :multiply,
+    vectorized_args: { 0 => true, 1 => true }
+  }
+}
+```
+
+## Reduction Operations
+
+```ruby
+reduction_operations: {
+  :total_amount => {
+    function: :sum,
+    source: :array_field
+  }
+}
+```
+
+## Usage
+
+- Compiler optimizations
+- Parallel execution
+- Type inference
+- Performance analysis

data/docs/schema_metadata/cascades.md

@@ -0,0 +1,45 @@
+# Cascades Metadata
+
+Cascade mutual exclusion analysis for safe conditional cycles.
+
+## Structure
+
+```ruby
+state[:cascades] = {
+  cascade_name => {
+    condition_traits: Array,
+    condition_count: Integer,
+    all_mutually_exclusive: Boolean,
+    exclusive_pairs: Integer,
+    total_pairs: Integer
+  }
+}
+```
+
+## Example
+
+```ruby
+{
+  :tax_rate => {
+    condition_traits: [:single, :married],
+    condition_count: 2,
+    all_mutually_exclusive: true,
+    exclusive_pairs: 1,
+    total_pairs: 1
+  }
+}
+```
+
+## Fields
+
+- `condition_traits`: Trait names used in cascade conditions
+- `all_mutually_exclusive`: Whether all condition pairs are exclusive
+- `exclusive_pairs`: Count of mutually exclusive pairs
+- `total_pairs`: Total possible pairs
+
+## Usage
+
+- Cycle safety analysis
+- Topological sorting
+- Optimization detection
+- Dependency validation

data/docs/schema_metadata/declarations.md

@@ -0,0 +1,54 @@
+# Declarations Metadata
+
+Processed declaration metadata for all schema declarations (traits and values) with clean, serializable information.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+declarations = metadata.declarations
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Hash>
+{
+  declaration_name => {
+    type: :trait | :value,  # Declaration type
+    expression: String      # Human-readable expression
+  }
+}
+```
+
+## Example
+
+```ruby
+metadata.declarations
+# => {
+#   :adult => { type: :trait, expression: ">=(input.age, 18)" },
+#   :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" },
+#   :status => { type: :value, expression: "cascade" }
+# }
+```
+
+## Raw AST Access
+
+For advanced use cases requiring direct AST manipulation:
+
+```ruby
+raw_declarations = metadata.analyzer_state[:declarations]
+# => { :adult => #<TraitDeclaration...>, :tax_amount => #<ValueDeclaration...> }
+```
+
+## AST Node Types
+
+- **TraitDeclaration**: Boolean conditions  
+- **ValueDeclaration**: Computed values or cascades
+
+## Usage
+
+- Dependency analysis
+- Code generation  
+- AST traversal
+- Type inference

data/docs/schema_metadata/dependencies.md

@@ -0,0 +1,57 @@
+# Dependencies Metadata
+
+Processed dependency information showing relationships between declarations with clean, serializable data.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+dependencies = metadata.dependencies
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Array<Hash>>
+{
+  declaration_name => [
+    {
+      to: Symbol,           # Target declaration name
+      conditional: Boolean, # True if dependency is conditional (cascade branch)
+      cascade_owner: Symbol # Optional: cascade that owns this conditional edge
+    }
+  ]
+}
+```
+
+## Example
+
+```ruby
+metadata.dependencies
+# => {
+#   :tax_amount => [
+#     { to: :income, conditional: false },
+#     { to: :deductions, conditional: false }
+#   ],
+#   :status => [
+#     { to: :adult, conditional: true, cascade_owner: :status },
+#     { to: :verified, conditional: true, cascade_owner: :status }
+#   ]
+# }
+```
+
+## Raw Edge Objects
+
+For advanced use cases requiring direct Edge object access:
+
+```ruby
+raw_dependencies = metadata.analyzer_state[:dependencies]
+# => { :tax_amount => [#<Edge to: :income>, #<Edge to: :deductions>] }
+```
+
+## Usage
+
+- Topological sorting
+- Cycle detection  
+- Evaluation planning
+- Dependency visualization

data/docs/schema_metadata/evaluation_order.md

@@ -0,0 +1,29 @@
+# Evaluation Order Metadata
+
+Topologically sorted order for safe declaration evaluation.
+
+## Structure
+
+```ruby
+state[:evaluation_order] = [:name1, :name2, :name3, ...]
+```
+
+## Example
+
+```ruby
+[:income, :deductions, :taxable_income, :tax_rate, :tax_amount, :adult, :status]
+```
+
+## Properties
+
+- Dependencies appear before dependents  
+- Handles conditional cycles in cascades
+- Deterministic ordering
+- Leaf nodes typically appear first
+
+## Usage
+
+- Compilation order
+- Evaluation sequencing  
+- Optimization planning
+- Parallel execution grouping