kumi 0.0.10 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98308b4c27cb40488f14215c8da9700c62a51fc54d11b9d822a1eb25d396a724
-  data.tar.gz: 3fbbb50dc0c74ba14d83fbcf71c5866efa814b71b4d2679c45b57d59a1f778da
+  metadata.gz: 3eb46e14716bf14c3d9165ffac957211f41ad5a21a74ad37c47b37c37e01b312
+  data.tar.gz: fd0e36d65ac41079c27cf9699a3e092ff762bc76b3af8fc90df2ec763fed3806
 SHA512:
-  metadata.gz: 4453ea76de50c433696c3ae5ebe4d39ae049cb35e40f34cf9a3cce0e52e5d0967a8ccfd9ca7627eafe33444ea4da186015a59796a59e022fdf5b5edc04c50444
-  data.tar.gz: dfdb9f118ee7c0c16fa30392b3591b88c8320a2d19ff331253a4344e49fa773967e6b8d2451c0fd490f200171846fec2b408ecd000e6ad111e3c2d89bd92c000
+  metadata.gz: 54ed5e72d6acf863e0f7ed0986c8db83fab22526bcffb97b4c1b96343e724b0ae505804baed5554933c452478ced8c46ec24a6568426813e69c4007994588de6
+  data.tar.gz: '09aabb772643aab71d957060c934f05be5838a1056b7c635822b75759106a3119844cc7e20f96b8990ec658d969f2d2e0143ceb43d36f8d48da061c2bb80cb6a'

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## [0.0.11] – 2025-08-13
+### Added
+- Intermediate Representation (IR) and slot-based VM interpreter.
+- Scope-aware vector semantics (alignment, lift, hierarchical indices).
+- Debug tooling: IR dump, VM/lowering traces via DEBUG_* flags.
+
+### Changed
+- Analyzer now lowers to IR via `LowerToIRPass`.
+- Access modes: `:read`, `:ravel`, `:each_indexed`, `:materialize`.
+
+### Removed (BREAKING)
+- JavaScript transpiler (legacy compiler).
+
+### Requirements
+- Ruby >= 3.1 (Was >= 3.0)
+
+### Notes
+- No expected DSL changes for typical schemas; report regressions.

data/CLAUDE.md

@@ -18,11 +18,6 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 - `bundle exec rspec spec/path/to/specific_spec.rb` - Run specific test file
 - `bundle exec rspec spec/path/to/specific_spec.rb:123` - Run specific test at line
 
-### Gem Management
-- `bundle install` - Install dependencies
-- `gem build kumi.gemspec` - Build the gem
-- `gem install ./kumi-*.gem` - Install locally built gem
-
 ## Architecture Overview
 
 ### Core Components
@@ -72,50 +67,8 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 - 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
 
-**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
-- `input/violation_creator.rb` - Creates standardized violation objects with detailed messages
-- `domain/validator.rb` - Domain constraint validation (ranges, arrays, procs)
-- `domain/range_analyzer.rb` - Range domain analysis and validation
-- `domain/enum_analyzer.rb` - Enumeration domain analysis and validation
-- `domain/violation_formatter.rb` - Formats domain violation error messages
-
-## DSL Syntax Requirements
-
-### Critical Syntax Rules
-
-**Module Definition Structure** 
-```ruby
-# CORRECT - CLI can find and load this
-module SchemaName
-  extend Kumi::Schema
-  
-  schema do
-    # schema definition here
-  end
-end
-```
-
-**Function Call Syntax**:
-- **Symbol style**: `fn(:function_name, arg1, arg2, ...)` - The only supported function call syntax 
-
-**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**: Sugar syntax for basic operations, function syntax for complex ones
-
-**Cascade Condition Syntax**:
-```ruby
-value :status do
-  on trait_name, "Result"
-  base "Default"
-end
-```
-
 ### Key Patterns
 **DSL Structure**:
 ```ruby
@@ -133,17 +86,15 @@ schema do
       string  :category
     end
 
-
-
     # Fields with no declared type
     any     :misc_field
   end
 
-  trait :name, (expression)  # Boolean conditions with new syntax
+  trait :name, (expression)  # Boolean conditions
   value :name, expression    # Computed values
   value :name do             # Conditional logic
-    on condition, result
-    base default_result
+    on condition, result     # on <trait> ?,<trait> , <expr>
+    base default_result      # base <expr>
   end
 end
 ```
