kumi 0.0.25 → 0.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d0a680258ba7c40a2f00d9af8d4abf116344071ddc61d8b587a9a5a49eed6c9
-  data.tar.gz: e16a0a52944cfa45d0a2f15c82fbbaac07392d4a1060f490b4c2fa67cb11208b
+  metadata.gz: a850b47be185d9e65a5b86121f6208b80eac6eba1f8a4bc78879893304cd02ea
+  data.tar.gz: f8a14f4516963be8c6ff8e4b9839189ead2ee134f790ea46f8945e2be6b06876
 SHA512:
-  metadata.gz: 6002d0e6a6b86c345226d630f09279b8e24c5ab581c1d6dba1c3f76b70f91e5ce0a9e2200ee402d12e0b43b593d326cf314ce19b5dafdd7249c36d467ce99a4e
-  data.tar.gz: d58b16b88031e3c9ed75598f71e999657f3e6f23b8f0b9e2fe211c74f8f43d1aa43ff5125f6faef7c713cdb1fac5edd7e59e0aaf29405aafe7123708d352ee36
+  metadata.gz: 2f4e71671cf52c9fbbdede6da6d401f44c4e55a6562fdda0b5d866f11d284a1a2645138e8f469d21fe0f7ab3546e5509348b6223f08d914a60a133b21ca9f57b
+  data.tar.gz: 7fa1e8c26b801ce265310f4dc8837ec7ec7f4218798d10360c4ab707f856ef8bb833c80f04cd08f52e1590df502c1d54fa44f270db384e7269abbda79de3eeec

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.0.27] – 2025-10-20
+### Added
+- Decimal type system for precise money/bignum calculations
+- Conversion functions (to_decimal, to_integer, to_float, to_string)
+- Automatic documentation generation system for IDE support
+- VSCode extension with schema block detection
+
+## [0.0.26] – 2025-10-17
+### Added
+- UNSAT detection via constraint propagation through operations
+- Documentation for UNSAT detection in `docs/UNSAT_DETECTION.md`
+
+### Changed
+- Moved `UnsatDetector` to work over SNAST for full resolution context (axes/types)
+- Refactored Typing system, added proper typing metadata on data/functions
+
 ## [0.0.25] – 2025-10-17
 ### Fixed
 - Fix inlining bug caused by previous fix

data/CLAUDE.md

@@ -25,6 +25,10 @@ Axes align by identity (lineage), not by name
 `bin/kumi golden verify [name]` - Verify current vs expected
 `bin/kumi golden diff <name>` - Show diffs when verification fails
 
+# Documentation Generation
+`bin/kumi-doc-gen` - Generate IDE-friendly JSON + Markdown docs from function/kernel definitions
+See docs/DEVELOPMENT.md for details
+
 # Kernels Invariants
 All reducers are pure binary combiner f : T × T → T applied over the last axis of a value. Example: agg.sum(a,b) = a+b.
 

data/README.md

@@ -7,103 +7,98 @@
 
 ---
 
-**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
-
-**Feedback**: have a use case or a paper cut? Open an issue or reach out.
+**Declarative, typed, vectorized calculation DSL (Ruby-embedded) that builds a deterministic dependency graph.**  
+Normalized, typed **AST → IR → LIR**. Static checks and **constraint UNSAT** at compile time. Codegen is thin.
 
 ---
 
+**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
 
-**Declarative calculation DSL for Ruby.** Write business rules once, run them anywhere.
-
-Kumi compiles high-level schemas into standalone Ruby and JavaScript with no runtime dependencies.
-
-**Built for:** finance, tax, pricing, insurance, payroll, analytics—domains where correctness and transparency matter.
+**Feedback**: have a use case or a paper cut? Open an issue or reach out.
 
 ---
 
-## Example: Conway's Game of Life
+## Example: US Tax Calculator (2024)
 
