kumi 0.0.36 → 0.0.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c1aeb3623e8c7a3e7f436ccaeb10323235e792b61b7f5c028373d62d9e199b3
-  data.tar.gz: 786c9d464c78d6fa67eb28803d6d6d6178f263cc2476e343a9c5f6307ae371da
+  metadata.gz: bb490e00af8d7e5b52df8056ed03f5b157670777ef4309b1805218999d71940f
+  data.tar.gz: 254c39487da8560617178f30f64ad1650c31e364f29452457c2931a45762e46e
 SHA512:
-  metadata.gz: 2b9e61de7438fbfacc2343b820bf5c36c1e66a3f44113af264705c8fee14d7a569dcd408fe1374a0ab0069765a63ee7ea04f44f9b1694862c4523023047eae00
-  data.tar.gz: f6bb5e93e9f2a7e8e06faa0831b619fdf83435b8b9cdb8555ad270bfb8db560fb344aa949527bfca6935e34049ada0f83b4234a203e3c112ae5ba9dc22cc384d
+  metadata.gz: 17ee44edcb98ae17de0ba57b422469769a0ef59f06b2c09d03b138b401dae63774b845532b0948c3abdd4173abb75e0d77c36af327d1630ac0362e7d791ebcc3
+  data.tar.gz: 78fd6d67671e81059ba9dfa6f10a5e4393e6fcef852409a3cccb93ee107a8f09d8c48a4366e4f3f3b4fb66fde8832925e3c089ffbf282ece6cc3fd694a802bfe

data/CHANGELOG.md

@@ -1,8 +1,8 @@
 ## [Unreleased]
 
-## [0.0.36] – 2026-06-11
-### Fixed
-- Keep `rdoc` as a development-only dependency so Ruby 3.1 installs do not resolve `erb >= 6`, which requires Ruby 3.2+.
+## [0.0.37] – 2026-06-11
+### Added
+- Streaming hints for JS codegen
 
 ## [0.0.35] – 2026-06-11
 ### Added

data/README.md

@@ -93,11 +93,82 @@ 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`).
 
+## Composing Schemas
+
+Schemas can import other schemas — and the compiler **inlines everything at compile time**. The generated code has no runtime dependency on the imported module; imported logic participates in broadcasting and loop fusion like any locally written expression.
+
+```ruby
+module TaxPolicy
+  extend Kumi::Schema
+
+  schema do
+    input { decimal :amount }
+    value :tax, input.amount * 0.15
+  end
+end
+
+module Order
+  extend Kumi::Schema
+
+  schema do
+    import :tax, from: TaxPolicy
+
+    input do
+      array :items do
+        hash :item do
+          decimal :price
+        end
+      end
+    end
+
+    # TaxPolicy only knows a scalar :amount — passing a vectorized
+    # argument applies it per item automatically.
+    value :item_taxes, fn(:tax, amount: input.items.item.price)
+    value :total_tax, fn(:sum, item_taxes)
+  end
+end
+
+Order.from(items: [{ price: 100 }, { price: 200 }, { price: 300 }])[:total_tax]
+# => 90.0
+```
+
+The generated JavaScript for `total_tax` shows what "inline everything" means — the imported tax rule **and** the `sum` reduction are fused into one loop, with no call to `TaxPolicy`, no intermediate array, and no runtime to ship:
+
+```js
+export function _total_tax(input) {
+  let t13 = input["items"];
+  let acc18 = 0.0;
+  for (let items_i15 = 0; items_i15 < t13.length; items_i15++) {
+    let items_el14 = t13[items_i15];
+    let t16 = items_el14["price"];
+    let t17 = 0.15;
+    let t12 = t16 * t17;
+    acc18 += t12;
+  }
+  let t6 = acc18;
+  return t6;
+}
+```
+
+See [Schema Imports](docs/SCHEMA_IMPORTS.md) for renamed inputs, multiple imports, and imports over nested arrays.
+
+## Performance
+
+Compiled schemas are straight-line code with fused loops — there is no interpreter, rule engine, or library call in the artifact, so the runtime cost is whatever the host language charges for a `for` loop.
+
+Two playground examples make this tangible:
+
+- **[Payroll at Scale](https://kumi-play-web.fly.dev/?example=payroll-at-scale)** — a full payroll run (overtime split, progressive withholding bands, ten aggregates) over **10,000 employees in ~0.2 ms per call** in desktop Chrome. Press **Benchmark ×100** in the Execute tab to measure median / p95 on your own machine.
+- **[Game of Life XL](https://kumi-play-web.fly.dev/?example=life-xl)** — Conway's rules over an **83,000-cell grid**, stepping live in a worker with the nine neighbor reads fused into a single pass — millions of cell updates per second, rendered in real time with a live counter.
+
 ## 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).
+- **Payroll at Scale** — overtime, withholding bands, and aggregates over 10,000 employees with per-run timing. [Open in the demo](https://kumi-play-web.fly.dev/?example=payroll-at-scale).
 - **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).
+- **Conway's Game of Life** — array operations powering a grid-based simulation ([XL version](https://kumi-play-web.fly.dev/?example=life-xl) runs 83k cells live). [Open in the demo](https://kumi-play-web.fly.dev/?example=game-of-life).
+
+The playground's example picker groups these by theme (language tour, business logic, scale & speed, simulations) — the [Language Intro](https://kumi-play-web.fly.dev/?example=language-intro) is the best starting point.
 
 ---
 

data/docs/SYNTAX.md

@@ -5,6 +5,9 @@
 ### File Structure
 ```kumi
 schema do