@@ -151,13 +102,6 @@ end
 **IMPORTANT CASCADE CONDITION SYNTAX:**
 In cascade expressions (`value :name do ... end`), trait references use bare identifiers:
 
-**Input Block System**:
-- **Required**: All schemas must have an `input` block declaring expected fields
-- **Type Declarations**: Preferred via type-specific methods (e.g. `integer :field`, `string :name`, `any :field` for untyped fields)
-- **Complex Types**: Use helper functions: `array(:element_type)` and `hash(:key_type, :value_type)`
-- **Domain Constraints**: Fields can have domains: `integer :age, domain: 18..65` (validated at runtime)
-- **Field Access**: Use `input.field_name` to reference input fields in expressions
-- **Separation**: Input metadata (types, domains) is separate from business logic
 
 **Expression Types**:
 - `input.field_name` - Access input data with operator methods (>=, <=, >, <, ==, !=)
@@ -179,30 +123,6 @@ In cascade expressions (`value :name do ... end`), trait references use bare ide
 - 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
-- Enhanced error messages showing type provenance (declared vs inferred)
-- Legacy compatibility constants maintained for backward compatibility
-
-### Examples Directory
-
-The `examples/` directory contains examples showing Kumi usage patterns:
-- `cascade_demonstration.rb` - Demonstrates cascade logic with UnsatDetector fixes (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` - 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)
-
-*Note: Some examples may use deprecated syntax and should be updated to use the new input block system.*
-
-## Test Structure
-
-- `spec/kumi/` - Unit tests for core components
-- `spec/integration/` - Integration tests for full workflows
-- `spec/fixtures/` - Test fixtures and sample schemas
-- `spec/support/` - Test helpers (`ast_factory.rb`, `schema_generator.rb`)
 
 ## Files for Understanding
 
@@ -210,46 +130,8 @@ The `examples/` directory contains examples showing Kumi usage patterns:
 - `examples/*` Random examples of diverse contexts.
 
 ### Troubleshooting Schema Issues
-- **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
-- **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!
+DEBUG, DEBUG. DEBUG LOGS!
 
-## Input Block System Details
-
-### 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 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.
-
-### Type System Integration
-- **Declared Types**: Explicit type declarations in input blocks (e.g. `integer :field`, `string :name`, `any :field`)
-- **Inferred Types**: Types automatically inferred from expression analysis
-- **Type Checking**: Validates compatibility between declared and inferred types
-- **Enhanced Errors**: Error messages show type provenance (declared vs inferred)
-- **Helper Functions**: Use `array(:type)` and `hash(:key_type, :value_type)` for complex types
-
-### Parser Components
-See `lib/kumi/ruby_parser/parser.rb`
-
-### Domain Constraints
-- Can be declared: `integer :age, domain: 18..65`
-- Supports Range domains (`18..65`), Array domains (`%w[active inactive]`), and Proc domains for custom validation
-- Analyzer do some limited domain UNSAT detection, and its used to validated against input at Runtime
-### Type Examples
-```ruby
-input do
-  string       :name
-  integer      :age, domain: 18..65
-  hash         :metadata, key: { type: :string }, val: { type: :any }
-
-  #generic type
-  any          :misc # this reduces Kumi's analyze/inference capabilities
-end
-```
 
 ### Array Broadcasting System
 
@@ -262,6 +144,9 @@ input do
     float   :price
     integer :quantity  
     string  :category
+    array   :prices do
+      element :integer, :val
+    end
   end
 end
 
@@ -269,112 +154,3 @@ end
 value :subtotals, input.line_items.price * input.line_items.quantity
 trait :is_taxable, (input.line_items.category != "digital")
 ```
-
-**Aggregation Operations**: Functions consuming arrays are 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** infers types for array element operations
-- Supports arbitrary depth field access with nested arrays and hashes
-
-### Trait Syntax Evolution
-
-**Current Syntax** (recommended):
-```ruby
-trait :adult, (input.age >= 18)
-trait :qualified, (input.age >= 21) & (input.score > 80) & (input.verified == true)
-```
-
-**Composite Trait Syntax** (NEW - bare identifier references):
-```ruby
-# Base traits
-trait :adult, (input.age >= 18)
-trait :verified, (input.verified == true)
-trait :high_score, (input.score > 80)
-
-# Composite traits using bare identifier syntax
-trait :eligible, adult & verified & high_score
-trait :mixed, adult & (input.income > 50_000) & verified
-
-# Backward compatibility - both syntaxes work together
-trait :legacy_mix, adult & ref(:verified) & (input.score > 90)
-```
-
-**Deprecated Syntax** (with warnings):
-```ruby
-trait :adult, input.age, :>=, 18                    # OLD - shows deprecation warning
-trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation warning
-```
-
-**Key Changes**:
-- **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 `&&`)
-- Only AND operations supported to maintain constraint satisfaction system
-- **Backward Compatible**: Both `trait_name` and `ref(:trait_name)` work together
-- Old syntax maintained with deprecation warnings for backward compatibility
-
-## Common Development Tasks
-
-### Adding New Analyzer Passes
-1. Create pass class inheriting from `PassBase` in `lib/kumi/analyzer/passes/`
-2. Implement `run(errors)` method that calls `set_state(key, value)` to store results
-3. Add pass to `PASSES` array in `lib/kumi/analyzer.rb` in correct order
-4. Consider dependencies on other passes (e.g., TypeChecker needs TypeInferencer)
-
-## Architecture Design Principles
-
-- **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 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
-
-### Testing Best Practices
-- **Spec Organization**: Tests organized by component with clear separation between unit and integration tests
-- **Error Variable Extraction**: RSpec patterns avoid multiline block chains by extracting error variables for assertion
-
-## Development Guides and Standards
-
-### Error Reporting Standards
-**For Parser Classes**:
-```ruby
-class MyParser
-  include ErrorReporting
-  
-  def parse_something
-    # Error raising
-    raise_syntax_error("Invalid syntax", location: current_location)
-  end
-end
-```
-
-**For Analyzer Passes**:
-```ruby
-class MyAnalyzerPass < PassBase
-  def run(errors)
-    # Error accumulation with enhanced location
-    report_error(errors, "semantic error", location: node.loc, type: :semantic)
-    
-    # Backward compatible method
-    add_error(errors, node.loc, "legacy format error")
-  end
-end
-```
-### Testing Error Scenarios
-- 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

@@ -66,7 +66,7 @@ Validation happens during schema definition.
 ## Installation
 
 ```bash
-# Requires Ruby 3.0+
+# Requires Ruby 3.1+
 # No external dependencies
 gem install kumi
 ```

data/docs/VECTOR_SEMANTICS.md

@@ -0,0 +1,286 @@
+# Kumi Vector Semantics — Short Guide
+
+This note documents how Kumi handles **vectorized traversal** over **arbitrary nested objects**, how **alignment/broadcasting** works, and how **reducers** and **structure functions** behave. It’s intentionally concise but hits all the sharp edges.
+
+---
+
+## Terminology
+
+* **Path** – a dot-separated traversal, e.g. `input.regions.offices.employees.salary`.
+* **Scope (axes)** – the list of array segments encountered along a path.
+  Example: for `regions.offices.employees.salary` the scope is `[:regions, :offices, :employees]`.
+* **Rank** – number of axes = `scope.length`.
+* **Index tuple** – lexicographic coordinates per axis, e.g. `[region_i, office_j, employee_k]`.
+
+**Three Laws (think of them as invariants):**
+
+1. **Enumeration**
+   `each_indexed(path).map(&:first) == ravel(path)`
+
+2. **Reconstruction**
+   `lift(to_scope, each_indexed(path))` regroups by `to_scope` (must be a prefix of `scope(path)`).
+
+3. **Counting**
+   `size(path) == ravel(path).length == each_indexed(path).count`
+
+These laws are the mental model. Everything else is just mechanics.
+
+---
+
+## Access Modes
+
+Kumi’s Access Planner emits low-level ops (`enter_hash`, `enter_array`) and supports three vector modes per path:
+
+### 1) `:materialize`
+
+Return the **original nested structure** down to that path (no enumeration).
+Good for “give me the data shaped like the input.”
+
+```ruby
+# Input (object mode)
+{
+  regions: [
+    { name: "E", offices: [{ employees: [{salary: 100}, {salary: 120}] }] },
+    { name: "D", offices: [{ employees: [{salary: 90}] }] }
+  ]
+}
+
+materialize("regions.offices.employees.salary")
+# => [[ [100,120] ], [ [90] ]]
+```
+
+### 2) `:ravel`
+
+**Enumerate elements at the next array boundary** for that path, i.e., “collect the items at this depth.”
+It is **not** NumPy’s “flatten everything.” It collects the next level.
+
+```ruby
+ravel("regions")                          # => [ {…E…}, {…D…} ]          (enumerate regions)
+ravel("regions.offices")                  # => [ {employees:[…]}, {employees:[…]} ] (each office)
+ravel("regions.offices.employees.salary") # => [ [100,120], [90] ]       (each employee group at that depth)
+```
+
+### 3) `:each_indexed`
+
+Enumerate leaf values **with** their index tuple (authoritative for `lift` and alignment):
+
+```ruby
+each_indexed("regions.offices.employees.salary")
+# => [
+#   [100, [0,0,0]], [120, [0,0,1]],
+#   [ 90, [1,0,0]]
+# ]
+```
+
+---
+
+## Lift (Regroup by prefix)
+
+`lift(to_scope)` turns a vector-of-rows (from `each_indexed`) into a nested array grouped by `to_scope`.
+
+```ruby
+# Given values from each_indexed above:
+lift([:regions],   …) # => [ [100,120], [90] ]
+lift([:regions,:offices], …) # => [ [[100,120]], [[90]] ]
+lift([:regions,:offices,:employees], …) # => [ [[[100,120]]], [[[90]]] ]
+```
+
+* `to_scope` must be a **prefix** of the vector’s `scope`.
+* Depth is derived mechanically from index arity; VM doesn’t guess.
+
+---
+
+## Alignment & Broadcasting
+
+When mapping a function over multiple arguments, Kumi:
+
+1. Picks a **carrier** vector (the one with the longest scope).
+2. **Aligns** other vectors to the carrier if they are **prefix-compatible** (same axes prefix).
+3. **Broadcasts** scalars across the carrier.
+
+If scopes aren’t prefix-compatible, lowering raises:
+`cross-scope map without join: [:a] vs [:b,:c]`
+
+```ruby
+# price, quantity both scope [:items]
+final = price * quantity             # zip by position (same scope)
+
+# Broadcast scalar across [:items]
+discounted = price * 0.9
+
+# Align prefix [:regions] to carrier [:regions,:offices]
+aligned_tax = align_to(offices_subtotals, regions_tax)
+total = offices_subtotals * (1 - aligned_tax)
+```
+
+---
+
+## Structure Functions vs Reducers
+
+* **Reducers** collapse a vector to a **scalar** (e.g., `sum`, `min`, `avg`).
+  Lowering selects a vector argument and emits a `Reduce`.
+
+* **Structure functions** observe or reshape **structure** (e.g., `size`, `flatten`, `count_across`).
+  Lowering usually uses a `:ravel` plan and a plain `Map` (no indices required).
+
+### Laws for `size` and `flatten`
+
+* `size(path) == ravel(path).length` (Counting Law)
+* `flatten(path)` flattens nested arrays (by default all levels; use `flatten_one` for one level).
+
+---
+
+## End-to-End Mini Examples
+
+### A. Simple vector math + reducers (object access)
+
+```ruby
+module Cart
+  extend Kumi::Schema
+  schema do
+    input do
+      array :items do
+        float :price
+        integer :qty
+      end
+      float :shipping_threshold
+    end
+
+    value :subtotals, input.items.price * input.items.qty
+    value :subtotal,  fn(:sum, subtotals)
+    value :shipping,  subtotal > input.shipping_threshold ? 0.0 : 9.99
+    value :total,     subtotal + shipping
+  end
+end
+
+data = {
+  items: [{price: 100.0, qty: 2}, {price: 200.0, qty: 1}],
+  shipping_threshold: 50.0
+}
+
+r = Cart.from(data)
+r[:subtotals] # => [200.0, 200.0]  (vector map)
+r[:subtotal]  # => 400.0           (reducer)
+r[:shipping]  # => 0.0
+r[:total]     # => 400.0
+```
+
+**Internal truths**:
+
+* `each_indexed(input.items.price)` → `[[100.0,[0]],[200.0,[1]]]`
+* `size(input.items)` → `2` because `ravel(input.items)` has length 2.
+
+### B. Mixed scopes + alignment
+
+```ruby
+module Regions
+  extend Kumi::Schema
+  schema do
+    input do
+      array :regions do
+        float :tax
+        array :offices do
+          array :employees do
+            float :salary
+          end
+        end
+      end
+    end
+
+    value :office_payrolls, fn(:sum, input.regions.offices.employees.salary)   # vector reduce per office
+    value :taxed, office_payrolls * (1 - input.regions.tax) # tax (align regions.tax to [:regions,:offices])
+  end
+end
+
+# Alignment rule: regions.tax (scope [:regions]) aligns to office_payrolls (scope [:regions,:offices])
+```
+
+### C. Element access (pure arrays) + structure functions
+
+```ruby
+module Cube
+  extend Kumi::Schema
+  schema do
+    input do
+      array :cube do
+        element :array, :layer do
+          element :array, :row do
+            element :float, :cell
+          end
+        end
+      end
+    end
+
+    value :layers,      fn(:size, input.cube)                 # == ravel(input.cube).length
+    value :matrices,    fn(:size, input.cube.layer)           # enumerate at next depth
+    value :rows,        fn(:size, input.cube.layer.row)
+    value :all_values,  fn(:flatten, input.cube.layer.row.cell)
+    value :total,       fn(:sum, all_values)
+  end
+end
+
+data = { cube: [ [[1,2],[3]], [[4]] ] }
+
+# ravel views (intuition)
+# ravel(cube)                => [ [[1,2],[3]], [[4]] ]
+# ravel(cube.layer)          => [ [1,2], [3], [4] ]
+# ravel(cube.layer.row)      => [ 1, 2, 3, 4 ]
+# ravel(cube.layer.row.cell) => [ 1, 2, 3, 4 ]  (same leaf)
+
+c = Cube.from(data)
+c[:layers]     # => 2
+c[:matrices]   # => 3
+c[:rows]       # => 4
+c[:all_values] # => [1,2,3,4]
+c[:total]      # => 10
+```
+
+---
+
+## Planner & VM: Who does what?
+
+* **Planner**: Emits deterministic `enter_hash`/`enter_array` sequences per path and mode.
+
+  * For element edges (inline array aliases), it **does not** emit `enter_hash`.
+  * For `:each_indexed` / `:ravel`, it appends a terminal `enter_array` **only if** the final node is an array.
+* **Lowerer**: Decides plans (`:ravel`, `:each_indexed`, `:materialize`), inserts `align_to`, emits `lift` at declaration boundary when a vector result should be exposed as a scalar nested array.
+* **VM**: Purely mechanical:
+
+  * `broadcast_scalar` for scalar→vec expansion,
+  * `zip_same_scope` when scopes match,
+  * `align_to` for prefix alignment,
+  * `group_rows` inside `lift` to reconstruct prefixes.
+
+No type sniffing or guesses: the IR is the source of truth.
+
+---
+
+## Jagged & Sparse Arrays
+
+* Ordering is **lexicographic by index tuple** (stable).
+* No padding is introduced; missing branches are just… missing.
+* `align_to(..., on_missing: :error|:nil)` enforces policy.
+
+---
+
+## Error Policies
+
+For missing keys/arrays, accessors obey policy:
+
+* `:error` (default) – raise descriptive error with the path/mode.
+* `:skip` – drop the missing branch (useful in ravels).
+* `:yield_nil` – emit `nil` in place (preserves cardinality).
+
+Document these on any user-facing accessor.
+
+---
+
+## Quick Cheatsheet
+
+* Use **`ravel(path)`** to “list the things at this level.”
+* Use **`each_indexed(path)`** when you need `(value, idx)` pairs for joins/regroup.
+* Use **`lift(to_scope, each_indexed(path))`** to reconstruct nested structure.
+* **Reducers** (e.g., `sum`, `avg`, `min`) consume the raveled view of their argument.
+* **Structure functions** (e.g., `size`, `flatten`, `flatten_one`, `count_across`) operate on structure at that depth and usually compile via `:ravel`.
+
+Keep the three laws in mind and Kumi’s behavior is predictable—even over deeply nested, heterogeneous data.

data/docs/features/hierarchical-broadcasting.md

@@ -193,7 +193,7 @@ The type system automatically infers appropriate types for broadcasted operation
 
 ### Analysis Layer  
 - **BroadcastDetector** - Identifies vectorized vs scalar operations
-- **TypeInferencer** - Infers types for array element access patterns
+- **TypeInferencerPass** - Infers types for array element access patterns
 
 ### Compilation Layer
 - **Automatic Dispatch** - Maps element-wise operations to array map functions

data/docs/features/s-expression-printer.md

@@ -42,7 +42,7 @@ The printer produces indented S-expressions that clearly show the hierarchical s
     (InputDeclaration :age :integer)
     (InputDeclaration :name :string)
   ]
-  attributes: [
+  values: [
     (ValueDeclaration :greeting
       (CallExpression :concat
         (Literal "Hello ")
@@ -65,7 +65,7 @@ The printer produces indented S-expressions that clearly show the hierarchical s
 
 The printer handles all Kumi AST node types:
 
-- **Root** - Schema container with inputs, attributes, and traits
+- **Root** - Schema container with inputs, values, and traits
 - **Declarations** - InputDeclaration, ValueDeclaration, TraitDeclaration
 - **Expressions** - CallExpression, ArrayExpression, CascadeExpression, CaseExpression
 - **References** - InputReference, InputElementReference, DeclarationReference

data/examples/deep_schema_compilation_and_evaluation_benchmark.rb

@@ -86,21 +86,27 @@ puts
 # ------------------------------------------------------------------
 Benchmark.ips do |x|
   schemas.each do |d, schema|
-    runner = schema.from(seed: 0)          # memoised runner
-    x.report("eval #{d}-deep") { runner[:final_result] }
+    # 1) HOT (memoized): expect ~flat, nanosecond-level if cached
+    hot = schema.from(seed: 0)
+    x.report("HOT fetch #{d}-deep") do
+      hot[:final_result]
+    end
+
+    # 2) COLD via UPDATE (no memoized result): change a dependent input each iter
+    upd = schema.from(seed: 0)
+    i = 0
+    x.report("COLD update #{d}-deep") do
+      i += 1
+      upd.update(seed: i)      # invalidates v0..vN; forces recompute
+      upd[:final_result]
+    end
+
+    # 3) COLD new runner (includes construction)
+    prng = Random.new(42)
+    x.report("COLD new #{d}-deep") do
+      r = schema.from(seed: prng.rand(1_000_000))
+      r[:final_result]
+    end
   end
   x.compare!
 end
-# Warming up --------------------------------------
-#         eval 50-deep   222.000 i/100ms
-#        eval 100-deep    57.000 i/100ms
-#        eval 150-deep    26.000 i/100ms
-# Calculating -------------------------------------
-#         eval 50-deep      2.166k (± 1.9%) i/s  (461.70 μs/i) -     10.878k in   5.024320s
-#        eval 100-deep    561.698 (± 1.4%) i/s    (1.78 ms/i) -      2.850k in   5.075057s
-#        eval 150-deep    253.732 (± 0.8%) i/s    (3.94 ms/i) -      1.274k in   5.021499s
-
-# Comparison:
-#         eval 50-deep:     2165.9 i/s
-#        eval 100-deep:      561.7 i/s - 3.86x  slower
-#        eval 150-deep:      253.7 i/s - 8.54x  slower