+See the [interactive demo](https://kumi-play-web.fly.dev/) or browse the [golden test files](golden/us_tax_2024/) (schema, input, expected output, generated code).
 
 <details>
 <summary><strong>Schema</strong></summary>
 
 ```ruby
-module GameOfLife
-  extend Kumi::Schema
-
-  schema do
-    input do
-      array :rows do
-        array :col do
-          integer :alive # 0 or 1
+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
-
-    let :a, input.rows.col.alive
-
-    # axis_offset: 0 = x, 1 = y
-    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)
-
-    let :neighbors, fn(:sum, [n, s, w, e, nw, ne, sw, se])
-
-    # Conway rules
-    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
 
+  # 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>
-
-
-<details>
-<summary><strong>Generated JavaScript (excerpt)</strong></summary>
-
-```js
-export function _next_state(input) {
-  let out = [];
-  let t285 = input["rows"];
-  let t1539 = t285.length;
-  const t1540 = -1;
-  const t1542 = 0;
-  const t1546 = 1;
-  const t1334 = 3;
-  const t1339 = 2;
-  let t1547 = t1539 - t1546;
-  t285.forEach((rows_el_286, rows_i_287) => {
-    let out_1 = [];
-    let t1541 = rows_i_287 - t1540;
-    let t1561 = rows_i_287 - t1546;
-    let t1580 = ((rows_i_287 % t1539) + t1539) % t1539;
-    // ... neighbor calculations, Conway's rules
-    let t1332 = [t1557, t1577, t1597, t1617, t1645, t1673, t1701, t1729];
-    let t1333 = t1332.reduce((a, b) => a + b, 0);
-    let t1335 = t1333 == t1334;
-    let t1340 = t1333 == t1339;
-    let t1344 = col_el_288 > t1542;
-    let t1345 = t1340 && t1344;
-    let t528 = t1335 || t1345;
-    let t293 = t528 ? t1546 : t1542;
-    out_1.push(t293);
-  });
-  return out;
-}
 ```
 
 </details>
@@ -146,6 +141,19 @@ Double.write_source("output.mjs", platform: :javascript)
 
 ---
 
+## Documentation
+
+Auto-generated reference for all functions and kernels:
+
+- **[Functions Reference](docs/FUNCTIONS.md)** - Human-readable docs with parameters and kernels
+- **[functions-reference.json](docs/functions-reference.json)** - Machine-readable format for IDEs (VSCode, Monaco, etc.)
+
+To regenerate: `bin/kumi-doc-gen`
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for development workflows.
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE).

data/data/functions/agg/boolean.yaml

@@ -2,13 +2,17 @@ functions:
   - id: agg.any
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "boolean"
+    dtype:
+      rule: scalar
+      kind: boolean
     aliases: ["any", "any?"]
     folding_class_method: any?
 
   - id: agg.all
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "boolean"
+    dtype:
+      rule: scalar
+      kind: boolean
     aliases: ["all", "all?"]
     folding_class_method: all?

data/data/functions/agg/numeric.yaml

@@ -2,65 +2,79 @@ functions:
   - id: agg.sum
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "same_as(source_value)"
+    dtype:
+      rule: same_as
+      param: source_value
     reduction_strategy: identity # This function has a true identity value.
     aliases: ["sum"]
-    
+
   - id: agg.count
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "integer"
+    dtype:
+      rule: scalar
+      kind: integer
     reduction_strategy: identity # This function has a true identity value.
     aliases: ["count"]
 
   - id: agg.min
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "element_of(source_value)"
+    dtype:
+      rule: element_of
+      param: source_value
     reduction_strategy: first_element
     aliases: ["min"]
 
   - id: agg.max
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "element_of(source_value)"
+    dtype:
+      rule: element_of
+      param: source_value
     reduction_strategy: first_element
     aliases: ["max"]
-  
+
   - id: agg.mean
     kind: reduce
     params: [{ name: source_value }]
-    dtype: "float"
+    dtype:
+      rule: scalar
+      kind: float
     aliases: ["mean", "avg"]
     expand:
       fn: div
       args:
         - fn: sum
-          args: [ "$1" ] # $1 is source_value
+          args: ["$1"] # $1 is source_value
         - fn: count
-          args: [ "$1" ]
+          args: ["$1"]
 
   - id: agg.sum_if
     kind: reduce
     params: [{ name: source_value }, { name: condition }]
-    dtype: "same_as(source_value)"
+    dtype:
+      rule: same_as
+      param: source_value
     aliases: ["sum_if"]
     expand:
       fn: sum
       args:
         - fn: __select__
-          args: [ "$2", "$1", { const: 0 } ] # $1=source_value, $2=condition
+          args: ["$2", "$1", { const: 0 }] # $1=source_value, $2=condition
 
   - id: agg.count_if
     kind: reduce
     params: [{ name: condition }, { name: source_value }]
-    dtype: "integer"
+    dtype:
+      rule: scalar
+      kind: integer
     aliases: ["count_if"]
     expand:
       fn: sum # Summing 1s and 0s is equivalent to a conditional count
       args:
         - fn: __select__
-          args: 
+          args:
             - fn: eq
               args: ["$1", "$2"]
             - { const: 1 }
@@ -69,12 +83,14 @@ functions:
   - id: agg.mean_if
     kind: reduce
     params: [{ name: source_value }, { name: condition }]
-    dtype: "float"
+    dtype:
+      rule: scalar
+      kind: float
     aliases: ["avg_if", "mean_if"]
     expand:
       fn: div
       args:
         - fn: sum_if
-          args: [ "$1", "$2" ] # Sum the values where the condition is true
+          args: ["$1", "$2"] # Sum the values where the condition is true
         - fn: count_if
-          args: [ "$1", "$2" ] # Count the values where the condition is true
+          args: ["$1", "$2"] # Count the values where the condition is true

data/data/functions/agg/string.yaml

@@ -2,7 +2,8 @@ functions:
   - id: agg.join
     kind: reduce
     params: [{ name: source_value, dtype: string }]
-    dtype: "string"
+    dtype:
+      rule: scalar
+      kind: string
     reduction_strategy: first_element
-    aliases: ["join"]
-    
+    aliases: ["join"]

data/data/functions/core/arithmetic.yaml

@@ -2,49 +2,97 @@ functions:
   - id: core.abs
     kind: elementwise
     params: [{ name: number }]
-    dtype: "same_as(number)"
+    dtype:
+      rule: same_as
+      param: number
     aliases: ["abs"]
 
   - id: core.add
-    kind: elementwise  
+    kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "promote(left_operand,right_operand)"
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
     aliases: ["add"]
+    constraint_semantics:
+      domain_effect: EXTEND
+      pure_combiner: true
+      commutativity: true
+      associativity: true
+      identity: 0
+      forward_propagation:
+        # If we know left == L and right == R, then result == L + R
+        equality: "result = left + right"
+        # If result is in [a, b] and left/right in domains, derive tighter bounds
+        range: "result_min = left_min + right_min; result_max = left_max + right_max"
+      reverse_propagation:
+        # If result == V, then left == V - right
+        equality: "left = result - right; right = result - left"
+        # If result in [a, b] and left in [l1, l2], then right in [a - l2, b - l1]
+        range: "left_min = result_min - right_max; left_max = result_max - right_min; right_min = result_min - left_max; right_max = result_max - left_min"
 
   - id: core.sub
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }] 
-    dtype: "promote(left_operand,right_operand)"
+    params: [{ name: left_operand }, { name: right_operand }]
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
     aliases: ["sub", "subtract"]
 
   - id: core.mul
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "promote(left_operand,right_operand)"
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
     aliases: ["mul", "multiply"]
+    constraint_semantics:
+      domain_effect: SCALE
+      pure_combiner: true
+      commutativity: true
+      associativity: true
+      identity: 1
+      forward_propagation:
+        # If we know left == L and right == R, then result == L * R
+        equality: "result = left * right"
+        # For multiplication: result bounds depend on sign of operands
+        range: "result = combinations of {left_min*right_min, left_min*right_max, left_max*right_min, left_max*right_max} -> [min, max]"
+      reverse_propagation:
+        # If result == V and right != 0, then left == V / right
+        equality: "left = result / right (if right != 0); right = result / left (if left != 0)"
+        # For multiplication: divide by absolute values considering sign changes
+        range: "derive from result bounds and operand bounds considering sign combinations"
 
   - id: core.pow
     kind: elementwise
     params: [{ name: base }, { name: exponent }]
-    dtype: "promote(base,exponent)"
+    dtype:
+      rule: promote
+      params: [base, exponent]
     aliases: ["pow", "power"]
 
   - id: core.div
-    kind: elementwise  
+    kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "float"
+    dtype:
+      rule: scalar
+      kind: float
     aliases: ["div", "divide"]
 
   - id: core.mod
     kind: elementwise
     params:
-      - { name: left_operand}
-      - { name: right_operand}
-    dtype: "promote(left_operand,right_operand)"
+      - { name: left_operand }
+      - { name: right_operand }
+    dtype:
+      rule: promote
+      params: [left_operand, right_operand]
     aliases: ["mod", "modulo", "%"]
 
   - id: core.clamp
     kind: elementwise
-    params: [{name: x},{name: lo},{name: hi}]
-    dtype: "same_as(x)"
+    params: [{ name: x }, { name: lo }, { name: hi }]
+    dtype:
+      rule: same_as
+      param: x
     aliases: ["clamp"]

data/data/functions/core/boolean.yaml

@@ -2,17 +2,23 @@ functions:
   - id: core.and
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["and", "&"]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["and", "&"]
 
   - id: core.or
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["or", "|"]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["or", "|"]
 
   - id: core.not
     kind: elementwise
     params: [{ name: operand }]
-    dtype: "boolean"
-    aliases : ["not", "!"]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["not", "!"]

data/data/functions/core/comparison.yaml

@@ -2,41 +2,53 @@ functions:
   - id: core.gte
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["gte", "ge", "greater_than_or_equal", ">="]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["gte", "ge", "greater_than_or_equal", ">="]
     folding_class_method: gte
 
   - id: core.gt
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["gt", "greater_than", ">"]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["gt", "greater_than", ">"]
     folding_class_method: gt
 
   - id: core.lte
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["lte", "le", "less_than_or_equal", "<="]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["lte", "le", "less_than_or_equal", "<="]
     folding_class_method: lte
 
   - id: core.lt
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["lt", "less_than", "<"]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["lt", "less_than", "<"]
     folding_class_method: lt
 
   - id: core.eq
-    kind: elementwise  
+    kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["eq", "equal", "=="]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["eq", "equal", "=="]
     folding_class_method: eq
 
   - id: core.neq
     kind: elementwise
     params: [{ name: left_operand }, { name: right_operand }]
-    dtype: "boolean"
-    aliases : ["neq", "not_equal", "!="]
+    dtype:
+      rule: scalar
+      kind: boolean
+    aliases: ["neq", "not_equal", "!="]
     folding_class_method: neq

data/data/functions/core/constructor.yaml

@@ -1,32 +1,40 @@
 functions:
-# length is probably in the wrong place 
+  # length is probably in the wrong place
   - id: core.length
     kind: elementwise
     params: [{ name: collection, dtype: string }]
-    dtype: "integer"
+    dtype:
+      rule: scalar
+      kind: integer
     aliases: ["length", "len", "size"]
     folding_class_method: length
 
   - id: core.array_size
     kind: elementwise
     params: [{ name: collection, dtype: array }]
-    dtype: "integer"
-    aliases: ["array_size","size"]
+    dtype:
+      rule: scalar
+      kind: integer
+    aliases: ["array_size", "size"]
     folding_class_method: length
 
   - id: core.at
     kind: elementwise
-    params: 
+    params:
       - { name: collection }
       - { name: index, dtype: integer }
-    dtype: "element_of(collection)"
+    dtype:
+      rule: element_of
+      param: collection
     aliases: ["at", "get", "[]"]
     folding_class_method: at
 
   - id: core.hash_fetch
     kind: elementwise
-    params: 
+    params:
       - { name: key, dtype: hash }
-    dtype: "value_of(key)" # TODO, we can calculate,
+    dtype:
+      rule: scalar
+      kind: any
     aliases: ["fetch"]
     folding_class_method: "[]"

data/data/functions/core/conversion.yaml

@@ -0,0 +1,32 @@
+functions:
+  - id: core.to_decimal
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: decimal
+    aliases: ["to_decimal"]
+
+  - id: core.to_integer
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: integer
+    aliases: ["to_integer", "to_int"]
+
+  - id: core.to_float
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: float
+    aliases: ["to_float"]
+
+  - id: core.to_string
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: string
+    aliases: ["to_string", "to_str"]