kumi 0.0.18 → 0.0.20

data/docs/SYNTAX.md

@@ -1,511 +1,764 @@
-# Kumi DSL Syntax Reference
+# Kumi Syntax — Quick Reference & Guide
 
-This document provides a comprehensive comparison of Kumi's DSL syntax showing both the sugar syntax (convenient, readable) and the underlying sugar-free syntax (explicit function calls).
+## Quick Reference
 
-## Table of Contents
+### File Structure
+```kumi
+schema do
+  input do
+    # Input shape declarations
+  end
+
+  # Declarations: let, value, trait
+end
+```
+
+### Types
+```kumi
+integer    # Integer numbers
+float      # Floating point numbers
+string     # Text strings
+array      # Sequential collections
+hash       # Structured objects
+```
+
+### Declarations
+```kumi
+let   :name, expr    # Intermediate value
+value :name, expr    # Output value
+trait :name, expr    # Boolean mask
+```
+
+### Operators
+
+**Arithmetic:** `+` `-` `*` `/` `**` `%`
+**Comparison:** `>` `>=` `<` `<=` `==` `!=`
+**Boolean:** `&` (AND) `|` (OR)
+**Indexing:** `tuple[0]` `tuple[1]` ...
+
+### Aggregation Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `fn(:sum, arr)` | Sum all elements | `fn(:sum, input.items.item.price)` |
+| `fn(:count, arr)` | Count elements | `fn(:count, input.items.item.price)` |
+| `fn(:max, arr)` | Maximum value | `fn(:max, input.items.item.price)` |
+| `fn(:min, arr)` | Minimum value | `fn(:min, input.items.item.price)` |
+| `fn(:mean, arr)` | Average (aliases: `avg`) | `fn(:mean, input.scores.score)` |
+| `fn(:sum_if, vals, cond)` | Sum where condition is true | `fn(:sum_if, input.items.item.price, expensive)` |
+| `fn(:count_if, vals, match)` | Count matching values | `fn(:count_if, input.cells.value, 0)` |
+| `fn(:mean_if, vals, cond)` | Average where true (aliases: `avg_if`) | `fn(:mean_if, input.scores.score, passing)` |
+| `fn(:any, arr)` | True if any element true | `fn(:any, input.flags.active)` |
+| `fn(:all, arr)` | True if all elements true | `fn(:all, input.checks.passed)` |
+| `fn(:join, arr)` | Join strings | `fn(:join, input.words.word)` |
+
+### Elementwise Functions
+
+**Arithmetic:**
+- `fn(:abs, x)` — Absolute value
+- `fn(:clamp, x, lo, hi)` — Clamp to range
+
+**String:**
+- `fn(:concat, s1, s2)` — Concatenate strings
+- `fn(:upcase, str)` — Convert to uppercase
+- `fn(:downcase, str)` — Convert to lowercase
+- `fn(:length, str)` — String length (aliases: `len`, `size`)
+
+**Array:**
+- `fn(:array_size, arr)` — Array length (alias: `size`)
+- `fn(:at, arr, idx)` — Get element at index (alias: `[]`)
+
+**Hash:**
+- `fn(:fetch, key)` — Fetch value from hash
+
+### Control Flow
+```kumi
+# Simple selection
+select(condition, if_true, if_false)
+
+# Multi-way cascade (first match wins)
+value :result do
+  on cond1, cond2, expr1    # If cond1 AND cond2
+  on cond3, expr2           # Else if cond3
+  base expr3                # Else (default)
+end
+```
+
+### Spatial Operations
+```kumi
+# Shift — access neighbors
+shift(expr, offset, axis_offset: 0, policy: :zero)
+  # offset: -N (left/up), +N (right/down)
+  # axis_offset: 0 (innermost/x), 1 (next/y)
+  # policy: :zero (default) | :wrap | :clamp
+
+# Roll — rotate with wrapping
+roll(expr, offset, policy: :wrap)
+  # policy: :wrap (default) | :clamp
+
+# Index access
+index(:name)  # Get index value (requires array declared with index: :name)
+```
+
+### Common Patterns
+
+**Filter and aggregate:**
+```kumi
+trait :expensive, input.items.item.price > 100.0
+value :expensive_total, fn(:sum_if, input.items.item.price, expensive)
+```
+
+**Map then reduce:**
+```kumi
+value :subtotals, input.items.item.price * input.items.item.quantity
+value :total, fn(:sum, subtotals)
+```
 