+  # Optional schema-level generation hints
+  codegen streaming: true
+
   input do
     # Input shape declarations
   end
@@ -30,6 +33,21 @@ value :name, expr    # Output value
 trait :name, expr    # Boolean mask
 ```
 
+### Codegen Hints
+```kumi
+schema do
+  codegen streaming: true
+
+  input do
+    # ...
+  end
+
+  value :next_state, ...
+end
+```
+
+`codegen streaming: true` keeps normal JavaScript exports and adds `_name_stream(input, target = {})` exports for each output. For direct array outputs, pass an array target to reuse it in-place, or pass an object target to receive `target["name"]`.
+
 ### Operators
 
 **Arithmetic:** `+` `-` `*` `/` `**` `%`

data/lib/kumi/core/analyzer/passes/codegen/loop/js/emitter.rb

@@ -16,11 +16,12 @@ module Kumi
                   @indent = 0
                 end
 
-                def emit(loop_module, schema_digest: nil)
+                def emit(loop_module, schema_digest: nil, streaming: false)
                   reset!
 
                   loop_module.each_function do |fn|
                     emit_function(fn)
+                    emit_streaming_function(fn) if streaming
                   end
 
                   to_s
@@ -38,15 +39,42 @@ module Kumi
                 def emit_function(fn)
                   write "export function _#{fn.name}(input) {"
                   indented do
-                    fn.entry_block.instructions.each do |instr|
-                      emit_instruction(instr)
+                    emit_instructions(fn)
+                    write "return #{reg(fn.return_reg)};"
+                  end
+                  write "}\n"
+                end
+
+                def emit_streaming_function(fn)
+                  write "export function _#{fn.name}_stream(input, target = {}) {"
+                  indented do
+                    return_array_reg = direct_return_array_reg(fn)
+                    if return_array_reg
+                      write "let __streamTarget = Array.isArray(target) ? target : target[\"#{fn.name}\"];"
+                      write "if (!Array.isArray(__streamTarget)) {"
+                      indented do
+                        write "__streamTarget = [];"
+                        write "if (target && typeof target === \"object\" && !Array.isArray(target)) target[\"#{fn.name}\"] = __streamTarget;"
+                      end
+                      write "} else {"
+                      indented { write "__streamTarget.length = 0;" }
+                      write "}"
                     end
+
+                    emit_instructions(fn, stream_return_array_reg: return_array_reg)
+                    write "if (target && typeof target === \"object\" && !Array.isArray(target)) target[\"#{fn.name}\"] = #{reg(fn.return_reg)};"
                     write "return #{reg(fn.return_reg)};"
                   end
                   write "}\n"
                 end
 
-                def emit_instruction(instr)
+                def emit_instructions(fn, stream_return_array_reg: nil)
+                  fn.entry_block.instructions.each do |instr|
+                    emit_instruction(instr, stream_return_array_reg: stream_return_array_reg)
+                  end
+                end
+
+                def emit_instruction(instr, stream_return_array_reg: nil)
                   case instr.opcode
                   when :constant
                     write "let #{reg(instr.result)} = #{format_literal(instr.attributes[:value])};"
@@ -79,7 +107,11 @@ module Kumi
                     @indent -= 1
                     write "}"
                   when :array_init
-                    write "let #{reg(instr.result)} = [];"
+                    if stream_return_array_reg == instr.result
+                      write "let #{reg(instr.result)} = __streamTarget;"
+                    else
+                      write "let #{reg(instr.result)} = [];"
+                    end
                   when :array_push
                     write "#{reg(instr.inputs[0])}.push(#{reg(instr.inputs[1])});"
                   when :array_len
@@ -106,6 +138,12 @@ module Kumi
                   end
                 end
 
+                def direct_return_array_reg(fn)
+                  fn.entry_block.instructions.any? do |instr|
+                    instr.opcode == :array_init && instr.result == fn.return_reg
+                  end ? fn.return_reg : nil
+                end
+
                 def emit_shift_read(instr)
                   array, index, length = instr.inputs.map { reg(_1) }
                   out = reg(instr.result)

data/lib/kumi/core/analyzer/passes/codegen/loop_js_pass.rb

@@ -10,9 +10,10 @@ module Kumi
               loop_module = get_state(:loop_module, required: true)
               registry = get_state(:registry, required: true)
               schema_digest = get_state(:schema_digest)
+              streaming = schema.hints.dig(:codegen, :streaming) == true
 
               emitter = Codegen::Loop::Js::Emitter.new(registry)
-              src = emitter.emit(loop_module, schema_digest: schema_digest)
+              src = emitter.emit(loop_module, schema_digest: schema_digest, streaming: streaming)
 
               state.with(:javascript_codegen_files, { "codegen.mjs" => src })
             end

data/lib/kumi/core/ruby_parser/build_context.rb

@@ -4,7 +4,7 @@ module Kumi
   module Core
     module RubyParser
       class BuildContext
-        attr_reader :inputs, :values, :traits, :imports, :imported_names
+        attr_reader :inputs, :values, :traits, :imports, :imported_names, :root_hints
         attr_accessor :current_location
 
         def initialize
@@ -13,9 +13,14 @@ module Kumi
           @traits = []
           @imports = []
           @imported_names = Set.new
+          @root_hints = {}
           @input_block_defined = false
         end
 
+        def merge_root_hint(namespace, values)
+          @root_hints[namespace] = (@root_hints[namespace] || {}).merge(values)
+        end
+
         def input_block_defined?
           @input_block_defined
         end

data/lib/kumi/core/ruby_parser/parser.rb

@@ -45,7 +45,7 @@ module Kumi
         end
 
         def build_syntax_tree
-          Root.new(@context.inputs, @context.values, @context.traits, @context.imports)
+          Root.new(@context.inputs, @context.values, @context.traits, @context.imports, hints: @context.root_hints)
         end
 
         def handle_parse_error(error)

data/lib/kumi/core/ruby_parser/schema_builder.rb

@@ -8,7 +8,7 @@ module Kumi
         include Syntax
         include ErrorReporting
 
-        DSL_METHODS = %i[value trait input ref literal fn select shift roll import].freeze
+        DSL_METHODS = %i[value trait input ref literal fn select shift roll import codegen].freeze
 
         def initialize(context)
           @context = context
@@ -72,6 +72,23 @@ module Kumi
           @context.imported_names.merge(names)
         end
 
+        def codegen(**kwargs)
+          update_location
+          unknown = kwargs.keys - %i[streaming]
+          unless unknown.empty?
+            raise_syntax_error(
+              "unknown codegen option(s): #{unknown.map(&:inspect).join(', ')}",
+              location: @context.current_location
+            )
+          end
+
+          if kwargs.key?(:streaming) && ![true, false].include?(kwargs[:streaming])
+            raise_syntax_error("codegen streaming: must be true or false", location: @context.current_location)
+          end
+
+          @context.merge_root_hint(:codegen, kwargs)
+        end
+
         def fn(fn_name, *args, **kwargs)
           update_location
 

data/lib/kumi/syntax/root.rb

@@ -13,7 +13,7 @@ module Kumi
         # The digest must be stable and depend on anything that could change the
         # compiled output. This includes the AST, the Kumi version (compiler changes),
         # and the Ruby version (runtime behavior changes).
-        digest_input = "#{Kumi::VERSION}-#{RUBY_VERSION}-#{self}"
+        digest_input = "#{Kumi::VERSION}-#{RUBY_VERSION}-#{self}-#{hints.inspect}"
 
         # Ruby constants cannot start with a number, so we add a prefix.
         "KUMI_#{Digest::SHA256.hexdigest(digest_input)}"

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.36"
+  VERSION = "0.0.37"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kumi
 version: !ruby/object:Gem::Version
-  version: 0.0.36
+  version: 0.0.37
 platform: ruby
 authors:
 - André Muta