kumi 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5f9f087001a482c906f041da8cb229511966a11c56e3ced99930b59d4141543
-  data.tar.gz: fe5fafe03a5ca1e414b5bc3af9eccd830553aa8f44762e9d9b38e589fa342fd1
+  metadata.gz: 98308b4c27cb40488f14215c8da9700c62a51fc54d11b9d822a1eb25d396a724
+  data.tar.gz: 3fbbb50dc0c74ba14d83fbcf71c5866efa814b71b4d2679c45b57d59a1f778da
 SHA512:
-  metadata.gz: b26279c08a9387616104252d24147c920f27b0f66574cde1987024325c5fd1ba87aff876b39fdc3d4f472d9aba2c713b19a5105890b66ac3ef10a3018a0b1bca
-  data.tar.gz: d4c8db755880cd7088fd4b6087d2f38e86a4fdee11f867d58a480e143494ca2b85440abd9249b8c02a469a9ad21642c287d5ef8f30948bdc6d67695a895c1c13
+  metadata.gz: 4453ea76de50c433696c3ae5ebe4d39ae049cb35e40f34cf9a3cce0e52e5d0967a8ccfd9ca7627eafe33444ea4da186015a59796a59e022fdf5b5edc04c50444
+  data.tar.gz: dfdb9f118ee7c0c16fa30392b3591b88c8320a2d19ff331253a4344e49fa773967e6b8d2451c0fd490f200171846fec2b408ecd000e6ad111e3c2d89bd92c000

data/CLAUDE.md

@@ -1,9 +1,11 @@
 # CLAUDE.md
 
+!! Important:
 !! 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.
+!! Disregard linting or coverage issues unless asked to do so.
+!! 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.
+!! See all Available Functions in docs/FUNCTIONS.md
 
 ## Project Overview
 
@@ -27,7 +29,7 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 
 **Schema System** (`lib/kumi/schema.rb`):
 - Entry point that ties together parsing, analysis, and compilation
-- Provides the `schema(&block)` DSL method that builds the syntax tree, runs analysis, and compiles to executable form
+- DSL method `schema(&block)` builds the syntax tree, runs analysis, and compiles to executable form
 - Generates a `Runner` instance for executing queries against input data
 
 **Parser** (`lib/kumi/ruby_parser{/*,.rb}`):
@@ -60,25 +62,19 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 - **Pass 8**: `type_checker.rb` - Validate function types and compatibility using inferred types
 
 **Compiler** (`lib/kumi/compiler.rb`):
-- Transforms analyzed syntax tree into executable lambda functions
+- Compiles analyzed syntax tree into executable lambda functions
 - Maps each expression type to a compilation method
 - Handles function calls via `Kumi::Registry`
 - Produces `CompiledSchema` with executable bindings
 
 **Function Registry** (`lib/kumi/function_registry.rb`):
 - Registry of available functions (operators, math, string, logical, collection operations)
-- Supports custom function registration with comprehensive type metadata
+- 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
 
-**Runner** (`lib/kumi/runner.rb`):
-- Executes compiled schemas against input data
-- Provides `fetch(key)` for individual value retrieval with caching
-- Provides `slice(*keys)` for batch evaluation
-- Provides `explain(key)` for detailed execution tracing
-
 **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
@@ -92,7 +88,7 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 
 ### Critical Syntax Rules
 
-**Module Definition Structure** (REQUIRED for CLI):
+**Module Definition Structure** 
 ```ruby
 # CORRECT - CLI can find and load this
 module SchemaName
@@ -102,11 +98,6 @@ module SchemaName
     # schema definition here
   end
 end
-
-# INCORRECT - CLI cannot load standalone schemas
-schema do  # This won't work with CLI
-  # schema definition
-end
 ```
 
 **Function Call Syntax**:
@@ -115,7 +106,7 @@ end
 **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**: Use sugar for simple operations, functions for complex ones
