kumi 0.0.25 → 0.0.27

data/docs/SYNTAX.md

@@ -17,6 +17,7 @@ end
 ```kumi
 integer    # Integer numbers
 float      # Floating point numbers
+decimal    # Precise decimal numbers (money, bignum calculations)
 string     # Text strings
 array      # Sequential collections
 hash       # Structured objects
@@ -58,6 +59,12 @@ trait :name, expr    # Boolean mask
 - `fn(:abs, x)` — Absolute value
 - `fn(:clamp, x, lo, hi)` — Clamp to range
 
+**Type Conversion:**
+- `fn(:to_decimal, x)` — Convert to decimal
+- `fn(:to_integer, x)` — Convert to integer
+- `fn(:to_float, x)` — Convert to float
+- `fn(:to_string, x)` — Convert to string
+
 **String:**
 - `fn(:concat, s1, s2)` — Concatenate strings
 - `fn(:upcase, str)` — Convert to uppercase
@@ -140,6 +147,7 @@ Scalar inputs represent single values:
 input do
   integer :x
   float :rate
+  decimal :price        # Precise decimal for money calculations
   string :name
 end
 ```

data/docs/UNSAT_DETECTION.md

@@ -0,0 +1,83 @@
+# UNSAT Detection & Constraint Analysis
+
+Kumi includes static analysis to detect **unsatisfiable constraints**—impossible conditions that can never be true given input domains.
+
+## How It Works
+
+### Direct Contradictions
+Kumi detects when the same variable is constrained to multiple different values:
+
+```ruby
+schema do
+  input { integer :x }
+
+  # ✓ Detected as UNSAT: x cannot be both 5 and 10
+  trait :impossible, fn(:and, input.x == 5, input.x == 10)
+end
+```
+
+### Domain Violations
+Kumi checks when constraints violate input domains:
+
+```ruby
+schema do
+  input { integer :age, domain: 0..150 }
+
+  # ✓ Detected as UNSAT: age can never be 200
+  trait :impossible_age, input.age == 200
+end
+```
+
+### Constraint Propagation (Phase 2)
+Kumi propagates constraints through operations to detect derived impossibilities:
+
+```ruby
+schema do
+  input { integer :x, domain: 0..10 }
+
+  value :doubled, fn(:mul, input.x, 2)  # doubled ∈ [0, 20]
+
+  # ✓ Detected as UNSAT: doubled can never be 50
+  trait :impossible_doubled, doubled == 50
+end
+```
+
+**Reverse propagation** derives input constraints from output constraints:
+
+```ruby
+schema do
+  input { integer :x, domain: 0..10 }
+
+  value :result, fn(:add, input.x, 100)  # result ∈ [100, 110]
+
+  # ✓ Detected as UNSAT: result == 50 would require x == -50 (outside domain)
+  trait :impossible_result, result == 50
+end
+```
+
+## Error Messages
+
+Impossible constraints raise `Kumi::Core::Errors::SemanticError`:
+
+```
+conjunction `impossible_doubled` is impossible
+```
+
+This message appears at schema compilation time, catching bugs before execution.
+
+## When UNSAT Detection Runs
+
+UNSAT detection is performed during the **HIR-to-LIR compilation phase**, after:
+- Function IDs are resolved
+- Type information is inferred
+- Dimensional metadata is computed
+
+This ensures detection has access to complete operation semantics.
+
+## Future Enhancements
+
+- **Multi-level propagation**: Chain constraints through multiple operations
+- **Inequality constraints**: Handle `<`, `>`, `<=`, `>=` constraints
+- **Combined constraints**: Detect contradictions across multiple traits
+
+See `spec/integration/unsat_with_propagation_spec.rb` for examples and pending tests.

data/docs/VSCODE_EXTENSION.md

@@ -0,0 +1,114 @@
+# VSCode Extension for Kumi
+
+The `vscode-extension/` directory contains a VSCode extension that provides IDE support for Kumi functions using the auto-generated function reference.
+
+## What It Does
+
+- **Autocomplete** - Suggest function names when typing `fn(:`
+- **Hover Documentation** - Show function signatures, parameters, and types
+- **Type Information** - Display type inference rules for each function
+- **Arity Display** - Show parameter counts at a glance
+
+## Setup
+
+### 1. Build the Extension
+
+```bash
+cd vscode-extension
+npm install
+npm run compile
+```
+
+This generates JavaScript in `out/extension.js` from the TypeScript sources.
+
+### 2. Install in VSCode
+
+**Option A: Load as Development Extension**
+
+- Open the `vscode-extension` folder in VSCode
+- Press `F5` to launch a debugging session
+- The extension will activate automatically
+
+**Option B: Package as VSIX**
+
+```bash
+npm install -g vsce
+vsce package
+```
+
+Then install the generated `.vsix` file in VSCode via "Extensions: Install from VSIX"
+
+### 3. Generate Function Data
+
+Before using the extension, ensure the function reference JSON is up-to-date:
+
+```bash
+bin/kumi-doc-gen
+```
+
+This creates `docs/functions-reference.json` which the extension reads.
+
+## Usage in VSCode
+
+When editing Ruby files in a Kumi project:
+
+```ruby
+# Start typing fn(: to get suggestions
+fn(:add, x, y)     # ← Autocomplete shows available functions
+   ↑
+   # Hover to see: core.add (arity: 2, type: promoted from left_operand, right_operand)
+
+# Completions include:
+# - add, sub, mul, div, pow (arithmetic)
+# - sum, count, min, max, mean (aggregations)
+# - ... and all other functions
+```
+
+The extension provides:
+- Full function name with backticks for easy identification
+- Arity (parameter count)
+- Type inference rules
+- Parameter names
+- Available kernel implementations
+
+## Data Flow
+
+```
+data/functions/ (YAML)
+      ↓
+bin/kumi-doc-gen
+      ↓
+docs/functions-reference.json
+      ↓
+vscode-extension/src/extension.ts
+      ↓
+VSCode IDE features (autocomplete, hover, etc.)
+```
+
+## Development
+
+To modify the extension:
+
+1. Edit `vscode-extension/src/extension.ts`
+2. Run `npm run watch` to auto-compile TypeScript
+3. Press `F5` in VSCode to reload the debugging session
+4. Test new features against the live extension
+
+## Limitations
+
+Currently the extension:
+- Only provides autocomplete after `fn(:`
+- Only works with Ruby files
+- Doesn't validate argument types at compile time
+- Doesn't provide inline hints during parameter entry
+
+These could be added as future enhancements!
+
+## Future Enhancements
+
+- Parameter validation (type checking)
+- Signature help (inline parameter hints)
+- Go-to-definition for function implementations
+- Diagnostics for arity mismatches
+- Snippet expansion for common patterns
+- LSP server for language-agnostic support