@fraczak/k 6.8.0 → 6.10.1

package/DOCS/REPL.md

@@ -33,20 +33,18 @@ complete.
 | Command | Meaning |
 | --- | --- |
 | `:help` | Show command summary |
+| `:engine [wasm\|js]` | Display or switch evaluation engine (`wasm` or `js`) |
+| `:wasm` / `:js` | Shortcut to switch engine |
+| `:rel name` | Show relation definition |
 | `:type name` | Show the canonical definition of a type |
+| `:types` | List type aliases |
+| `:rels` | List relation aliases |
 | `:code name` | Alias for `:C name` |
-| `:run expr` | Evaluate `expr` on the current value |
-| `:eval expr` | Alias for `:run` |
-| `:time expr` | Evaluate `expr` and report compilation and execution time |
-| `:t name` | Show relation input/output filters |
-| `:d name` | Show relation definition |
 | `:C name` | Show canonical code definition |
-| `:codes` | List type aliases |
-| `:rels` | List relation aliases |
-| `:codec load name\|file` | Load a built-in codec (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file |
+| `:codec load file` | Load a codec from an ES module file (e.g. `:codec load codecs/int.mjs`) |
 | `:codec unload name` | Unload a registered codec |
 | `:codec list` | List loaded REPL codecs (alias: `:codecs`) |
-| `:input [<filter=(...)> [codec]]` | Read next input line using specified codec (opens dialog in browser) |
+| `:input <codec.mjs> [text]` | Read next input line or parse inline text using specified codec |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
 | `:klib file` | Export the active relation closure as a `.klib` library |
 | `:ko file expr` | Export a `.ko` executable with `expr` as main |
@@ -136,9 +134,8 @@ Tab completion covers:
 
 Type aliases also complete in `$name` position inside raw k input.
 
-For codec commands, completion covers `:codec load`, `:codec list`, file paths
-after `:codec load`, type names or codec names after `:input`, and loaded codec names
-after the input pattern or type.
+For codec commands, completion covers `:codec load`, `:codec unload`, `:codec list`,
+file paths after `:codec load`, and codec names after `:input`.
 
 ## Loading
 
@@ -156,71 +153,92 @@ unless `--no-alias` is used.
 
 ## Codecs
 
-REPL codecs are usually keyed by canonical code hashes. Patterns are not used
-for codec dispatch. A codec may also export `universal = true` to make it
-available for any type selected by `:input`; the parsed value is still validated
-against the requested type before it enters the session.
+A codec is a recipe for translating between external text and enveloped *k* values:
+- `parse(text)`: parses an external string into an enveloped *k* value.
+- `print(value)`: serializes an enveloped *k* value to external string, throwing an `Error` if the value is not representable.
+
+Codecs can define a family of target patterns (e.g. `int` parses/prints single integers as well as lists like `[0,1,2]`).
+
+For printing in the REPL, every value is printed with the standard *k* envelope representation, followed by lines for all loaded codecs that can format it:
+```text
+> 42 int
+{}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+int: 42
+```
 
 For a complete guide to writing a new codec module, see
 [`CODECS.md`](./CODECS.md).
 
-### `:codec load name|file`
+### `:codec load file`
 
-Loads either a built-in codec by name (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file. Loading a built-in codec automatically loads its corresponding `.k` definition file if not already present:
-- `int` auto-loads `Examples/arithmetics.k`
-- `ieee` auto-loads `Examples/ieee.k`
-- `utf8`, `json`, `unit` auto-load `Examples/core.k`
+Loads a codec module from an ES module file (e.g. `:codec load codecs/int.mjs`). Codecs are identified by their file name, and export `parse(text)` and `print(value)` functions.
 
-Loading a codec also creates code aliases matching the codec name (e.g. `$ int = @...`, `$ float64 = @...`, `$ utf8 = @...`).
+### `:codec unload name`
 
-An external codec module exports:
+Unloads a previously loaded codec by name (e.g. `:codec unload int.mjs`).
 
-```js
-export const name = "utf8";
-export const codes = ["@..."];
-export function parse(text) { /* text -> Value */ }
-export function print(value) { /* Value -> text */ }
-```
+### `:codec list` (or `:codecs`)
 
-A codec may export `patterns` instead of `codes`; each pattern must be a closed
-property-list pattern that can be canonicalized to a code hash, and that hash is
-recalculated by the REPL. A universal codec exports `universal = true` instead
-of `codes` or `patterns`.
+Lists all currently loaded codecs and their source files.
 
+### `:input <codec.mjs> [text]`
 
-### `:codec unload name`
+Parses external input using the specified codec file.
+
+- **Interactive mode**: `:input <codec.mjs>` switches the REPL prompt to `<codec.mjs>> `, and the next input line is parsed using that codec:
+  ```text
+  > :input json.mjs
+  json.mjs> {"hello": "world"}
+  {...} ?<{...}>
+  json.mjs: {"hello":"world"}
+  ```
 
-Unloads a previously registered codec by name.
+- **One-line mode**: `:input <codec.mjs> <text>` immediately parses `<text>`:
+  ```text
+  > :input int.mjs 42
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
 
-### `:input [<filter=(...)> [codec]]`
+  > :input int.mjs [0,1,2]
+  {...} ?<{...}>
+  int.mjs: [0,1,2]
+  ```
 
-Resolves a pattern expression (e.g. `? {string a, float64 n}`, `? (...)`, `? <{} true, {} false>`), a type alias, or a canonical code hash, selects the registered codec, and consumes the next line verbatim as codec input.
+Entering `:input` with no arguments displays usage and a list of loaded codecs.
 
-If only a universal codec is specified (e.g. `:input json`), no pre-declared type or pattern is required; input is parsed directly and derives its pattern from the input payload.
+## Evaluation Engines: WASM and JS
 
-When a pattern expression or type is provided, the parsed value is validated and constrained against that pattern before becoming the current value:
+The REPL supports two evaluation engines:
 
-```text
-> :input ? {string a, float64 n} json
-input ? {string a, float64 n} using json: enter value text
-json> {"a": "Woj", "n": 123}
+- **`wasm`** (default): Compiles k expressions into WebAssembly bytecode via polymorphic kVM lowering. Provides near-native execution speed, tail-call optimization (TCO), and stack safety on deep recursion.
+- **`js`**: The tree-walking JavaScript interpreter. Provides near-zero compilation latency (interprets parsed definitions directly) and convenient runtime inspection.
+
+### Engine Commands
+
+- `:engine` &mdash; displays active engine (`wasm` or `js`)
+- `:engine wasm` (or `:wasm`) &mdash; switches to the WebAssembly engine
+- `:engine js` (or `:js`) &mdash; switches to the JavaScript engine
+
+### CLI Options
+
+When starting `k-repl`, choose the engine with:
+
+```bash
+k-repl --engine=js    # or k-repl --js
+k-repl --engine=wasm  # or k-repl --wasm (default)
 ```
 
 ## Timing and Profiling
 
 Timing reporting is enabled by default for all evaluations, reporting elapsed time
-broken down into compilation (type derivation + WebAssembly lowering/compilation) and runtime execution:
+broken down into compilation and runtime execution, annotated with the active engine:
 
 ```text
 > {10 int x, 5 int y} plus
 {}|_|1|1|1|1|+ ?<{} _, ...>
-/* comp: 12.4ms, exec: 0.8ms */
+/* comp: 12.4ms, exec: 0.8ms (wasm) */
 ```
 
-### `:time expr`
-
-Evaluates `expr` with explicit timing and records performance metrics in session state.
-
 ## Web REPL (Studio)
 
 The repository provides a standalone, single-file browser REPL: `repl.html`.
@@ -272,8 +290,8 @@ Evaluated values print in k syntax together with the inferred envelope:
 > inc = | +1;
 > {} | 0
 {}|0 ?<{} 0, ...>
-> :t inc
-inc : ?X0  -->  ?<X0 +1, ...>  (@...)
+> :rel inc
+inc = | +1;  -- @...
 > :klib nat.klib
 saved nat.klib
 > :ko inc.ko inc

package/Examples/arithmetics.k

@@ -92,6 +92,7 @@ _fromBitList =
 
 --------------------------------------
 $ int = < bits '+', bits '-' >;
+$ ints = <{int car, ints cdr} cons, {} nil>;
 
 remove_leading_zeros = <
   /0 remove_leading_zeros, 

package/Examples/poly.k

@@ -65,3 +65,49 @@ zip = <
     {.xs cdr xs, .ys cdr ys} zip cdr
   } cons
 >;
+
+-- Gen list of intgers: n -> [0, 1, ..., n]
+gen_list = {() n, nil list} gen_list_; 
+gen_list_ = <
+  {.n neg? if, .list then} .then, 
+  {.n dec n, {.n car, .list cdr} cons list} gen_list_
+>;
+
+-- Identity filter on {x, y} when x is greater than y: ?{X x, X y}=Y -> ?Y
+gt? =
+  <
+    {.x/- if1, .y/+ if2, () then} .then,
+    {{.x/- y, .y/- x} GT if, () then} .then,
+    {{.x/+ x, .y/+ y} GT if, () then} .then
+  >
+;
+
+-- Split list into two halves by alternating elements: xs -> {first, second}
+split = {() xs, nil first, nil second} _split;
+_split = <
+  {.xs /nil if, {.first first, .second second} then} .then,
+  {.xs cdr /nil if, {{.xs car car, .first cdr} cons first, .second second} then} .then,
+  {.xs cdr cdr xs, {.xs car car, .first cdr} cons first, {.xs cdr car car, .second cdr} cons second} _split
+>;
+
+-- Merge two sorted lists: {xs, ys} -> list
+merge = <
+  {.xs /nil if, .ys then} .then,
+  {.ys /nil if, .xs then} .then,
+  {
+    {.xs car x, .ys car y} gt? if,
+    {.ys car car, {.xs xs, .ys cdr ys} merge cdr} cons then
+  } .then,
+  {.xs car car, {.xs cdr xs, .ys ys} merge cdr} cons
+>;
+
+-- Sort a list in ascending order (merge sort): xs -> list
+sort = list? <
+  /nil nil,
+  /cons <
+    {.cdr /nil if, .car singleton then} .then,
+    |cons split {.first sort xs, .second sort ys} merge
+  >
+> list?;
+
+

package/backends/llvm/runtime/krt.c

@@ -563,6 +563,7 @@ k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr) {
 
   if (!is_after_mark(rt, root, *mark_ptr)) {
     rt_rewind_and_free(rt, *mark_ptr);
+    *mark_ptr = k_rt_mark(rt);
     return root;
   }
 
@@ -580,6 +581,7 @@ k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr) {
   if (staging_used == 0) {
     free(staging);
     if (fixups.offsets != NULL) free(fixups.offsets);
+    *mark_ptr = k_rt_mark(rt);
     return staged_root;
   }
 
@@ -603,6 +605,8 @@ k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr) {
   free(staging);
   if (fixups.offsets != NULL) free(fixups.offsets);
 
+  *mark_ptr = k_rt_mark(rt);
+
   return new_root;
 }
 

package/backends/llvm/src/kvm2llvm.mjs

@@ -438,7 +438,7 @@ function hasSelfTailCall(insts, funcName, isTail = true) {
   for (let i = 0; i < insts.length; i++) {
     const inst = insts[i];
     if (isTail && isSelfTailCall(insts, i, funcName)) return true;
-    if (inst.branches) {
+    if (inst.op === "union" && inst.branches) {
       const unionIsTail = isTail && tailValueAfter(insts, i + 1, inst.dest);
       for (let bIdx = 0; bIdx < inst.branches.length; bIdx++) {
         if (hasSelfTailCall(inst.branches[bIdx].body, funcName, unionIsTail)) return true;
@@ -721,7 +721,7 @@ function lowerKVMFunction(kvmFunc, symbol, funcName, moduleCtx, linkage = "", op
         }
         case "call": {
           const v = getReg(inst.src);
-          if (isSelfTailCall(insts, i, tailRef)) {
+          if (isTopLevel && !returnTarget && isSelfTailCall(insts, i, tailRef)) {
             if (ctx.catchTail) {
               const compacted = lowerRtCompact(ctx, v, "%tail_mark_slot");
               ctx.lines.push(`  store ptr ${compacted}, ptr %tail_input_slot`);

package/backends/llvm/tests/test-llvm.mjs

@@ -237,4 +237,23 @@ assert.match(nestedUnionLLVM, /store ptr %union_value\d+, ptr %ptr_slot\d+/);
 assert.doesNotMatch(nestedUnionLLVM, /call void @k_product_set_at\(ptr %product\d+/);
 assert.doesNotMatch(nestedUnionLLVM, /ptr false/);
 
+const productRecurseObject = decodeObject(compileObjectBuffer(`
+  $ list = < {} nil, { {} car, list cdr } cons >;
+  foo = $list <
+    /nil |nil,
+    /cons { .car car, .cdr foo cdr } |cons
+  > $list;
+  foo
+`, { source: "llvm-product-recurse.k" }));
+const { llvm: productRecurseLLVM } = compileObjectToLLVM(productRecurseObject, {
+  relation: "foo",
+  inputPattern: [
+    ["closed-union", [["nil", 1], ["cons", 2]]],
+    ["closed-product", []],
+    ["closed-product", [["car", 1], ["cdr", 0]]]
+  ]
+});
+// Calls inside product fields must not return tail status (i32 2)
+assert.doesNotMatch(productRecurseLLVM, /insertvalue %k_result undef, i32 2, 0/);
+
 console.log("OK");

package/backends/wasm/src/kvm2wasm.mjs

@@ -397,6 +397,8 @@ export function lowerToWasm(relDef, name, options = {}) {
             }
             lines.push(`      local.get $tail_loop_mark`);
             lines.push(`      call $compact_finish`);
+            lines.push(`      global.get $arena_free`);
+            lines.push(`      local.set $tail_loop_mark`);
             lines.push(`    end`);
             for (let i = 0; i < N; i++) {
               const branch = sortedBranches[i];
@@ -598,6 +600,8 @@ export function lowerToWasm(relDef, name, options = {}) {
             lines.push(`      local.set $${callSrc}`);
             lines.push(`      local.get $tail_loop_mark`);
             lines.push(`      call $compact_finish`);
+            lines.push(`      global.get $arena_free`);
+            lines.push(`      local.set $tail_loop_mark`);
             lines.push(`    end`);
             lines.push(`    local.get $${callSrc}`);
             lines.push(`    local.set $in`);

package/backends/wasm/tests/test-wasm.mjs

@@ -619,6 +619,10 @@ console.log("==> Running End-to-End Peano Addition & Serialization Tests");
   const deepRes = exports.add(deepInputPtr);
   assert.equal(deepRes[1], 1, "Tail-recursive Peano addition must handle deep inputs without overflowing the Wasm call stack");
 
+  const deeperInputPtr = writeAddInputPtrToArena(writeNatPtrToArena(20000), writeNatPtrToArena(0));
+  const deeperRes = exports.add(deeperInputPtr);
+  assert.equal(deeperRes[1], 1, "Tail-recursive Peano addition must handle 20000 inputs with compaction without call stack overflow");
+
   console.log("End-to-End Peano Addition & Serialization tests passed successfully!");
 }