kumi 0.0.31 → 0.0.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b228964d7834bd37eb2b5f969fb288edbb4dab6e27ef72d45a04fa9fb87a2d0
-  data.tar.gz: 79e0b9db5acedb69e61eb6799844fa6a849fca4ed604e79522af03147e3e0436
+  metadata.gz: 7b98e39a72b87991ec1e2055ca1ad9ca996a1e95924ca5d4e201043f679564ed
+  data.tar.gz: ac6b469fd9cb3aa8d01bc4907c4f40ba5dbbc900e95e8309a9c68595b57d9c30
 SHA512:
-  metadata.gz: b28eb238da8e21b0ec51dd1f5c3e2ac769fd07bef7461787a456fded7dba4a5d7603e2d3eff110e23bbe69af8d28e303834d0aa12b2a06fe6ee7d8c441eae289
-  data.tar.gz: 98fa5a9f34f3ab1c8d9aea17ce888025713d73665de5a85608a4108fdcd697d587986ba24d404f505b35cabffadb8880765ec7f9cd803a232d2295bd4b6b36fc
+  metadata.gz: 3e8b32dbcb228a886a4089992ddaa2cabbe977477226561d09be2d6a3583ebf9d3276f338e99e9612e4c1dbfe6e911801b70747aa4dbc47b820949b2425661f0
+  data.tar.gz: 6537e18270ed92b04a80f14c24758cda316a5658a2d92d7940b2f7770ef51518eabd2f421e85516484f0c49b2c699f4bc2bac63e07b08b8108f8cd500654282f

data/CHANGELOG.md

@@ -1,4 +1,24 @@
 ## [Unreleased]
+
+## [0.0.33] – 2025-11-05
+### Added
+- **Peephole Optimization Helper:** `Kumi::Core::LIR::Peephole` plus specs for safer peephole transforms, inline Ruby clamp kernel, richer LIR dumps, and refreshed golden files
+- **Import Diagnostics:** Clearer errors with available declaration hints when imports fail
+
+### Changed
+- Default `Kumi.configure.compilation_mode` now `:jit`; override via config or `KUMI_COMPILATION_MODE`
+- Improved constant propagation output formatting for Ruby/JS codegen
+
+## [0.0.32] – 2025-10-23
+### Added
+- **Schema Imports:** Reuse declarations from other schemas with `import :name, from: Module` syntax
+- **Improved Import Errors:** Clearer messages with available declaration hints when imports fail
+- Documentation: `docs/COMPOSED_SCHEMAS.md` and `docs/SCHEMA_IMPORTS.md`
+
+## [0.0.31] – 2025-10-22
+### Changed
+- Documentation for schema imports in README and SYNTAX
+
 ## [0.0.30] – 2025-10-21
 ### Changed
 - **Analyzer Refactoring:** PassManager now centralizes pass orchestration, replacing manual orchestration in Analyzer.run_analysis_passes
@@ -174,4 +194,4 @@ Fix - Remove require of pry gem on runtime.
 - Ruby >= 3.1 (Was >= 3.0)
 
 ### Notes
-- No expected DSL changes for typical schemas; report regressions.
+- No expected DSL changes for typical schemas; report regressions.

data/README.md

@@ -10,116 +10,36 @@
 
 ## What is Kumi?
 
-Kumi is a **declarative DSL for building calculation systems** that are:
-- **Typed & verifiable at compile time** (catch errors before they hit production)
-- **Vectorized** (arrays and nested data structures work naturally)
-- **Transparent** (inspect generated code and execution order)
-- **Portable** (compile the same schema to Ruby or JavaScript)
+Kumi is a **declarative DSL for building calculation systems**.
 
-Instead of writing procedural formulas, you declare *what* values depend on *what*, and Kumi figures out the computation order, validates types, detects impossible constraints, and generates efficient code.
+Schemas define:
+- Input shape (scalars, arrays, nested structures)
+- Declarations (computed values and boolean conditions)
+- Dependencies between declarations
 
-## Why Kumi Exists
+The compiler:
+- Performs type checking
+- Detects unsatisfiable constraints
+- Determines evaluation order
+- Generates code for Ruby or JavaScript
 