+- **Mixed**: Sugar syntax for basic operations, function syntax for complex ones
 
 **Cascade Condition Syntax**:
 ```ruby
@@ -159,13 +150,6 @@ end
 
 **IMPORTANT CASCADE CONDITION SYNTAX:**
 In cascade expressions (`value :name do ... end`), trait references use bare identifiers:
-```ruby
-value :status do
-  on adult, "Adult Status"      
-  on verified, "Verified User"
-  base "Unverified"
-end
-```
 
 **Input Block System**:
 - **Required**: All schemas must have an `input` block declaring expected fields
@@ -190,9 +174,9 @@ end
 4. Execute with Runner
 
 **Type System** (`lib/kumi/types.rb`):
-- Simple symbol-based type system for clean and intuitive declaration
+- Symbol-based type system
 - **Dual Type System**: Declared types (from input blocks) and inferred types (from expressions)
-- Automatic type inference for all declarations based on expression analysis
+- 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
@@ -201,13 +185,13 @@ end
 
 ### Examples Directory
 
-The `examples/` directory contains comprehensive examples showing Kumi usage patterns:
+The `examples/` directory contains 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)
+- `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` - Simple tax example with explain functionality (working)
-- `wide_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for wide schemas (compilation and evaluation scaling)
+- `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)
 
@@ -223,11 +207,11 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 ## Files for Understanding
 
 . `docs/*` - Documents about Kumi, its features, DSL syntax, ... 
-- `examples/*` Random examples of very diverse contexts.
+- `examples/*` Random examples of diverse contexts.
 
 ### Troubleshooting Schema Issues
 - **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
-- **Module Not Found**: Ensure proper module structure and naming, see examples
+- **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!
@@ -237,7 +221,7 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 ### 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 its not very useful.
+- **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.
 
@@ -263,13 +247,13 @@ input do
   hash         :metadata, key: { type: :string }, val: { type: :any }
 
   #generic type
-  any          :misc # this will make Kumi lose most of its analyze/inference power
+  any          :misc # this reduces Kumi's analyze/inference capabilities
 end
 ```
 
 ### Array Broadcasting System
 
-**Automatic Vectorization**: Field access on array inputs (`input.items.price`) applies operations element-wise with intelligent map/reduce detection.
+**Vectorization**: Field access on array inputs (`input.items.price`) applies operations element-wise with map/reduce detection.
 
 **Basic Broadcasting**:
 ```ruby
@@ -286,7 +270,7 @@ 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:
+**Aggregation Operations**: Functions consuming arrays are detected:
 ```ruby
 value :total_subtotal, fn(:sum, subtotals)
 value :avg_price, fn(:avg, input.line_items.price)
@@ -297,7 +281,7 @@ value :max_quantity, fn(:max, input.line_items.quantity)
 - **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
+- **Type Inference** infers types for array element operations
 - Supports arbitrary depth field access with nested arrays and hashes
 
 ### Trait Syntax Evolution
@@ -330,7 +314,7 @@ trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation war
 ```
 
 **Key Changes**:
-- **NEW**: Bare identifier syntax allows direct trait reference: `adult` instead of `ref(:adult)`
+- **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 `&&`)
@@ -350,9 +334,9 @@ trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation war
 
 - **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 to ensure correct order
-- **Type Safety**: Optional but comprehensive type checking without breaking existing schemas
-- **Ruby Integration**: Leverages Ruby's metaprogramming while providing structured analysis
+- **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
@@ -370,7 +354,7 @@ class MyParser
   include ErrorReporting
   
   def parse_something
-    # Immediate error raising
+    # Error raising
     raise_syntax_error("Invalid syntax", location: current_location)
   end
 end
@@ -389,7 +373,7 @@ class MyAnalyzerPass < PassBase
 end
 ```
 ### Testing Error Scenarios
-- Use `spec/integration/dsl_breakage_spec.rb` patterns for comprehensive error testing
+- 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

@@ -5,7 +5,7 @@
 
 Kumi is a Declarative logic and rules engine 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.
+It handles complex, interdependent calculations with validation and consistency checking.
 
 
 ## What can you build?
@@ -59,9 +59,9 @@ result[:total_tax]   # => 21,491.00
 result[:after_tax]   # => 78,509.00
 ```
 
-Real tax calculation with brackets, deductions, and FICA caps. Validation happens during schema definition.
+Real tax calculation with brackets, deductions, and FICA caps. 
 
-Kumi is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
+Validation happens during schema definition.
 
 ## Installation
 
@@ -74,7 +74,7 @@ gem install kumi
 ## Core Features
 
 <details>
-<summary><strong>📊 Schema Primitives</strong> - Four building blocks for business logic</summary>
+<summary><strong>Schema Primitives</strong> - Four building blocks for business logic</summary>
 
 ### Schema Primitives
 
@@ -96,7 +96,7 @@ value :tax_rate, 0.08
 value :tax_amount, subtotal * tax_rate
 ```
 
-**Traits** are boolean conditions that enable branching logic:
+**Traits** are boolean conditions for branching logic:
 ```ruby
 trait :bulk_order, input.quantity >= 100
 trait :premium_customer, input.tier == "premium"
@@ -109,7 +109,7 @@ value :discount do
 end
 ```
 
-**Functions** provide computational building blocks:
+**Functions** are computational building blocks:
 
 ```ruby
 value :final_price, [subtotal - discount_amount, 0].max
@@ -120,9 +120,13 @@ Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIO
 </details>
 
 <details>
-<summary><strong>🔍 Static Analysis</strong> - Catch errors at definition time and provides rich metadata</summary>
+<summary><strong>Analysis & Introspection</strong> - Static verification, runtime inspection, and metadata extraction</summary>
 
-### Static Analysis
+### Analysis & Introspection
+
+Kumi provides comprehensive analysis capabilities - catching errors at definition time and exposing schema structure for tooling and debugging.
+
+#### **Static Analysis: Catch Errors Early**
 
 Kumi catches many types of business logic errors that cause runtime failures or silent bugs:
 
@@ -203,7 +207,7 @@ end
 # ❌ Function arity error: divide expects 2 arguments, got 1
 ```
 
-**Bounded Recursion**: Kumi allows mutual recursion when cascade conditions are mutually exclusive:
+**Mutual Recursion**: Kumi supports mutual recursion when cascade conditions are mutually exclusive:
 
 ```ruby
 trait :is_forward, input.operation == "forward"
@@ -212,7 +216,7 @@ 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)
+  on is_reverse, reveAnalysisrse_processor + 10  # Delegates to reverse (safe)
   base "invalid operation"
 end
 
@@ -230,168 +234,225 @@ end
 
 This compiles because `operation` can only be "forward" or "reverse", never both. Each recursion executes one step before hitting a direct calculation.
 
-</details>
+#### **Runtime Introspection: Debug and Understand**
 
-<details>
-<summary><strong>🔍 Array Broadcasting</strong> - Automatic vectorization over array fields</summary>
-
-### Array Broadcasting
-
-Kumi broadcasts operations over array fields for element-wise computation:
+**Explainability**: Trace exactly how any value is computed, step-by-step. This is invaluable for debugging complex logic and auditing results.
 
 ```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
+Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
+# => fed_tax = fed_calc[0]
+#    = (fed_calc = piecewise_sum(taxable_income, fed_breaks, fed_rates)
+#       = piecewise_sum(85_400, [11_600, 47_150, ...], [0.10, 0.12, ...])
+#       = [15_099.50, 0.22])
+#    = 15_099.50
 ```
 
-**Dimension Mismatch Detection**: Operations across different arrays generate error messages:
+#### **Schema Metadata API: Build Tooling**
 
-```ruby
-schema do
-  input do
-    array :items do
-      string :name
-    end
-    array :logs do  
-      string :user_name
-    end
-  end
+Programmatically access the analyzed structure of your schema to build tools like form generators, documentation sites, or custom validators.
 
-  # This generates an error
-  trait :same_name, input.items.name == input.logs.user_name
-end
+```ruby
+metadata = FederalTax2024.schema_metadata
 
-# 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.
-```
+# Processed, tool-friendly metadata
+metadata.inputs           # => { name: { type: :string, domain: ... } }
+metadata.values           # => { name: { dependencies: [...], expression: "..." } }
+metadata.traits           # => { name: { condition: "...", dependencies: [...] } }
 
-</details>
+# Raw analyzer state for deep analysis
+metadata.dependencies     # Dependency graph between all declarations
+metadata.evaluation_order # Topologically sorted computation order
 
-<details>
-<summary><strong>💾 Automatic Memoization</strong> - Each value computed exactly once</summary>
+# Export to standard formats
+metadata.to_h             # => Serializable hash for JSON/APIs
+metadata.to_json_schema   # => JSON Schema for input validation
+```
 
-### Automatic Memoization
+#### **AST Visualization: See the Structure**
 
-Each value is computed exactly once:
+For deep debugging, you can print the raw Abstract Syntax Tree (AST) of a schema.
 
 ```ruby
-runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
-
-# First access computes full dependency chain
-runner[:total_tax]     # => 53,155.20
-
-# Subsequent access uses cached values
-runner[:fed_tax]       # => 39,077.00 (cached)
-runner[:after_tax]     # => 196,844.80 (cached)
+puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
+# => (Root
+#      inputs: [
+#        (InputDeclaration :income :float)
+#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
+#      ]
+#      traits: [...]
+#      attributes: [...])
 ```
 
 </details>
 
 <details>
-<summary><strong>🔍 Introspection</strong> - See exactly how values are calculated</summary>
+<summary><strong>Hierarchical Broadcasting</strong> - Vectorization over nested data structures</summary>
+
+### Hierarchical Broadcasting
+
+Kumi broadcasts operations over hierarchical data structures with two complementary access modes for maximum flexibility.
 
-### Introspection
+See [docs/features/hierarchical-broadcasting.md](docs/features/hierarchical-broadcasting.md) for detailed documentation.
 
-Show how values are calculated:
+**Business Scenario**: E-commerce checkout with dynamic pricing rules
 
+> **"As an e-commerce platform, I need to calculate order totals with complex discount rules:**
+> - Premium members get 15% off electronics
+> - Bulk orders (5+ items) get 10% off that item
+> - Free shipping on orders over $100
+> - Calculate: item subtotals, total discounts, shipping, final total
+> 
+> **The challenge:** Each order has different items, quantities, categories, and customer tiers. The discount logic involves multiple conditions - some items qualify for multiple discounts, others for none. Traditional pricing code requires nested if-statements and manual calculations."
+
+**Kumi Solution** (16 lines of declarative pricing logic):
 ```ruby
-Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
-# => fed_tax = fed_calc[0]
-#    = (fed_calc = piecewise_sum(taxable_income, fed_breaks, fed_rates)
-#       = piecewise_sum(85,400, [11,600, 47,150, ...], [0.10, 0.12, ...])
-#       = [15,099.50, 0.22])
-#    = 15,099.50
+module OrderPricing
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      array :items do
+        float   :price
+        integer :quantity
+        string  :category
+      end
+      string :customer_tier
+      float  :shipping_threshold
+    end
+    
+    # Calculate item subtotals and discount eligibility
+    value :subtotals, input.items.price * input.items.quantity
+    trait :electronics, input.items.category == "electronics"
+    trait :bulk_item, input.items.quantity >= 5
+    trait :premium_customer, input.customer_tier == "premium"
+    
+    # Apply layered discounts (premium + bulk can stack)
+    trait :premium_electronics, premium_customer & electronics
+    trait :stacked_discount, premium_electronics & bulk_item
+    
+    value :discounted_prices do
+      on stacked_discount, input.items.price * 0.75      # 15% + 10% = 25% off
+      on premium_electronics, input.items.price * 0.85   # 15% off
+      on bulk_item, input.items.price * 0.90             # 10% off
+      base input.items.price                              # No discount
+    end
+    
+    value :final_subtotals, discounted_prices * input.items.quantity
+    
+    # Order totals and conditional shipping
+    value :subtotal, fn(:sum, final_subtotals)
+    value :total_savings, fn(:sum, subtotals) - subtotal
+    value :shipping, subtotal > input.shipping_threshold ? 0.0 : 9.99
+    value :total, subtotal + shipping
+  end
+end
 ```
 
-**Debug AST Structure**: Visualize the parsed schema as S-expressions:
+**Mixed Access Modes**: Both object and element access can be used together in the same schema:
 
 ```ruby
-puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
-# => (Root
-#      inputs: [
-#        (InputDeclaration :income :float)
-#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
-#      ]
-#      traits: [...]
-#      attributes: [...])
+module UserAnalytics
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      # Object access mode - structured business data
+      array :users do
+        string :name
+        integer :age
+      end
+      
+      # Element access mode - multi-dimensional raw arrays
+      array :recent_purchases do
+        element :integer, :days_ago
+      end
+    end
+
+    # Object access works normally
+    value :user_names, input.users.name
+    value :avg_age, fn(:avg, input.users.age)
+    
+    # Element access handles nested arrays with progressive path traversal
+    value :all_purchase_days, fn(:flatten, input.recent_purchases.days_ago)
+    value :recent_flags, input.recent_purchases.days_ago < 5
+    trait :has_recent_purchase, fn(:any?, fn(:flatten, recent_flags))
+    
+    # Progressive dimensional analysis - each path level goes deeper
+    value :purchase_dimensions, [
+      fn(:size, input.recent_purchases),           # Number of purchase groups
+      fn(:size, input.recent_purchases.days_ago)  # Total individual purchase days
+    ]
+    
+    # Mixed usage in conditions
+    trait :adult_users, input.users.age >= 18
+    value :adult_count, fn(:count_if, adult_users)
+  end
+end
+
+# Works with mixed data structures
+result = UserAnalytics.from({
+  users: [{ name: "Alice", age: 25 }, { name: "Bob", age: 17 }],
+  recent_purchases: [[1, 3, 7], [2, 4], [10, 15]]  # Nested arrays
+})
+
+result[:user_names]          # => ["Alice", "Bob"]
+result[:has_recent_purchase] # => true (some purchases < 5 days ago)
+result[:adult_count]         # => 1
+result[:purchase_dimensions] # => [3, 8] (3 groups, 8 total days)
 ```
 
 </details>
 
 <details>
-<summary><strong>📋 Schema Metadata</strong> - Extract structured information for tooling</summary>
+<summary><strong>Memoization</strong> - Each value computed exactly once</summary>
 
-### Schema Metadata
+### Memoization
 
-Access structured metadata for building tools like form generators and dependency analyzers:
+Each value is computed exactly once:
 
 ```ruby
-metadata = FederalTax2024.schema_metadata
-
-# Processed metadata (tool-friendly)
-metadata.inputs           # Input field types and domains  
-metadata.values           # Value declarations with dependencies
-metadata.traits           # Trait conditions and metadata
-metadata.functions        # Function registry information
+runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
 
-# Raw analyzer state (advanced usage)
-metadata.dependencies     # Dependency graph between declarations
-metadata.evaluation_order # Topologically sorted computation order
-metadata.inferred_types   # Type inference results
-metadata.declarations     # Raw AST declaration nodes
+# First access computes full dependency chain
+runner[:total_tax]     # => 53,155.20
 
-# Export formats
-metadata.to_h             # Serializable hash for JSON/APIs
-metadata.to_json_schema   # JSON Schema for input validation
+# Subsequent access uses cached values
+runner[:fed_tax]       # => 39,077.00 (cached)
+runner[:after_tax]     # => 196,844.80 (cached)
 ```
-
-The SchemaMetadata interface provides both processed metadata for tool development and raw analyzer state for advanced use cases. Complete documentation available in the SchemaMetadata class and [docs/schema_metadata.md](docs/schema_metadata.md).
-
 </details>
 
-## Beyond Rules: What the Metadata Unlocks
-* **Auto-generated forms** – compile schema → field spec → React form
-* **Scenario explorer** – derive all trait combinations, Monte Carlo outcomes
-* **Coverage dashboard** – flag branches never hit in prod
-* **Schema diff** – highlight behaviour changes across versions
-
 ## Usage
 
 **Suitable for:**
 - Complex interdependent business rules
 - Tax calculation engines
 - Insurance premium calculators
-- Loan amortization schedules
 - Commission structures with complex tiers
 - Pricing engines with multiple discount rules
 
 **Not suitable for:**
-- Simple conditional statements
+- Basic conditional statements
 - Sequential procedural workflows  
-- Rules that change during execution
-- High-frequency real-time processing
+- High-frequency processing
+
+## JavaScript Transpiler
+
+Transpiles compiled schemas to standalone JavaScript code. See [docs/features/javascript-transpiler.md](docs/features/javascript-transpiler.md) for details.
+
+```ruby
+Kumi::Js.export_to_file(FederalTax2024, "federal-tax-2024.js")
+```
+
+```javascript
+const { schema } = require('./federal-tax-2024.js');
+const calculator = schema.from({ income: 100_000, filing_status: "single" });
+console.log(calculator.fetch('total_tax'));   // 21491
+```
+
+Generated JavaScript includes only functions used by the schema.
+
+All tests run in dual mode to verify compiled schemas produce identical results in both Ruby and JavaScript.
 
 ## Performance
 
@@ -400,6 +461,12 @@ Benchmarks on Linux with Ruby 3.3.8 on a Dell Latitude 7450:
 - 1,000 attributes:         **131,000/sec** (analysis <50ms)
 - 10,000 attributes:        **14,200/sec**  (analysis ~300ms)
 
+See [docs/features/performance.md](docs/features/performance.md) for detailed benchmarks.
+
+## 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.
+
 ## Learn More
 
 - [DSL Syntax Reference](docs/SYNTAX.md)

data/docs/AST.md

@@ -77,7 +77,7 @@ CaseExpression = Struct.new(:condition, :result)
 ```
 
 **Case type mappings**:
-- `on :a, :b, result` → `condition: fn(:all?, ref(:a), ref(:b))`  
+- `on :a, :b, result` → `condition: fn(:cascade_and, ref(:a), ref(:b))`  
 - `on_any :a, :b, result` → `condition: fn(:any?, ref(:a), ref(:b))`
 - `base result` → `condition: literal(true)`