-- [Schema Structure](#schema-structure)
-- [Input Declarations](#input-declarations)
-- [Value Declarations](#value-declarations)
-- [Trait Declarations](#trait-declarations)
-- [Expressions](#expressions)
-- [Functions](#functions)
-- [Array Broadcasting](#array-broadcasting)
-- [Cascade Logic](#cascade-logic)
-- [References](#references)
+**Broadcasting (parent to child):**
+```kumi
+value :dept_total, fn(:sum, input.depts.dept.teams.team.headcount)
+trait :large_team, input.depts.dept.teams.team.headcount > dept_total / 3
+```
+
+**Index-based calculation:**
+```kumi
+let :W, fn(:array_size, input.x.y)
+value :row_major, (index(:i) * W) + index(:j)
+```
+
+---
+
+## Detailed Guide
+
+### 1) Input Shapes
+
+#### Scalars
+
+Scalar inputs represent single values:
+
+```kumi
+input do
+  integer :x
+  float :rate
+  string :name
+end
+```
 
-## Schema Structure
+**Example:**
+```kumi
+schema do
+  input do
+    integer :x
+    integer :y
+  end
+
+  value :sum, input.x + input.y
+  value :product, input.x * input.y
+end
+```
 
-### Basic Schema Template
+#### Arrays
 
-```ruby
-# With Sugar (Recommended)
-module MySchema
-  extend Kumi::Schema
+Arrays represent sequences. Navigate using dot notation through each level.
 
-  schema do
-    input do
-      # Input field declarations
+**1D Array:**
+```kumi
+input do
+  array :cells do
+    integer :value     # Access: input.cells.value
+  end
+end
+```
+
+**2D Array (grid):**
+```kumi
+input do
+  array :rows do
+    array :col do
+      integer :v       # Access: input.rows.col.v
     end
+  end
+end
+```
 
-    # Traits and values using sugar syntax
+**3D Array (cube):**
+```kumi
+input do
+  array :cube do
+    array :layer do
+      array :row do
+        integer :cell  # Access: input.cube.layer.row.cell
+      end
+    end
   end
 end
+```
+
+#### Arrays of Hashes
 
-# Sugar-Free (Explicit)
-module MySchema
-  extend Kumi::Schema
+Common pattern for structured collections:
 
-  schema do
-    input do
-      # Input field declarations (same)
+```kumi
+input do
+  array :items do
+    hash :item do
+      float :price
+      integer :quantity
+      string :category
     end
+  end
+end
+
+# Access: input.items.item.price
+#         input.items.item.quantity
+```
+
+#### Hashes
+
+Hashes represent structured data with named fields:
 
-    # Traits and values using explicit function calls
+```kumi
+input do
+  hash :config do
+    string :app_name
+    array :servers do
+      hash :server do
+        string :hostname
+        integer :port
+      end
+    end
   end
 end
+
+# Access scalar: input.config.app_name
+# Access nested: input.config.servers.server.hostname
 ```
 
-## Input Declarations
+#### Arrays with Named Indices
 
-Input declarations are the same in both syntaxes:
+Declare indices to access position values:
 
-```ruby
+```kumi
 input do
-  # Type-specific declarations
-  integer :age, domain: 18..65
-  string :status, domain: %w[active inactive suspended]
-  float :score, domain: 0.0..100.0
-  array :tags, elem: { type: :string }
-  hash :metadata, key: { type: :string }, val: { type: :any }
-  
-  # Untyped fields
-  any :misc_data
+  array :x, index: :i do
+    array :y, index: :j do
+      integer :_           # Placeholder (value unused)
+    end
+  end
 end
+
+# Use in expressions
+let :W, fn(:array_size, input.x.y)
+value :row_major, (index(:i) * W) + index(:j)
+value :col_major, (index(:j) * fn(:array_size, input.x)) + index(:i)
 ```
 
-## Value Declarations
+### 2) Declarations
 
-### Arithmetic Operations
+#### `let` — Intermediate Values
 
-```ruby
-# With Sugar
-value :total_score, input.math_score + input.verbal_score + input.writing_score
-value :average_score, total_score / 3
-value :scaled_score, average_score * 1.5
-value :final_score, scaled_score - input.penalty_points
+Use for computed values referenced elsewhere:
 
-# Sugar-Free
-value :total_score, fn(:add, fn(:add, input.math_score, input.verbal_score), input.writing_score)
-value :average_score, fn(:divide, total_score, 3)
-value :scaled_score, fn(:multiply, average_score, 1.5)
-value :final_score, fn(:subtract, scaled_score, input.penalty_points)
+```kumi
+let :x_sq, input.x * input.x
+let :y_sq, input.y * input.y
+let :distance_sq, x_sq + y_sq
+value :distance, distance_sq ** 0.5
 ```
 
-### Mathematical Functions
+#### `value` — Outputs
 
-```ruby
-# With Sugar (Note: Some functions require sugar-free syntax)
-value :score_variance, fn(:power, fn(:subtract, input.score, average_score), 2)
-value :max_possible, fn(:max, [input.math_score, input.verbal_score, input.writing_score])
-value :min_score, fn(:min, [input.math_score, input.verbal_score])
+Results serialized to output:
 
-# Sugar-Free
-value :score_variance, fn(:power, fn(:subtract, input.score, average_score), 2)
-value :max_possible, fn(:max, [input.math_score, input.verbal_score, input.writing_score])
-value :min_score, fn(:min, [input.math_score, input.verbal_score])
+```kumi
+value :cart_total, fn(:sum, input.items.item.price * input.items.item.quantity)
+value :item_count, fn(:count, input.items.item.quantity)
 ```
 
-## Trait Declarations
+#### `trait` — Boolean Masks
 
-### Comparison Operations
+Boolean conditions for filtering/branching:
 
-```ruby
-# With Sugar
-trait :high_scorer, input.total_score >= 1400
-trait :perfect_math, input.math_score == 800
-trait :needs_improvement, input.total_score < 1000
-trait :above_average, input.average_score > 500
+```kumi
+trait :expensive_items, input.items.item.price > 100.0
+trait :electronics, input.items.item.category == "electronics"
+trait :high_value, expensive_items & electronics
 
-# Sugar-Free
-trait :high_scorer, fn(:>=, input.total_score, 1400)
-trait :perfect_math, fn(:==, input.math_score, 800)
-trait :needs_improvement, fn(:<, input.total_score, 1000)
-trait :above_average, fn(:>, input.average_score, 500)
+value :discounted, select(high_value,
+  input.items.item.price * 0.8,
+  input.items.item.price
+)
 ```
 
-### Logical Operations
+### 3) Operators
 
-```ruby
-# With Sugar
-trait :excellent_student, high_scorer & perfect_math
-trait :qualified, (input.age >= 18) & (input.score >= 1200) & (input.status == "active")
-trait :needs_review, needs_improvement & (input.attempts > 2)
+**Arithmetic:**
+```kumi
++   -   *   /   **   %
 
-# Sugar-Free
-trait :excellent_student, fn(:and, high_scorer, perfect_math)
-trait :qualified, fn(:and, fn(:and, fn(:>=, input.age, 18), fn(:>=, input.score, 1200)), fn(:==, input.status, "active"))
-trait :needs_review, fn(:and, needs_improvement, fn(:>, input.attempts, 2))
+value :total, input.x + input.y
+value :area, input.width * input.height
+value :power, input.base ** input.exponent
+value :remainder, input.x % input.y
 ```
 
-### String Operations
+**Comparison:**
+```kumi
+>   >=   <   <=   ==   !=
 
-```ruby
-# All string operations use function syntax
-trait :long_name, fn(:string_length, input.name) >  20
-trait :starts_with_a, fn(:start_with?, input.name, "A")
-trait :contains_space, fn(:contains?, input.name, " ")
+trait :is_adult, input.age >= 18
+trait :is_expensive, input.price > 100.0
+trait :exact_match, input.category == "electronics"
 ```
 
-## Expressions
+**Boolean:**
+```kumi
+&   |   !
 
-### Complex Expressions
+trait :premium, is_adult & is_expensive
+trait :eligible, is_member | is_trial
+trait :not_active, !is_active
+```
 
-```ruby
-# With Sugar
-value :weighted_score, (input.math_score * 0.4) + (input.verbal_score * 0.3) + (input.writing_score * 0.3)
-value :percentile_rank, ((scored_better_than / total_students) * 100).round(2)
+### 4) Functions
 
-# Sugar-Free
-value :weighted_score, fn(:add, 
-  fn(:add, 
-    fn(:multiply, input.math_score, 0.4), 
-    fn(:multiply, input.verbal_score, 0.3)
-  ), 
-  fn(:multiply, input.writing_score, 0.3)
-)
-value :percentile_rank, fn(:round, 
-  fn(:multiply, 
-    fn(:divide, scored_better_than, total_students), 
-    100
-  ), 
-  2
-)
+All functions use `fn(:name, args...)` syntax.
+
+#### Aggregation (Reduce Dimension)
+
+**Sum and Count:**
+```kumi
+value :total, fn(:sum, input.items.item.price)
+value :count, fn(:count, input.items.item.price)
 ```
 
-### Collection Operations
+**Min, Max, Mean:**
+```kumi
+value :highest, fn(:max, input.items.item.price)
+value :lowest, fn(:min, input.items.item.price)
+value :average, fn(:mean, input.scores.score)
+```
 
-```ruby
-# With Sugar
-value :total_scores, input.score_array.sum
-value :score_count, input.score_array.size
-value :unique_scores, input.score_array.uniq.size
-value :sorted_scores, input.score_array.sort
+**Conditional Aggregation:**
+```kumi
+trait :expensive, input.items.item.price > 100.0
+value :expensive_sum, fn(:sum_if, input.items.item.price, expensive)
+value :expensive_avg, fn(:mean_if, input.items.item.price, expensive)
+value :zero_count, fn(:count_if, input.cells.value, 0)
+```
 
-# Sugar-Free
-value :total_scores, fn(:sum, input.score_array)
-value :score_count, fn(:size, input.score_array)
-value :unique_scores, fn(:size, fn(:unique, input.score_array))
-value :sorted_scores, fn(:sort, input.score_array)
+**Boolean Aggregation:**
+```kumi
+value :has_any_active, fn(:any, input.flags.active)
+value :all_passed, fn(:all, input.checks.passed)
 ```
 
-## Functions
+**String Aggregation:**
+```kumi
+value :combined, fn(:join, input.words.word)
+```
 
-### Built-in Functions Available
+#### Elementwise (No Dimension Change)
 
-See [FUNCTIONS.md](FUNCTIONS.md)
+**Array Utilities:**
+```kumi
+value :num_rows, fn(:array_size, input.matrix.row)
+value :first_item, fn(:at, input.items, 0)
 
-| Category | Sugar | Sugar-Free |
-|----------|-------|------------|
-| **Arithmetic** | `+`, `-`, `*`, `/`, `**` | `fn(:add, a, b)`, `fn(:subtract, a, b)`, etc. |
-| **Comparison** | `>`, `<`, `>=`, `<=`, `==`, `!=` | `fn(:>, a, b)`, `fn(:<, a, b)`, etc. |
-| **Logical** | `&` `|` | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
-| **Math** | `abs`, `round`, `ceil`, `floor` | `fn(:abs, x)`, `fn(:round, x)`, etc. |
-| **String** | `.length`, `.upcase`, `.downcase` | `fn(:string_length, s)`, `fn(:upcase, s)`, etc. |
-| **Collection** | `.sum`, `.size`, `.max`, `.min` | `fn(:sum, arr)`, `fn(:size, arr)`, etc. |
+let :W, fn(:array_size, input.x.y)
+value :linear_idx, (index(:i) * W) + index(:j)
+```
+
+**String Operations:**
+```kumi
+value :full_name, fn(:concat, input.first_name, input.last_name)
+value :upper, fn(:upcase, input.name)
+value :lower, fn(:downcase, input.name)
+value :name_len, fn(:length, input.name)
+```
+
+**Math:**
+```kumi
+value :magnitude, fn(:abs, input.value)
+value :bounded, fn(:clamp, input.value, 0, 100)
+```
 
-### Custom Function Calls
+### 5) Conditionals
 
-```ruby
-# With Sugar (when available)
-value :clamped_score, input.raw_score.clamp(0, 1600)
-value :formatted_name, input.first_name + " " + input.last_name
+#### Simple Selection with `select`
 
-# Sugar-Free (always available)
-value :clamped_score, fn(:clamp, input.raw_score, 0, 1600)
-value :formatted_name, fn(:add, fn(:add, input.first_name, " "), input.last_name)
+```kumi
+trait :is_expensive, input.items.item.price > 100.0
+value :discounted, select(is_expensive,
+  input.items.item.price * 0.9,
+  input.items.item.price
+)
 ```
 
-## Array Broadcasting
+#### Multi-way Cascade with `on`
 
-Array broadcasting enables element-wise operations on array fields with automatic vectorization.
+First matching condition wins:
 
-### Array Input Declarations
+```kumi
+trait :x_positive, input.x > 0
+trait :y_positive, input.y > 0
 
-```ruby
-input do
-  # Structured array with defined fields
-  array :line_items do
-    float   :price
-    integer :quantity
-    string  :category
-  end
-  
-  # Nested arrays with hash objects
-  array :orders do
-    array :items do
-      hash :product do
-        string :name
-        float  :base_price
-      end
-      integer :quantity
-    end
-  end
-  
-  # Dynamic arrays with flexible element types
-  array :api_responses do
-    element :any, :response_data    # For dynamic/unknown hash structures
-  end
-  
-  array :measurements do
-    element :float, :value          # For simple scalar arrays
-  end
+value :status do
+  on y_positive, x_positive, "both positive"
+  on x_positive,             "x positive"
+  on y_positive,             "y positive"
+  base                       "neither positive"
 end
 ```
 
-### Element-wise Operations
+**Complex Example with Broadcasting:**
+```kumi
+trait :high_performer, input.employees.employee.rating >= 4.5
+trait :senior, input.employees.employee.level == "senior"
+trait :top_team, input.teams.team.performance_score >= 0.9
 
-```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)
+value :bonus do
+  on high_performer, senior, top_team, input.employees.employee.salary * 0.30
+  on high_performer, top_team,         input.employees.employee.salary * 0.20
+  base                                 input.employees.employee.salary * 0.05
+end
 ```
 
-### Aggregation Operations
+### 6) Tuples and Indexing
 
-```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)
+#### Tuple Literals
 
-# 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)
+```kumi
+value :scores, [100, 85, 92]
+value :coords, [input.x, input.y]
+value :mixed, [1, input.x + 10, input.y * 2]
 ```
 
-### Nested Array Access
+#### Tuple Indexing
 
-```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
+```kumi
+value :scores, [100, 85, 92]
+value :first, scores[0]
+value :second, scores[1]
+value :third, scores[2]
+```
 
-# 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)
+#### Operations on Tuples
+
+```kumi
+value :coords, [input.x, input.y, input.z]
+value :max_coord, fn(:max, coords)
+value :sum_coords, fn(:sum, coords)
 ```
 
-### Mixed Operations
+#### Vectorized Tuple Operations
+
+When tuples contain array elements:
 
-```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)
+```kumi
+trait :x_large, input.points.point.x > 100
+value :selected, select(x_large,
+  input.points.point.x,
+  input.points.point.y
+)
 
-# 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)
+# For each point, compute max of selected and x
+value :max_per_point, fn(:max, [selected, input.points.point.x])
 ```
 
-### Dynamic Hash Elements with `element :any`
+### 7) Spatial Operations
+
+#### `shift` — Access Neighbors
+
+Move along arrays to access adjacent values.
+
+**Syntax:**
+```kumi
+shift(expr, offset, axis_offset: 0, policy: :zero)
+```
 
-For arrays containing hash data with unknown or flexible structure, use `element :any` instead of defining explicit hash objects:
+**Parameters:**
+- `offset`: Distance to shift (negative = left/up, positive = right/down)
+- `axis_offset`: Which dimension (0 = innermost/x, 1 = next/y, etc.)
+- `policy`: Edge handling
+  - `:zero` (default) — Use 0 for out-of-bounds
+  - `:wrap` — Wrap to opposite edge
+  - `:clamp` — Repeat edge value
 
-```ruby
+**1D Example:**
+```kumi
 input do
-  array :api_responses do
-    element :any, :response_data
-  end
-  
-  array :user_profiles do
-    element :any, :profile_info
+  array :cells do
+    integer :value
   end
 end
 
-# Access hash data using fn(:fetch)
-value :response_codes, fn(:fetch, input.api_responses.response_data, "status")
-value :user_names, fn(:fetch, input.user_profiles.profile_info, "name")
-value :user_ages, fn(:fetch, input.user_profiles.profile_info, "age")
+value :left,  shift(input.cells.value, -1)
+value :right, shift(input.cells.value,  1, policy: :wrap)
+```
+
+**2D Example (Game of Life):**
+```kumi
+let :a, input.rows.col.alive
+
+# Horizontal (axis_offset: 0, default)
+let :w, shift(a, -1)                  # West
+let :e, shift(a,  1)                  # East
+
+# Vertical (axis_offset: 1)
+let :n, shift(a, -1, axis_offset: 1)  # North
+let :s, shift(a,  1, axis_offset: 1)  # South
 
-# Mathematical operations on extracted values
-value :avg_response_time, fn(:mean, fn(:fetch, input.api_responses.response_data, "response_time"))
-value :total_users, fn(:size, input.user_profiles.profile_info)
+# Diagonals (shift twice)
+let :nw, shift(n, -1)
+let :ne, shift(n,  1)
+let :sw, shift(s, -1)
+let :se, shift(s,  1)
 
-# Traits using dynamic data
-trait :success_responses, fn(:any?, fn(:fetch, input.api_responses.response_data, "status") == 200)
-trait :adult_users, fn(:any?, fn(:fetch, input.user_profiles.profile_info, "age") >= 18)
+let :neighbors, fn(:sum, [n, s, w, e, nw, ne, sw, se])
 ```
 
-**Use Cases for `element :any`:**
-- API responses with varying schemas
-- Configuration data with flexible structure  
-- Dynamic hash structures (unknown keys at schema definition time)
-- Legacy data where hash structure may vary
-- When you need maximum flexibility without type constraints
+#### `roll` — Rotate with Wrapping
 
-**Comparison: `element :any` vs Hash Objects**
+Convenience for 1D rotations:
 
-```ruby
-# element :any approach (flexible, dynamic)
-array :users do
-  element :any, :data
-end
-value :names, fn(:fetch, input.users.data, "name")
+```kumi
+value :roll_right, roll(input.cells.value,  1)                    # Wrap (default)
+value :roll_left,  roll(input.cells.value, -1)
+value :roll_clamp, roll(input.cells.value,  1, policy: :clamp)
+```
 
-# hash object approach (typed, structured)  
-array :users do
-  hash :data do
-    string :name
-    integer :age
-  end
-end
-value :names, input.users.data.name
+### 8) Reductions and Broadcasting
+
+#### Reductions
+
+Aggregation functions reduce dimensionality:
+
+**1D → Scalar:**
+```kumi
+value :total, fn(:sum, input.items.item.price)
 ```
 
-### Broadcasting Type Inference
+**2D → 1D (reduce inner dimension):**
+```kumi
+value :row_sums, fn(:sum, input.rows.col.v)
+```
+
+**2D → Scalar (double reduction):**
+```kumi
+value :grand_total, fn(:sum, fn(:sum, input.rows.col.v))
+```
+
+**3D → Scalar (triple reduction):**
+```kumi
+trait :over_limit, input.cube.layer.row.cell > 100
+value :sum_over, fn(:sum_if, input.cube.layer.row.cell, over_limit)
+value :total, fn(:sum, fn(:sum, sum_over))
+```
+
+#### Broadcasting
+
+Values at higher/parent levels automatically broadcast to lower/child levels.
 
-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
+**Scalar to Array:**
+```kumi
+input do
+  array :items do
+    hash :item do
+      float :price
+    end
+  end
+  float :discount  # Scalar
+end
 
-## Cascade Logic
+# discount broadcasts to each item
+value :discounted, input.items.item.price * (1.0 - input.discount)
+```
 
-Cascades are similar to Ruby when case, where each case is one of more trait reference and finally the value if that branch is true.
-```ruby
-value :grade_letter do
-  on excellent_student, "A+"       
-  on high_scorer, "A"              
-  on above_average, "B"            
-  on needs_improvement, "C"        
-  base "F"
+**Parent Level to Child Level:**
+```kumi
+input do
+  array :departments do
+    hash :dept do
+      array :teams do
+        hash :team do
+          integer :headcount
+        end
+      end
+    end
+  end
 end
+
+# Reduce to department level
+value :dept_total, fn(:sum, input.departments.dept.teams.team.headcount)
+
+# dept_total broadcasts to team level
+trait :large_team, input.departments.dept.teams.team.headcount > dept_total / 3
 ```
 
+**Key Rule:** Axes align by identity (lineage), not name. A department-level value knows which teams belong to it.
+
+### 9) Common Patterns
 
-## References
+#### Filter and Aggregate
 
-### Referencing Other Declarations
+```kumi
+trait :expensive, input.items.item.price > 100.0
+value :expensive_total, fn(:sum_if, input.items.item.price, expensive)
+value :expensive_count, fn(:sum_if, 1, expensive)
+```
 
-```ruby
-# Both syntaxes (same)
-trait :qualified_senior, qualified & (input.age >= 65)
-value :bonus_points, qualified_senior ? 100 : 0
+#### Map then Reduce
 
-# Explicit reference syntax (both syntaxes)
-trait :qualified_senior, ref(:qualified) & (input.age >= 65)
-value :bonus_points, ref(:qualified_senior) ? 100 : 0
+```kumi
+value :subtotals, input.items.item.price * input.items.item.quantity
+value :cart_total, fn(:sum, subtotals)
 ```
 
-### Input Field References
+#### Conditional Aggregation in Hierarchies
 
-```ruby
-# Both syntaxes (same)
-input.field_name          # Access input field
-input.field_name.method   # Call method on input field (sugar)
-fn(:method, input.field_name)  # Call method on input field (sugar-free)
+```kumi
+trait :over_limit, input.cube.layer.row.cell > 100
+value :cell_sum, fn(:sum_if, input.cube.layer.row.cell, over_limit)
+value :total, fn(:sum, fn(:sum, cell_sum))
 ```
 
-## Complete Example Comparison
+#### Hash Construction
 
-### With Sugar (Recommended)
+```kumi
+value :users, {
+  name: input.users.user.name,
+  state: input.users.user.state
+}
 
-```ruby
-module StudentEvaluation
-  extend Kumi::Schema
+trait :is_john, input.users.user.name == "John"
+value :john_user, select(is_john, users, "NOT_JOHN")
+```
 
-  schema do
-    input do
-      integer :math_score, domain: 0..800
-      integer :verbal_score, domain: 0..800
-      integer :writing_score, domain: 0..800
-      integer :age, domain: 16..25
-      string :status, domain: %w[active inactive]
-    end
+#### Index-Based Calculations
 
-    # Calculated values with sugar
-    value :total_score, input.math_score + input.verbal_score + input.writing_score
-    value :average_score, total_score / 3
-    value :scaled_average, fn(:round, average_score * 1.2, 2)
-
-    # Traits with sugar
-    trait :high_performer, total_score >= 2100
-    trait :math_excellence, input.math_score >= 750
-    trait :eligible_student, (input.age >= 18) & (input.status == "active")
-    trait :scholarship_candidate, high_performer & math_excellence & eligible_student
-
-    # Cascade with sugar-defined traits
-    value :scholarship_amount do
-      on scholarship_candidate, 10000
-      on high_performer, 5000
-      on math_excellence, 2500
-      base 0
+```kumi
+input do
+  array :x, index: :i do
+    array :y, index: :j do
+      integer :_
     end
   end
 end
+
+let :W, fn(:array_size, input.x.y)
+value :row_major, (index(:i) * W) + index(:j)
+value :col_major, (index(:j) * fn(:array_size, input.x)) + index(:i)
+value :coord_sum, index(:i) + index(:j)
 ```
 
-### Sugar-Free (Explicit)
+---
 
-```ruby
-module StudentEvaluation
-  extend Kumi::Schema
+## Complete Examples
 
-  schema do
-    input do
-      integer :math_score, domain: 0..800
-      integer :verbal_score, domain: 0..800
-      integer :writing_score, domain: 0..800
-      integer :age, domain: 16..25
-      string :status, domain: %w[active inactive]
-    end
+### Shopping Cart with Discounts
 
-    # Calculated values without sugar
-    value :total_score, fn(:add, fn(:add, input.math_score, input.verbal_score), input.writing_score)
-    value :average_score, fn(:divide, total_score, 3)
-    value :scaled_average, fn(:round, fn(:multiply, average_score, 1.2), 2)
-
-    # Traits without sugar
-    trait :high_performer, fn(:>=, total_score, 2100)
-    trait :math_excellence, fn(:>=, input.math_score, 750)
-    trait :eligible_student, fn(:and, fn(:>=, input.age, 18), fn(:==, input.status, "active"))
-    trait :scholarship_candidate, fn(:and, fn(:and, high_performer, math_excellence), eligible_student)
-
-    # Cascade with sugar-free defined traits
-    value :scholarship_amount do
-      on scholarship_candidate, 10000
-      on high_performer, 5000
-      on math_excellence, 2500
-      base 0
+```kumi
+schema do
+  input do
+    array :items do
+      hash :item do
+        float :price
+        integer :qty
+      end
     end
+    float :discount
   end
+
+  value :items_subtotal, input.items.item.price * input.items.item.qty
+  value :items_discounted, input.items.item.price * (1.0 - input.discount)
+
+  value :items_is_big, input.items.item.price > 100.0
+  value :items_effective, select(items_is_big,
+    items_subtotal * 0.9,
+    items_subtotal
+  )
+
+  value :total_qty, fn(:sum, input.items.item.qty)
+  value :cart_total, fn(:sum, items_subtotal)
+  value :cart_total_effective, fn(:sum, items_effective)
 end
 ```
 
-## When to Use Each Syntax
+### Conway's Game of Life
+
+```kumi
+schema do
+  input do
+    array :rows do
+      array :col do
+        integer :alive  # 0 or 1
+      end
+    end
+  end
+
+  let :a, input.rows.col.alive
 
-### Use Sugar Syntax When:
-- ✅ Writing schemas by hand
-- ✅ Readability is important
-- ✅ Working with simple to moderate complexity
-- ✅ You want concise, Ruby-like expressions
+  let :n,  shift(a, -1, axis_offset: 1)
+  let :s,  shift(a,  1, axis_offset: 1)
+  let :w,  shift(a, -1)
+  let :e,  shift(a,  1)
+  let :nw, shift(n, -1)
+  let :ne, shift(n,  1)
+  let :sw, shift(s, -1)
+  let :se, shift(s,  1)
 
-### Use Sugar-Free Syntax When:
-- ✅ Generating schemas programmatically
-- ✅ Building dynamic schemas in loops/methods
-- ✅ You need explicit control over function calls
-- ✅ Working with complex nested expressions
-- ✅ Debugging expression evaluation issues
+  let :neighbors, fn(:sum, [n, s, w, e, nw, ne, sw, se])
 
-## Syntax Limitations
+  let :alive, a > 0
+  let :n3_alive, neighbors == 3
+  let :n2_alive, neighbors == 2
+  let :keep_alive, n2_alive & alive
+  let :next_alive, n3_alive | keep_alive
+
+  value :next_state, select(next_alive, 1, 0)
+end
+```
+
+### Hierarchical Organization Analysis
+
+```kumi
+schema do
+  input do
+    array :departments do
+      hash :dept do
+        string :dept_name
+        array :teams do
+          hash :team do
+            string :team_name
+            integer :headcount
+          end
+        end
+      end
+    end
+  end
+
+  value :dept_headcount, fn(:sum, input.departments.dept.teams.team.headcount)
+  value :teams_per_dept, fn(:count, input.departments.dept.teams.team.team_name)
+  value :avg_headcount_per_dept, dept_headcount / teams_per_dept
+
+  trait :is_above_average_team,
+    input.departments.dept.teams.team.headcount > avg_headcount_per_dept
+end
+```
 
-### Sugar Syntax Limitations:
-- Supports `&` for logical AND (no `&&` due to Ruby precedence)
-- Supports `|` for logical OR
-- Limited operator precedence control
-- Some Ruby methods not available as sugar
-- **Refinement scope**: Array methods like `.max` on syntax expressions may not work in certain contexts (e.g., test helpers, Ruby < 3.0). Use `fn(:max, array)` instead.
+---
 
-### Sugar-Free Advantages:
-- Full access to all registered functions
-- Clear operator precedence through explicit nesting
-- Works in all contexts (including programmatic generation)
-- More explicit about what operations are being performed
+## Best Practices
 
-## Performance Notes
+**Do:**
+- Use `trait` for boolean conditions
+- Use `fn(:array_size, ...)` instead of hardcoding lengths
+- Name intermediate values with `let` for clarity
+- Think about which dimension you're reducing
+- Remember axes align by lineage, not name
 
-Both syntaxes compile to identical internal representations, so there is **no performance difference** between sugar and sugar-free syntax. Choose based on readability and maintenance needs.
+**Don't:**
+- Forget that aggregation functions reduce dimensionality
+- Hardcode array sizes
+- Mix up `axis_offset` values (0 = inner/x, 1 = outer/y)