-Calculation systems are everywhere: tax engines, pricing models, financial projections, compliance checks. They're usually:
-- Hard to verify (logic spread across multiple files)
-- Fragile (changing one formula breaks hidden dependencies)
-- Duplicated (same logic needed in backend and frontend)
-- Opaque (hard to audit which rules applied to which data)
+## Use Cases
 
-Kumi makes them explicit, testable, and portable.
+Calculation systems appear in: tax engines, pricing models, financial projections, compliance systems, insurance underwriting, shipping rate calculators.
 
 ---
 
 **Status**: experimental. Public API may change. Typing and some static checks are still evolving.
 
-**Feedback**: have a use case or hit a rough edge? Open an issue or reach out.
+**Feedback**: have a use case or hit a rough edge? Open an issue or reach out (andremuta+kumi@gmail.com).
 
 ---
 
-## Example: US Tax Calculator (2024)
+## Examples
 
-A single schema computes federal, state, FICA taxes across multiple filing statuses—all types verified at compile time. Try it in the [interactive demo](https://kumi-play-web.fly.dev/) or inspect the [full schema, input, output, and generated code](golden/us_tax_2024/).
-
-<details>
-<summary><strong>Schema</strong></summary>
-
-```ruby
-schema do
-  input do
-    float  :income
-    float  :state_rate
-    float  :local_rate
-    float  :retirement_contrib
-    string :filing_status
-
-    array :statuses do
-      hash :status do
-        string :name
-        float  :std
-        float  :addl_threshold
-        array  :rates do
-          hash :bracket do
-            float :lo
-            float :hi # -1 = open-ended
-            float :rate
-          end
-        end
-      end
-    end
-  end
-
-  # shared
-  let :big_hi, 100_000_000_000.0
-  let :state_tax, input.income * input.state_rate
-  let :local_tax, input.income * input.local_rate
-
-  # FICA constants
-  let :ss_wage_base, 168_600.0
-  let :ss_rate, 0.062
-  let :med_base_rate, 0.0145
-  let :addl_med_rate, 0.009
-
-  # per-status federal
-  let :taxable,   fn(:max, [input.income - input.statuses.status.std, 0])
-  let :lo,        input.statuses.status.rates.bracket.lo
-  let :hi,        input.statuses.status.rates.bracket.hi
-  let :rate,      input.statuses.status.rates.bracket.rate
-  let :hi_eff,    select(hi == -1, big_hi, hi)
-  let :amt,       fn(:clamp, taxable - lo, 0, hi_eff - lo)
-  let :fed_tax,   fn(:sum, amt * rate)
-  let :in_br,     (taxable >= lo) & (taxable < hi_eff)
-  let :fed_marg,  fn(:sum_if, rate, in_br)
-  let :fed_eff,   fed_tax / fn(:max, [input.income, 1.0])
-
-  # per-status FICA
-  let :ss_tax,         fn(:min, [input.income, ss_wage_base]) * ss_rate
-  let :med_tax,        input.income * med_base_rate
-  let :addl_med_tax,   fn(:max, [input.income - input.statuses.status.addl_threshold, 0]) * addl_med_rate
-  let :fica_tax,       ss_tax + med_tax + addl_med_tax
-  let :fica_eff,       fica_tax / fn(:max, [input.income, 1.0])
-
-  # totals per status
-  let :total_tax,  fed_tax + fica_tax + state_tax + local_tax
-  let :total_eff,  total_tax / fn(:max, [input.income, 1.0])
-  let :after_tax,  input.income - total_tax
-  let :take_home,  after_tax - input.retirement_contrib
-
-  # array of result objects, one per status
-  value :summary, {
-    filing_status: input.statuses.status.name,
-    federal: { marginal: fed_marg, effective: fed_eff, tax: fed_tax },
-    fica: { effective: fica_eff, tax: fica_tax },
-    state: { marginal: input.state_rate, effective: input.state_rate, tax: state_tax },
-    local: { marginal: input.local_rate, effective: input.local_rate, tax: local_tax },
-    total: { effective: total_eff, tax: total_tax },
-    after_tax: after_tax,
-    retirement_contrib: input.retirement_contrib,
-    take_home: take_home
-  }
-end
-```
-
-</details>
+- **US Tax Calculator (2024)** — a single schema computes federal, state, and FICA taxes across multiple filing statuses. [Open in the demo](https://kumi-play-web.fly.dev/?example=us-federal-tax-2024).
+- **Monte Carlo Portfolio** — demonstrates probabilistic simulations and table visualizations. [Open in the demo](https://kumi-play-web.fly.dev/?example=monte-carlo-simulation).
+- **Conway's Game of Life** — showcases array operations powering a grid-based simulation. [Open in the demo](https://kumi-play-web.fly.dev/?example=game-of-life).
 
 ---
 
@@ -129,7 +49,7 @@ end
 gem install kumi
 ```
 
-Requires Ruby 3.1+. No external dependencies.
+Requires Ruby 3.1+. Runtime dependencies: `mutex_m` and `zeitwerk` (bundled via Rubygems).
 
 ## Quick Start
 
@@ -149,17 +69,29 @@ end
 result = Double.from(x: 5)
 result[:doubled]  # => 10
 
+# or just call the method directly
+Double._doubled(x: 5) # => 10
+
 # Export to JavaScript (same logic)
 Double.write_source("output.mjs", platform: :javascript)
+# ./output.mjs
+# export function _doubled(input) {
+#   let t1 = input["x"];
+#   let t3 = t1 * 2;
+#   return t3;
+# }
 ```
 
+You can also override the compilation strategy without touching code by setting
+`KUMI_COMPILATION_MODE` to `jit` or `aot` (e.g. `export KUMI_COMPILATION_MODE=aot`).
+
 Try the [interactive demo](https://kumi-play-web.fly.dev/) (no setup required).
 
 ---
 
 ## Documentation
 
-- **[Syntax Reference](docs/SYNTAX.md)** - DSL syntax, types, operators, and functions
+- **[Syntax Reference](docs/SYNTAX.md)** - DSL syntax, types, operators, functions, and schema imports
 - **[Functions Reference](docs/FUNCTIONS.md)** - Auto-generated docs for all functions and kernels
 - **[functions-reference.json](docs/functions-reference.json)** - Machine-readable format for IDEs (VSCode, Monaco, etc.)
 - **[Development Guide](docs/DEVELOPMENT.md)** - Testing, debugging, and contributing

data/data/kernels/ruby/core/arithmetic.yaml

@@ -39,5 +39,5 @@ kernels:
   
   - id: clamp:ruby:v1
     fn: core.clamp
-    inline: "= [[ $0, $1 ].max, $2 ].min"
-    impl: "(x, lo, hi)\n  [[x, lo].max, hi].min"
+    inline: "= $0.clamp($1, $2)"
+    impl: "(x, lo, hi)\n  x.clamp(lo, hi)"

data/docs/COMPOSED_SCHEMAS.md

@@ -0,0 +1,137 @@
+# Composed Schemas
+
+Multiple schemas can be imported and called within a single schema.
+
+## Example: Order Processing with Price and Tax
+
+### Step 1: Define Base Schemas
+
+**Price Calculation** (`golden/_shared/price.rb`):
+```ruby
+module GoldenSchemas
+  module Price
+    extend Kumi::Schema
+
+    schema do
+      input do
+        decimal :base_price
+        decimal :discount_rate
+      end
+
+      value :discounted, input.base_price * (1.0 - input.discount_rate)
+      value :discount_amount, input.base_price * input.discount_rate
+    end
+  end
+end
+```
+
+**Tax Calculation** (`golden/_shared/tax.rb`):
+```ruby
+module GoldenSchemas
+  module Tax
+    extend Kumi::Schema
+
+    schema do
+      input do
+        decimal :amount
+      end
+
+      value :tax, input.amount * 0.15
+      value :total, input.amount + tax
+    end
+  end
+end
+```
+
+### Composed Order Schema
+
+```ruby
+module GoldenSchemas
+  module ComposedOrder
+    extend Kumi::Schema
+
+    schema do
+      import :discounted, :discount_amount, from: GoldenSchemas::Price
+      import :total, from: GoldenSchemas::Tax
+
+      input do
+        decimal :item_price
+        decimal :quantity
+        decimal :discount_rate
+      end
+
+      value :subtotal, input.item_price * input.quantity
+      value :price_after_discount, fn(:discounted, base_price: subtotal, discount_rate: input.discount_rate)
+      value :discount_amt, fn(:discount_amount, base_price: subtotal, discount_rate: input.discount_rate)
+      value :final_total, fn(:total, amount: price_after_discount)
+    end
+  end
+end
+```
+
+### Test Data and Output
+
+Input:
+```json
+{
+  "item_price": 100.0,
+  "quantity": 3,
+  "discount_rate": 0.1
+}
+```
+
+Output:
+```json
+{
+  "subtotal": 300.0,
+  "price_after_discount": 270.0,
+  "discount_amt": 30.0,
+  "final_total": 310.5
+}
+```
+
+## Parameter Mapping
+
+Imported functions are called with keyword arguments that map to the imported schema's input fields.
+
+Price schema input fields: `base_price`, `discount_rate`
+```kumi
+discounted(base_price: subtotal, discount_rate: input.discount_rate)
+```
+
+Tax schema input fields: `amount`
+```kumi
+total(amount: price_after_discount)
+```
+
+The compiler maps keyword argument names to the imported schema's input field names and generates a runtime call that passes these values as an input hash to the imported schema's method.
+
+## Compilation
+
+For each imported function call:
+1. Compiler locates the declaration in the imported schema
+2. Maps keyword arguments to input field names
+3. Generates a runtime call to the imported schema's generated method
+4. Passes parameter values as an input hash to the imported function
+5. The imported schema's compiled method executes independently at runtime
+
+## Testing
+
+Base schemas tested independently:
+```bash
+bin/kumi golden test schema_imports_discount_with_tax
+bin/kumi golden test schema_imports_nested_with_reductions
+```
+
+Composed schemas tested:
+```bash
+bin/kumi golden test schema_imports_composed_order
+```
+
+Working examples in `golden/`:
+- `schema_imports_with_imports` - single import
+- `schema_imports_broadcasting_with_imports` - broadcast across arrays
+- `schema_imports_discount_with_tax` - multiple imports
+- `schema_imports_nested_with_reductions` - nested arrays
+- `schema_imports_complex_order_calc` - complex multi-import
+- `schema_imports_composed_order` - composed price and tax

data/docs/SCHEMA_IMPORTS.md

@@ -0,0 +1,275 @@
+# Schema Imports Feature
+
+## Overview
+
+Schema imports allow you to reuse declarations (values and traits) from one schema in another schema by importing them from a source module.
+
+## How It Works
+
+### Compilation Pipeline
+
+The schema import feature works through multiple analysis passes:
+
+1. **NameIndexer**: Identifies all imported names in the schema
+2. **ImportAnalysisPass**: Loads the source schemas and extracts their analyzed state
+3. **ConvertCallToImportCall** (text parser only): Converts function calls to ImportCall nodes when the function name matches an imported declaration
+4. **DependencyResolver**: Creates dependency edges for ImportCall nodes
+5. **NormalizeToNASTPass**: **Substitutes** ImportCall nodes with the source expression, mapping parameters
+
+### Key Design Principle: Runtime Function Calls
+
+Imports are **compiled as runtime function calls** to the imported schema:
+
+1. The compiler analyzes the imported schema and generates its module methods
+2. When an imported function is called, the generated code invokes `ImportedModule._function_name(input_hash)`
+3. This allows for modular code generation and schema reuse
+
+**Behavior:**
+- Imported functions are called at runtime via generated code
+- Broadcasting still applies - the calling function iterates and calls the imported function for each array element
+- Parameter mapping creates input hashes that are passed to the imported function
+
+### Example: Tax Calculation
+
+**Imported Schema** (`GoldenSchemas::Tax`):
+```kumi
+schema do
+  input do
+    decimal :amount
+  end
+
+  value :tax, input.amount * 0.15
+  value :total, input.amount + tax
+end
+```
+
+**Calling Schema**:
+```kumi
+import :tax, from: GoldenSchemas::Tax
+
+schema do
+  input do
+    decimal :amount
+  end
+
+  value :tax_result, tax(amount: input.amount)
+  value :total, input.amount + tax_result
+end
+```
+
+**Generated Ruby Code**:
+```ruby
+def self._tax_result(input)
+  # The imported function is called at runtime:
+  t1 = input["amount"] || input[:amount]
+  t2 = GoldenSchemas::Tax._tax({"amount" => t1})
+  t2
+end
+```
+
+Note: The generated code uses module-level functions (`def self._name(input)`) rather than instance methods. Imported functions are invoked as module methods with parameter mapping, enabling schema composition and reuse.
+
+## Syntax
+
+### Import Declaration
+
+Text parser syntax:
+```kumi
+import :name1, :name2, from: Module::Path
+```
+
+Ruby DSL syntax:
+```ruby
+import :name1, :name2, from: SourceModule
+```
+
+### Imported Function Calls
+
+**Text parser** (identifier syntax):
+```kumi
+result = tax(amount: input.price)
+```
+
+**Ruby DSL** (function call syntax):
+```ruby
+result = fn(:tax, amount: input.price)
+```
+
+Both create an `ImportCall` node which gets substituted during normalization.
+
+## Broadcasting with Imports
+
+When you pass an array to an imported function, the calling schema iterates over the array and calls the imported function for each element:
+
+```kumi
+import :tax, from: GoldenSchemas::Tax
+
+schema do
+  input do
+    array :items do
+      hash :item do
+        decimal :amount
+      end
+    end
+  end
+
+  value :item_taxes, tax(amount: input.items.item.amount)
+  value :total_tax, fn(:sum, item_taxes)
+end
+```
+
+With input `items: [{amount: 100}, {amount: 200}, {amount: 300}]`:
+- The generated code loops over each item and calls `GoldenSchemas::Tax._tax({"amount" => item.amount})`
+- `item_taxes` becomes `[15, 30, 45]`
+- `total_tax` sums to `90`
+
+The generated code performs loop iteration and calls the imported function for each array element.
+
+## Parameter Mapping
+
+When you call an imported function with keyword arguments, the compiler:
+
+1. Maps each keyword argument name to the corresponding input field in the imported schema
+2. Constructs an input hash with the mapped parameter values
+3. Generates a runtime call to the imported function with this hash
+
+Example:
+```kumi
+# Imported schema input field: amount
+# Call: fn(:tax, amount: input.price)
+# Generated: GoldenSchemas::Tax._tax({"amount" => input.price})
+```
+
+Multiple parameters work similarly:
+```kumi
+# Imported schema input fields: price, rate
+# Call: fn(:discount, price: invoice.total, rate: 0.1)
+# Generated: GoldenSchemas::Discount._discount({"price" => invoice.total, "rate" => 0.1})
+```
+
+## Golden Test Cases
+
+### Basic Tests
+1. **`schema_imports_with_imports`** - Single import, scalar parameters
+2. **`schema_imports_broadcasting_with_imports`** - Broadcasting imported functions across arrays
+
+### Advanced Tests
+3. **`schema_imports_line_items`** - Importing reduction functions
+   - Imports `:subtotal` (sums quantity × price over array)
+   - Tests array aggregation through imports
+
+4. **`schema_imports_discount_with_tax`** - Multiple imports from different schemas
+   - Imports `:tax`, `:discounted`, `:savings`
+   - Tests composing multiple imported functions in sequence
+
+5. **`schema_imports_nested_with_reductions`** - Nested arrays with imports
+   - Imports subtotal and applies it to nested order structure
+   - Tests broadcasting imports through multiple levels
+
+6. **`schema_imports_complex_order_calc`** - Multiple imports with nested arrays
+   - Imports tax, discount, and subtotal functions
+   - Tests order processing with taxes, discounts, and summaries across multiple orders
+
+## Creating Reusable Schemas
+
+Shared schemas are defined in `golden/_shared/` as Ruby DSL modules:
+
+```ruby
+module GoldenSchemas
+  module Subtotal
+    extend Kumi::Schema
+
+    schema do
+      input do
+        array :items do
+          hash :item do
+            integer :quantity
+            integer :unit_price
+          end
+        end
+      end
+
+      value :subtotal, fn(:sum, input.items.item.quantity * input.items.item.unit_price)
+    end
+  end
+end
+```
+
+Then import in any schema:
+```kumi
+import :subtotal, from: GoldenSchemas::Subtotal
+
+schema do
+  value :order_total, subtotal(items: input.order_items)
+end
+```
+
+The shared schemas are automatically loaded and compiled in JIT mode when running golden tests.
+
+## Implementation Details
+
+### Parser Level (kumi-parser gem)
+
+**Text Parser Changes**:
+- Added `import` and `from` keywords to tokenizer
+- Extended `parse_imports()` to handle `import :name, from: Constant::Path` syntax
+- Added `parse_imported_function_call()` to handle identifier syntax like `tax(amount: value)`
+- Tracks `@imported_names` during parsing to create ImportCall nodes when appropriate
+
+**Key Methods**:
+- `parse_imports()`: Parses import declarations
+- `parse_constant()`: Parses scope-resolved constants like `GoldenSchemas::Tax`
+- `parse_imported_function_call()`: Parses direct function calls with keyword arguments
+
+### Analyzer Level (kumi gem)
+
+**New/Modified Passes**:
+- `ImportAnalysisPass`: Loads source schemas, extracts analyzed state, and prepares for runtime calls
+- `SemanticConstraintValidator`: Skips validation for imported function names
+- `CodegenPass`: Generates runtime function calls to imported schema methods
+
+**Key Data Structures**:
+- `ImportDeclaration`: Stores import metadata (names, source module)
+- `ImportCall`: Represents a call to an imported function (fn_name, input_mapping)
+- `imported_declarations`: State containing all imported names
+- `imported_schemas`: State containing full analysis of imported schemas (used to ensure schemas are compiled before use)
+
+## How Imports Are Compiled
+
+**Imports are compiled as runtime function calls:**
+
+1. The imported schema is fully analyzed and compiled as a standalone module with its own methods
+2. When you call an imported function, the compiler generates a call to that module's method
+3. Parameters are mapped and passed as a hash to the imported function at runtime
+
+**Example:**
+
+Imported schema defines: `value :tax, input.amount * 0.15`
+
+Your schema calls: `fn(:tax, amount: input.price)`
+
+Compiler produces:
+```ruby
+t1 = input["price"] || input[:price]
+t2 = GoldenSchemas::Tax._tax({"amount" => t1})
+```
+
+The imported function executes independently and returns its result to the calling schema.
+
+## Testing Strategy
+
+To verify imports are working correctly, test:
+
+1. **Parser correctness**: ImportCall nodes are created for imported functions
+2. **Parameter mapping**: Input hashes are correctly constructed from keyword arguments
+3. **Runtime calls**: Generated code properly invokes imported schema methods with parameter hashes
+4. **Broadcasting**: Loop iteration works correctly when passing arrays to imported functions
+5. **Runtime evaluation**: Generated code produces correct results by calling imported functions
+
+## Future Enhancements
+
+1. **Trait imports**: Support importing traits for reusable conditions
+2. **Nested imports**: Allow imported schemas to import other schemas
+3. **Import aliasing**: Rename imports on import (`import :tax as :tax_calc`)
+4. **Selective exports**: Mark declarations as publicly exportable
+5. **Cross-schema optimization**: Detect and optimize repeated patterns across imports

data/docs/SYNTAX.md

@@ -328,6 +328,54 @@ trait :eligible, is_member | is_trial
 trait :not_active, !is_active
 ```
 
+### 3) Schema Imports
+
+Reuse declarations from other schemas without duplicating code.
+
+#### Basic Import
+
+```kumi
+import :tax, from: MySchemas::TaxCalculator
+
+schema do
+  input do
+    decimal :amount
+  end
+
+  # Call imported declaration with input mapping
+  value :total, tax(amount: input.amount)
+end
+```
+
+#### Multiple Imports
+
+```kumi
+import :tax, :discount, from: MySchemas::Utilities
+
+schema do
+  input do
+    decimal :price
+  end
+
+  value :after_tax, tax(amount: input.price)
+  value :final, discount(amount: after_tax)
+end
+```
+
+#### Nested Imports
+
+Imported schemas can themselves import from other schemas. The compiler resolves the full chain automatically.
+
+```kumi
+# PriceSchema imports TaxSchema internally
+import :final_price, from: MySchemas::PriceSchema
+```
+
+**Key Rules:**
+- All imported declarations must be available when the schema loads
+- Input parameters are mapped by name (no positional arguments)
+- Imports work with reductions, broadcasts, and cascades like normal declarations
+
 ### 4) Functions
 
 All functions use `fn(:name, args...)` syntax.