kumi 0.0.33 → 0.0.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b98e39a72b87991ec1e2055ca1ad9ca996a1e95924ca5d4e201043f679564ed
-  data.tar.gz: ac6b469fd9cb3aa8d01bc4907c4f40ba5dbbc900e95e8309a9c68595b57d9c30
+  metadata.gz: 74f061f34a9936380a89aff28563594be891ac849f233613edf5ad9b52acce64
+  data.tar.gz: 8c7ee4b31d80293c18d8ea5914ae51ec80a489f6950352dd47044aa1b1aecba1
 SHA512:
-  metadata.gz: 3e8b32dbcb228a886a4089992ddaa2cabbe977477226561d09be2d6a3583ebf9d3276f338e99e9612e4c1dbfe6e911801b70747aa4dbc47b820949b2425661f0
-  data.tar.gz: 6537e18270ed92b04a80f14c24758cda316a5658a2d92d7940b2f7770ef51518eabd2f421e85516484f0c49b2c699f4bc2bac63e07b08b8108f8cd500654282f
+  metadata.gz: 70164a71693f388d25f2b2c8fc3c7d938860bb6e0f06344f06f7be96d1edb25a1e88686339fb81e919f6fde6d11510d14174cea22c3acc9f200bcc5c6fbf8724
+  data.tar.gz: 02df5faaef97f3d951a5fb022d7621daf1cec37ee482d0aa8db366c0ff7e0f44f6dc301302745249de1901c63c6e40dc52cff3e8d0019712ddae364196a4f642

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.0.35] – 2026-06-11
+### Added
+- **Dataflow IR Pipeline:** New DF IR graph, typed operations, validation, import inlining, broadcast simplification, CSE, load deduplication, tuple/object canonicalization, and golden artifact coverage.
+- **Vector IR Pipeline:** New VecIR builder, lowerer, validator, axis canonicalization, constant propagation, GVN, DCE, peephole simplification, stencil detection, and focused specs.
+- **Loop IR Pipeline:** New LoopIR builder/lowerer/validator and Ruby/JavaScript loop codegen path replacing the legacy LIR codegen pipeline.
+- **IR Tooling:** Shared IR base types, pass pipeline infrastructure, pretty printers, SNAST factory helpers, and expanded golden v2 output artifacts for DF/Vec/Loop stages.
+- **Regression Coverage:** External installed-gem loading spec that builds and installs the gem in an isolated `GEM_HOME` so runtime packaging issues are caught.
+
+### Changed
+- Removed the legacy LIR pipeline and refreshed golden outputs to the DF/Vec/Loop representation stack.
+- Updated generated Ruby and JavaScript output to use the LoopIR-backed codegen path.
+- Hardened kernel definitions and docs around numeric reductions, string aggregations, arithmetic helpers, and min/max empty-array behavior.
+- Revised architecture, schema import, golden test, and development documentation around the new IR pipeline.
+
+### Fixed
+- Runtime `require "kumi"` no longer loads golden-test support files or leaks the Zeitwerk loader as a top-level `AUTOLOADER` constant.
+- Golden shared schemas are loaded only through `Kumi.load_shared_schemas!`, preserving test support behavior without coupling it to normal gem loading.
+
 ## [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

data/README.md

@@ -10,36 +10,44 @@
 
 ## What is Kumi?
 
-Kumi is a **declarative DSL for building calculation systems**.
+Kumi is a **declarative DSL for calculation logic** — tax rules, pricing, scoring, financial projections — that compiles to plain Ruby and JavaScript.
 
-Schemas define:
-- Input shape (scalars, arrays, nested structures)
-- Declarations (computed values and boolean conditions)
-- Dependencies between declarations
+You declare the shape of your input data and the values you want computed. The compiler determines evaluation order, checks types, detects impossible conditions, and emits dependency-free code for each target.
 
-The compiler:
-- Performs type checking
-- Detects unsatisfiable constraints
-- Determines evaluation order
-- Generates code for Ruby or JavaScript
+```ruby
+schema do
+  input do
+    array :items do
+      hash :item do
+        integer :quantity
+        decimal :unit_price
+      end
+    end
+  end
 
-## Use Cases
+  value :line_totals, input.items.item.quantity * input.items.item.unit_price
+  value :subtotal, fn(:sum, line_totals)
+end
+```
 
-Calculation systems appear in: tax engines, pricing models, financial projections, compliance systems, insurance underwriting, shipping rate calculators.
+No loops, no iteration plumbing: `line_totals` is computed per item because that's where the data lives, and `fn(:sum, ...)` collapses it back to a scalar. This works through arbitrarily nested arrays.
 
----
+## Why
 
-**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
+- **One source of truth, two targets.** The same schema compiles to Ruby and JavaScript with identical semantics — write pricing logic once, run it in your backend and in the browser preview.
+- **Broadcasting from data shape.** Operations align over arrays automatically based on the declared input structure, including nested and ragged data.
+- **Static checks at compile time.** Type checking, dependency cycle detection, and unsatisfiable-constraint detection happen when the schema is defined, not in production.
+- **Boring generated code.** Output is deterministic, dependency-free, straight-line code with explicit loops. What you read is what runs.
 
-**Feedback**: have a use case or hit a rough edge? Open an issue or reach out (andremuta+kumi@gmail.com).
+## Use Cases
+
+Tax engines, pricing models, financial projections, compliance rules, insurance underwriting, shipping rate calculators — anywhere calculation logic must be correct, auditable, and consistent across platforms.
 
 ---
 
-## Examples
+**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
 
-- **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).
+**Feedback**: have a use case or hit a rough edge? Open an issue or reach out (andremuta+kumi@gmail.com).
 
 ---
 
@@ -85,18 +93,22 @@ Double.write_source("output.mjs", platform: :javascript)
 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).
+## Examples
+
+- **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** — probabilistic simulations and table visualizations. [Open in the demo](https://kumi-play-web.fly.dev/?example=monte-carlo-simulation).
+- **Conway's Game of Life** — array operations powering a grid-based simulation. [Open in the demo](https://kumi-play-web.fly.dev/?example=game-of-life).
 
 ---
 
 ## Documentation
 
-- **[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
-
-To regenerate function docs: `bin/kumi-doc-gen`
+- **[Syntax Reference](docs/SYNTAX.md)** — DSL syntax, types, operators, functions
+- **[Functions Reference](docs/FUNCTIONS.md)** — auto-generated docs for all functions and kernels ([machine-readable JSON](docs/functions-reference.json))
+- **[Schema Imports](docs/SCHEMA_IMPORTS.md)** — composing and reusing schemas
+- **[Architecture](docs/ARCHITECTURE.md)** — the compiler pipeline and IR stack
+- **[Golden Tests](docs/GOLDEN_TESTS.md)** — the end-to-end test harness
+- **[Development Guide](docs/DEVELOPMENT.md)** — tooling, docs generation, IDE integration
 
 ---
 

data/Rakefile

@@ -9,4 +9,6 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+Dir[File.join(__dir__, "tasks/**/*.rake")].each { |task_file| import task_file }
+
 task default: %i[spec rubocop]

data/data/functions/agg/numeric.yaml

@@ -7,6 +7,8 @@ functions:
       param: source_value
     reduction_strategy: identity # This function has a true identity value.
     aliases: ["sum"]
+    options:
+      tuple_fold_combiner: core.add
 
   - id: agg.count
     kind: reduce
@@ -25,6 +27,8 @@ functions:
       param: source_value
     reduction_strategy: first_element
     aliases: ["min"]
+    options:
+      tuple_fold_combiner: core.min
 
   - id: agg.max
     kind: reduce
@@ -34,6 +38,8 @@ functions:
       param: source_value
     reduction_strategy: first_element
     aliases: ["max"]
+    options:
+      tuple_fold_combiner: core.max
 
   - id: agg.mean
     kind: reduce

data/data/functions/core/arithmetic.yaml

@@ -7,6 +7,32 @@ functions:
       param: number
     aliases: ["abs"]
 
+  - id: core.max
+    kind: elementwise
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
+    constraint_semantics:
+      pure_combiner: true
+      commutativity: true
+      associativity: true
+
+  - id: core.min
+    kind: elementwise
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
+    constraint_semantics:
+      pure_combiner: true
+      commutativity: true
+      associativity: true
+
   - id: core.add
     kind: elementwise
     params:

data/data/kernels/javascript/agg/numeric.yaml

@@ -16,12 +16,16 @@ kernels:
 
   - id: agg.min:javascript:v1
     fn: agg.min
-    # Handles first element being null/undefined
-    inline: "= ($0 === null || $1 < $0) ? $1 : $0"
+    # Skips null values (an inner reduction over an empty array yields null);
+    # the $1 !== null guard is required because null coerces to 0 in
+    # relational comparisons (null < 5 is true).
+    inline: "= ($1 !== null && ($0 === null || $1 < $0)) ? $1 : $0"
     fold_inline: "= Math.min(...$0)"
 
   - id: agg.max:javascript:v1
     fn: agg.max
-    # Handles first element being null/undefined
-    inline: "= ($0 === null || $1 > $0) ? $1 : $0"
+    # Skips null values (an inner reduction over an empty array yields null);
+    # the $1 !== null guard is required because null coerces to 0 in
+    # relational comparisons (null > -5 is true).
+    inline: "= ($1 !== null && ($0 === null || $1 > $0)) ? $1 : $0"
     fold_inline: "= Math.max(...$0)"

data/data/kernels/javascript/agg/string.yaml

@@ -2,4 +2,7 @@ kernels:
   - id: agg.join:javascript:v1
     fn: agg.join
     inline: "+= $1"
-    fold_inline: "= $0.join('')"
+    fold_inline: "= $0.join('')"
+    # String concatenation identity: join over an empty array is "".
+    identity:
+      string: ""

data/data/kernels/javascript/core/arithmetic.yaml

@@ -7,6 +7,14 @@ kernels:
     fn: core.mod
     inline: "= (($0 % $1) + $1) % $1"
 
+  - id: max:javascript:v1
+    fn: core.max
+    inline: "= Math.max($0, $1)"
+
+  - id: min:javascript:v1
+    fn: core.min
+    inline: "= Math.min($0, $1)"
+
   - id: add:javascript:v1
     fn: core.add
     inline: "= $0 + $1"

data/data/kernels/ruby/agg/numeric.yaml

@@ -18,12 +18,16 @@ kernels:
 
   - id: agg.min:ruby:v1
     fn: agg.min
-    inline: "= $1 if $1 < $0" 
+    # Skips nil values (an inner reduction over an empty array yields nil),
+    # matching the javascript kernel's null handling.
+    inline: "= $1 if !$1.nil? && $1 < $0"
     impl: "(a, b)\n  a < b ? a : b"
     fold_inline: "= $0.min"
 
   - id: agg.max:ruby:v1
     fn: agg.max
-    inline: "= $1 if $1 > $0" 
+    # Skips nil values (an inner reduction over an empty array yields nil),
+    # matching the javascript kernel's null handling.
+    inline: "= $1 if !$1.nil? && $1 > $0"
     impl: "(a, b)\n  a > b ? a : b"
     fold_inline: "= $0.max"

data/data/kernels/ruby/agg/string.yaml

@@ -2,4 +2,7 @@ kernels:
   - id: agg.join:ruby:v1
     fn: agg.join
     inline: "+= $1"
-    fold_inline: "= $0.join"
+    fold_inline: "= $0.join"
+    # String concatenation identity: join over an empty array is "".
+    identity:
+      string: ""

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

@@ -7,6 +7,16 @@ kernels:
     fn: core.mod
     inline: "= $0 % $1"
   
+  - id: max:ruby:v1
+    fn: core.max
+    inline: "= $0 > $1 ? $0 : $1"
+    impl: "(a, b)\n  a > b ? a : b"
+
+  - id: min:ruby:v1
+    fn: core.min
+    inline: "= $0 < $1 ? $0 : $1"
+    impl: "(a, b)\n  a < b ? a : b"
+
   - id: add:ruby:v1
     fn: core.add
     inline: "= $0 + $1"

data/docs/AGENTS.md

@@ -0,0 +1,60 @@
+# Agent Reference
+
+A toolbox for inspecting and debugging the compiler pipeline. The pipeline is
+SNAST → DFIR → VecIR → LoopIR → Ruby/JS emitters; see
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Inspect One Layer for One Schema
+
+```bash
+bundle exec bin/kumi pp <repr> <schema.kumi>
+# reprs: ast, input_plan, nast, snast, dfir, dfir_optimized, vecir, loopir,
+#        schema_ruby, schema_javascript
+bundle exec bin/kumi pp loopir golden/multi_loop_reduction/schema.kumi
+```
+
+This is the fastest way to surface a lowering crash in a specific layer.
+
+## Sweep for Crashes
+
+```bash
+for d in golden/*/; do
+  bundle exec bin/kumi pp loopir "$d/schema.kumi" >/dev/null || echo "$d"
+done
+```
+
+## Phase-Scoped Golden Checks
+
+```bash
+bundle exec bin/kumi golden_v2 verify --repr loop            # one layer, all schemas
+bundle exec bin/kumi golden_v2 diff --repr df <schema>       # unified diff
+bundle exec bin/kumi golden_v2 update --repr vec,loop        # regenerate layers
+```
+
+Groups: `frontend`, `df`, `vec`, `loop`, `codegen`, `all`.
+
+## Runtime Ground Truth
+
+```bash
+bundle exec bin/kumi golden test            # regenerate + execute Ruby and JS
+bundle exec bin/kumi golden test <schema>
+```
+
+## Search Goldens Instead of Reading Them
+
+Some golden artifacts are large (`game_of_life`, `us_tax_2024`) — grep them:
+
+```bash
+rg -n "reduce" golden -g"dfir*.txt"
+rg -n "axis_shift" golden -g"vecir.txt"
+rg -n "function" golden/<schema>/expected/loopir.txt
+```
+
+## Other Useful Commands
+
+```bash
+bundle exec bin/kumi analyze <schema> --dump <state_key>   # inspect analyzer state
+bundle exec rspec                                          # full test suite
+```
+
+`tmp/` is gitignored and a good place for debug scripts.