@fraczak/k 6.9.0 → 6.10.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.10.1] — 2026-10-02 — Fix Compaction Mark Reset and False Tail Calls in LLVM & WASM Backends
+
+### LLVM & WebAssembly Backends
+
+- **Compaction Mark Reset**: Fixed an issue in both LLVM (`krt.c`) and WebAssembly (`kvm2wasm.mjs`) where tail-loop compaction never reset the baseline arena mark after compacting live objects. Once the threshold was reached, compaction was erroneously triggered on every subsequent iteration, turning $O(N)$ execution into $O(N^2)$ and causing call-stack overflow on large inputs.
+- **Product Branch Tail-Call Fix**: Fixed LLVM lowering in `kvm2llvm.mjs` where recursive calls inside product constructor fields were incorrectly classified as self-tail calls.
+
+---
+
+## [6.10.0] — 2026-10-02 — Dual Evaluation Engines (WASM & JS) and REPL Command Modernization
+
+### REPL & Evaluation Engines
+
+- **Dual Evaluation Engines**: The REPL now supports two evaluation modes:
+  - `wasm` (default): Lowers expressions via polymorphic kVM to WebAssembly AOT bytecode for near-native performance, tail-call optimization, and stack safety.
+  - `js`: Direct tree-walking JavaScript interpreter evaluating parsed relations via `run_rel` with pattern constraints for instant interpretation without compilation latency.
+- **Engine Switching & CLI**:
+  - REPL commands `:engine [wasm|js]`, `:wasm`, and `:js` dynamically inspect or switch the active evaluation engine.
+  - CLI options `--engine=wasm`, `--engine=js`, `--wasm`, and `--js` added to `k-repl`.
+  - Active engine displayed in execution timing annotations (`/* comp: Xms, exec: Yms (wasm) */` or `(js)`).
+- **Web REPL (`repl.html`) Integration**:
+  - Added clickable navbar engine badge (`wasm-in-process` <-> `js-in-process`) for one-click engine toggling in the browser.
+  - Exported `getEngine()` and `setEngine()` on `window.kRepl`.
+- **Command Modernization**:
+  - Removed deprecated REPL commands: `:run expr`, `:eval expr`, `:time expr`, and `:t name`.
+  - Renamed `:codes` to `:types` (listing type aliases).
+  - Renamed `:d name` to `:rel name` (displaying relation definitions).
+
+---
+
 ## [6.9.0] — 2026-10-01 — Reusable Codecs, Dynamic Pattern Derivation & Unified SDK
 
 ### Codecs & Type System

package/CLAUDE.md

@@ -61,4 +61,4 @@ npm test  # Run comprehensive test suite (unit tests, derivation tests, shell te
 - No external runtime dependencies (only jiwson for parser generation)
 - Uses ES6 modules (.mjs files) throughout
 - Extensive test suite in `tests/code-derivation/` for type system validation
-- REPL supports commands like `:C name` (show canonical type), `:t name` (show relation type), and `:d name` (show relation definition)
+- REPL supports commands like `:rel name` (show relation definition), `:type name` (show type definition), `:types`, `:rels`, etc.

package/DOCS/BIG_PICTURE.md

@@ -252,13 +252,11 @@ car = list? /cons .car;
 cdr = list? /cons .cdr;
 ```
 
-For example, the filter annotation for `car` is:
+For example, the definition for `car` is:
 
 ```text
-> :t car
-car : ?<{X1 car, X0 cdr} cons, $KL nil>=X0  -->  ?X1  (@...)
-> :C KL
-$ KL = {};  -- @...
+> :rel car
+car = list? /cons .car;  -- @...
 ```
 
 ## Universal Schema Registry

package/DOCS/REPL.md

@@ -33,16 +33,14 @@ 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 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`) |
@@ -208,21 +206,39 @@ Parses external input using the specified codec file.
 
 Entering `:input` with no arguments displays usage and a list of loaded codecs.
 
+## Evaluation Engines: WASM and JS
+
+The REPL supports two evaluation engines:
+
+- **`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` — displays active engine (`wasm` or `js`)
+- `:engine wasm` (or `:wasm`) — switches to the WebAssembly engine
+- `:engine js` (or `:js`) — 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`.
@@ -274,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/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!");
 }
 

package/browser/repl-browser.mjs

@@ -302,11 +302,24 @@ export async function executeCommand(input) {
   // Re-create completer with updated state
   completer = createCompleter(state);
   updateCodecsBadge();
+  updateEngineUI();
   if (codecsModal && codecsModal.classList.contains("open")) {
     renderCodecsModal();
   }
 }
 
+function updateEngineUI() {
+  const badge = document.getElementById("engine-badge");
+  if (!badge) return;
+  badge.textContent = state.engine === "js" ? "js-in-process" : "wasm-in-process";
+  badge.title = `Engine: ${state.engine} (click to toggle wasm/js)`;
+  if (state.engine === "js") {
+    badge.classList.add("js-mode");
+  } else {
+    badge.classList.remove("js-mode");
+  }
+}
+
 function adjustInputHeight() {
   if (!inputEl) return;
   inputEl.style.height = "auto";
@@ -949,6 +962,16 @@ export function initRepl() {
     }
   });
 
+  // Engine Badge toggle (wasm <-> js)
+  const engineBadge = document.getElementById("engine-badge");
+  if (engineBadge) {
+    engineBadge.onclick = () => {
+      const nextEngine = state.engine === "wasm" ? "js" : "wasm";
+      executeCommand(`:engine ${nextEngine}`);
+    };
+  }
+  updateEngineUI();
+
   inputEl.focus();
 }
 
@@ -965,6 +988,8 @@ if (typeof window !== "undefined") {
     executeCommand,
     initRepl,
     getState: () => state,
+    getEngine: () => state.engine,
+    setEngine: (engine) => executeCommand(`:engine ${engine}`),
     getVfsFile,
     setVfsFile,
     getAllVfsFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.9.0",
+    "version": "6.10.1",
     "description": "k — a language for composing first-order partial functions over algebraic data types (products and tagged unions); includes runtime, type derivation, REPL, and codec toolchain",
     "main": "index.mjs",
     "exports": {

package/repl.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { argv, exit, stdin, stdout } from "node:process";
 
 import { annotate, parse } from "./index.mjs";
-import { constrainWithPattern } from "./run.mjs";
+import run, { constrainWithPattern, run_rel } from "./run.mjs";
 import { compileWasmArtifactFromObject, instantiateWasmArtifact } from "./backends/wasm/src/wasm.mjs";
 import { exportPatternGraph } from "./codecs/runtime/codec.mjs";
 import { patternToPropertyList } from "./codecs/runtime/pattern-json.mjs";
@@ -21,7 +21,7 @@ if (typeof globalThis !== "undefined") {
   globalThis.isVariant = isVariant;
   globalThis.patternFromFilter = patternFromFilter;
 }
-import { patterns2filters, prettyCode, prettyRel } from "./pretty.mjs";
+import { prettyCode } from "./pretty.mjs";
 import {
   compileObject,
   compileLibrary,
@@ -48,9 +48,9 @@ import {
 
 const NAME_RE = /^[a-zA-Z0-9_+-][a-zA-Z0-9_?!+-]*$/;
 const COMMAND_NAMES = [
-  "help", "type", "code", "run", "eval", "t", "d", "C",
-  "codes", "codecs", "rels", "codec", "input", "reset", "klib", "ko", "load",
-  "time",
+  "help", "type", "code", "rel", "C",
+  "types", "codecs", "rels", "codec", "input", "reset", "klib", "ko", "load",
+  "engine", "wasm", "js",
   "quit", "exit"
 ];
 const CODEC_COMMAND_NAMES = ["load", "unload", "list"];
@@ -73,9 +73,14 @@ function emptyValue() {
   return Value.product({}, [["closed-product", []]]);
 }
 
-function createState() {
+function createState(options = {}) {
   codes.load(cloneJSON(initialCodes));
+  const engine = (options.engine || "wasm").toLowerCase();
+  if (engine !== "wasm" && engine !== "js") {
+    throw new Error(`Invalid engine '${options.engine}'. Valid engines: wasm, js`);
+  }
   return {
+    engine,
     codes: codes.dump(),
     rels: {},
     relAliases: {},
@@ -337,11 +342,6 @@ function resolveRel(state, name) {
   return hash ? { hash, rel: state.rels[hash] } : { hash: null, rel: null };
 }
 
-function relTypeString(rel) {
-  const filters = patterns2filters(rel.typePatternGraph, ...rel.def.patterns);
-  return filters.map((filter) => prettyRel({ op: "filter", filter })).join("  -->  ");
-}
-
 function listAliases(aliases) {
   const entries = Object.entries(aliases).sort(([a], [b]) => a.localeCompare(b));
   if (entries.length === 0) return "(none)";
@@ -803,6 +803,10 @@ function completeCommandArgument(line, state) {
     return completeCodecCommand(line, argStart, arg, state);
   }
 
+  if (command === "engine") {
+    return completeCommandWord(line, argStart, arg, ["wasm", "js"]);
+  }
+
   if (command === "input") {
     return completeInputCommand(line, state, argStart, arg);
   }
@@ -1047,47 +1051,24 @@ async function executeExpressionWithWasm(annotated, state, lineOffset = 0) {
   return { result, wasmCompileMs, executeMs };
 }
 
-async function runExpression(input, state) {
-  const expression = input.trim();
-  if (!expression) throw new Error(":run requires an expression");
-
-  restoreCodes(state);
-  const preamble = aliasPreamble(state);
-  const lineOffset = preambleLineCount(preamble);
-  const source = [preamble, expression].filter(Boolean).join("\n");
-  const compileStart = performance.now();
-  let annotated;
-  try {
-    annotated = annotate(source, { libraries: [stateLibrary(state)] });
-  } catch (error) {
-    throw remapError(error, lineOffset);
-  }
-  const snippetCompileMs = performance.now() - compileStart;
+function executeExpressionWithJs(annotated, state, lineOffset = 0) {
+  const mainRel = annotated.rels.__main__;
+  if (!mainRel) return { result: undefined, wasmCompileMs: 0, executeMs: 0 };
 
-  let execRes;
-  try {
-    execRes = await executeExpressionWithWasm(annotated, state, lineOffset);
-  } catch (error) {
-    throw remapError(error, lineOffset);
+  let inputValue = state.value ?? emptyValue();
+  if (mainRel.typePatternGraph && mainRel.def.patterns) {
+    const graph = mainRel.typePatternGraph;
+    const nodeId = graph.find(mainRel.def.patterns[0]);
+    const inputPattern = patternToPropertyList(exportPatternGraph(graph, nodeId));
+    inputValue = constrainWithPattern(inputValue, inputPattern, mainRel.def);
   }
-  state.codes = codes.dump();
-  restoreCodes(state);
 
-  const compileMs = snippetCompileMs + execRes.wasmCompileMs;
-  const executeMs = execRes.executeMs;
-  state.lastTiming = {
-    compileMs,
-    executeMs,
-    totalMs: compileMs + executeMs,
-    snippetCompileMs,
-    wasmCompileMs: execRes.wasmCompileMs
-  };
+  const executeStart = performance.now();
+  run.defs = { rels: annotated.rels };
+  const result = run_rel(codes.find, mainRel, inputValue, "__main__");
+  const executeMs = performance.now() - executeStart;
 
-  const committed = commitResult(state, execRes.result, expression);
-  if (state.showTiming) {
-    committed.push(`/* comp: ${formatDuration(compileMs)}, exec: ${formatDuration(executeMs)} */`);
-  }
-  return committed;
+  return { result, wasmCompileMs: 0, executeMs };
 }
 
 async function runSnippet(input, state, options = {}) {
@@ -1108,7 +1089,8 @@ async function runSnippet(input, state, options = {}) {
       executeMs: 0,
       totalMs: snippetCompileMs,
       snippetCompileMs,
-      wasmCompileMs: 0
+      wasmCompileMs: 0,
+      engine: state.engine
     };
     if (state.showTiming) {
       return [`/* comp: ${formatDuration(snippetCompileMs)} */`];
@@ -1118,26 +1100,32 @@ async function runSnippet(input, state, options = {}) {
 
   let execRes;
   try {
-    execRes = await executeExpressionWithWasm(annotated, state, lineOffset);
+    if (state.engine === "js") {
+      execRes = executeExpressionWithJs(annotated, state, lineOffset);
+    } else {
+      execRes = await executeExpressionWithWasm(annotated, state, lineOffset);
+    }
   } catch (error) {
     throw remapError(error, lineOffset);
   }
   state.codes = codes.dump();
   restoreCodes(state);
 
-  const compileMs = snippetCompileMs + execRes.wasmCompileMs;
+  const wasmCompileMs = execRes.wasmCompileMs || 0;
+  const compileMs = snippetCompileMs + wasmCompileMs;
   const executeMs = execRes.executeMs;
   state.lastTiming = {
     compileMs,
     executeMs,
     totalMs: compileMs + executeMs,
     snippetCompileMs,
-    wasmCompileMs: execRes.wasmCompileMs
+    wasmCompileMs,
+    engine: state.engine
   };
 
   const committed = commitResult(state, execRes.result, snippet);
   if (state.showTiming) {
-    committed.push(`/* comp: ${formatDuration(compileMs)}, exec: ${formatDuration(executeMs)} */`);
+    committed.push(`/* comp: ${formatDuration(compileMs)}, exec: ${formatDuration(executeMs)} (${state.engine}) */`);
   }
   return committed;
 }
@@ -1267,10 +1255,6 @@ async function evaluateCommand(line, state) {
       return [helpText()];
     case "timing":
       throw new Error(":timing has been removed; timing is now always enabled");
-    case "time": {
-      if (!arg) throw new Error(":time requires an expression");
-      return evaluateInput(arg, state);
-    }
     case "type": {
       if (!arg) throw new Error(":type requires a type name");
       if (arg.includes("=")) {
@@ -1280,13 +1264,18 @@ async function evaluateCommand(line, state) {
     }
     case "code":
       return evaluateCommand(`:C ${arg}`, state);
-    case "rel":
     case "def":
       throw new Error("Relation definitions use syntax: name = relExpr;");
-    case "run":
-    case "eval":
-      return runExpression(arg, state);
-    case "codes":
+    case "rel": {
+      if (!arg) throw new Error(`${usagePrefix}rel requires a relation name`);
+      if (arg.includes("=")) {
+        throw new Error("Relation definitions use syntax: name = relExpr; Use :rel <name> to show a relation definition");
+      }
+      const { hash, rel } = resolveRel(state, arg);
+      if (!rel) throw new Error(`Unknown relation '${arg}'`);
+      return [`${arg} = ${prettyRelation(rel, displayAliases(state), state.relAliases)};  -- ${hash}`];
+    }
+    case "types":
       return [listAliases(state.typeAliases)];
     case "rels":
       return [listAliases(state.relAliases)];
@@ -1295,8 +1284,28 @@ async function evaluateCommand(line, state) {
       return loadCodec(arg, state);
     case "input":
       return requestCodecInput(arg, state);
+    case "engine": {
+      const mode = (arg || "").trim().toLowerCase();
+      if (!mode) {
+        return [`Current engine: ${state.engine}`];
+      }
+      if (mode !== "wasm" && mode !== "js") {
+        throw new Error(`Invalid engine '${arg.trim()}'. Valid engines: wasm, js`);
+      }
+      state.engine = mode;
+      return [`engine set to ${mode}`];
+    }
+    case "wasm": {
+      state.engine = "wasm";
+      return ["engine set to wasm"];
+    }
+    case "js": {
+      state.engine = "js";
+      return ["engine set to js"];
+    }
     case "reset": {
-      const fresh = createState();
+      const currentEngine = state.engine;
+      const fresh = createState({ engine: currentEngine });
       Object.assign(state, fresh);
       return ["reset"];
     }
@@ -1321,18 +1330,6 @@ async function evaluateCommand(line, state) {
       loadSourceOrKlib(state, loadPath, { loadAliases });
       return [`loaded ${loadPath}`];
     }
-    case "t": {
-      if (!arg) throw new Error(`${usagePrefix}t requires a relation name`);
-      const { hash, rel } = resolveRel(state, arg);
-      if (!rel) throw new Error(`Unknown relation '${arg}'`);
-      return [`${arg} : ${relTypeString(rel)}  (${hash})`];
-    }
-    case "d": {
-      if (!arg) throw new Error(`${usagePrefix}d requires a relation name`);
-      const { hash, rel } = resolveRel(state, arg);
-      if (!rel) throw new Error(`Unknown relation '${arg}'`);
-      return [`${arg} = ${prettyRelation(rel, displayAliases(state), state.relAliases)};  -- ${hash}`];
-    }
     case "C": {
       if (!arg) throw new Error(`${usagePrefix}C requires a type name`);
       const hash = state.typeAliases[arg] || (arg.startsWith("@") ? arg : null);
@@ -1346,12 +1343,10 @@ async function evaluateCommand(line, state) {
 
 function helpText() {
   return [
-    ":run expr            run an expression on the current value",
-    ":time expr           run an expression and report compilation/execution time",
-    ":t name              show relation type",
-    ":d name              show relation definition",
+    ":engine [wasm|js]    display or switch evaluation engine (wasm or js)",
+    ":rel name            show relation definition",
     ":type name           show type definition",
-    ":codes               list type aliases",
+    ":types               list type aliases",
     ":rels                list relation aliases",
     ":codec load file     load a codec module from file (e.g. :codec load codecs/int.mjs)",
     ":codec unload name   unload a registered codec",
@@ -1376,17 +1371,19 @@ function promptForState(state) {
 }
 
 function cliUsage() {
-  console.log("Usage: k-repl");
-  console.log("       k-repl -h");
+  console.log("Usage: k-repl [options]");
   console.log("");
   console.log("Start the interactive k interpreter. Type :help inside the REPL for commands.");
   console.log("");
   console.log("Options:");
-  console.log("  -h, --help   Show this help.");
+  console.log("  --engine=<wasm|js>  Select evaluation engine (default: wasm)");
+  console.log("  --js                Shortcut for --engine=js");
+  console.log("  --wasm              Shortcut for --engine=wasm");
+  console.log("  -h, --help          Show this help.");
 }
 
-function startRepl() {
-  const state = createState();
+function startRepl(options = {}) {
+  const state = createState(options);
   const rl = readline.createInterface({
     input: stdin,
     output: stdout,
@@ -1397,7 +1394,7 @@ function startRepl() {
   let pending = Promise.resolve();
   let closed = false;
 
-  console.log("k interpreter (.klib-backed). Type :help for commands.");
+  console.log(`k interpreter (.klib-backed, ${state.engine}). Type :help for commands.`);
   rl.prompt();
   async function handleLine(line) {
     if (state.pendingInput && buffer.length === 0) {
@@ -1476,15 +1473,38 @@ function startRepl() {
 
 if (isMainEntrypoint()) {
   const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    cliUsage();
-    exit(0);
-  }
-  if (args.length > 0) {
-    cliUsage();
-    exit(1);
+  let engine = "wasm";
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      cliUsage();
+      exit(0);
+    } else if (arg === "--js") {
+      engine = "js";
+    } else if (arg === "--wasm") {
+      engine = "wasm";
+    } else if (arg.startsWith("--engine=")) {
+      const val = arg.slice("--engine=".length).toLowerCase();
+      if (val !== "wasm" && val !== "js") {
+        console.error(`Invalid engine '${val}'. Valid engines: wasm, js`);
+        exit(1);
+      }
+      engine = val;
+    } else if (arg === "--engine") {
+      i++;
+      const val = (args[i] || "").toLowerCase();
+      if (val !== "wasm" && val !== "js") {
+        console.error(`Invalid engine '${val}'. Valid engines: wasm, js`);
+        exit(1);
+      }
+      engine = val;
+    } else {
+      console.error(`Unknown option '${arg}'.`);
+      cliUsage();
+      exit(1);
+    }
   }
-  startRepl();
+  startRepl({ engine });
 }
 
 export {

package/scripts/build-repl-html.mjs

@@ -247,6 +247,25 @@ const htmlContent = `<!DOCTYPE html>
       border: 1px solid rgba(88, 166, 255, 0.3);
       padding: 2px 8px;
       border-radius: 12px;
+      cursor: pointer;
+      user-select: none;
+      transition: all 0.15s ease;
+    }
+
+    .engine-badge:hover {
+      background: rgba(88, 166, 255, 0.3);
+      border-color: rgba(88, 166, 255, 0.6);
+    }
+
+    .engine-badge.js-mode {
+      background: rgba(240, 180, 41, 0.15);
+      color: #e3b341;
+      border-color: rgba(240, 180, 41, 0.4);
+    }
+
+    .engine-badge.js-mode:hover {
+      background: rgba(240, 180, 41, 0.3);
+      border-color: rgba(240, 180, 41, 0.7);
     }
 
     .status-indicator {
@@ -1609,7 +1628,7 @@ const htmlContent = `<!DOCTYPE html>
       <div class="nav-left">
         <div class="brand">
           <span class="brand-name">k repl</span>
-          <span class="engine-badge">wasm-in-process</span>
+          <span id="engine-badge" class="engine-badge" title="Click to toggle engine (wasm/js)">wasm-in-process</span>
         </div>
         <div class="status-indicator">
           <span id="status-dot" class="status-dot ready"></span>
@@ -1635,8 +1654,11 @@ const htmlContent = `<!DOCTYPE html>
               <option value="expr:{10 x, 5 y} plus">{10 x, 5 y} plus (bits)</option>
               <option value="expr:1 succ">1 succ</option>
               <option value="expr:{10 int x, 5 int y} plus">{10 int x, 5 int y} plus (int)</option>
-              <option value="expr::codes">:codes (list types)</option>
+              <option value="expr::types">:types (list types)</option>
               <option value="expr::rels">:rels (list relations)</option>
+              <option value="expr::engine">:engine (show engine)</option>
+              <option value="expr::engine wasm">:engine wasm</option>
+              <option value="expr::engine js">:engine js</option>
             </optgroup>
             <optgroup label="Codecs &amp; Format Adapters">
               <option value="expr::codecs">:codecs</option>
@@ -1856,17 +1878,16 @@ const htmlContent = `<!DOCTYPE html>
           <div class="help-section">
             <h4>REPL Commands</h4>
             <table class="help-table">
+              <tr><td><code>:engine [wasm|js]</code></td><td>Display or switch evaluation engine (<code>wasm</code> or <code>js</code>)</td></tr>
               <tr><td><code>:load &lt;file&gt;</code></td><td>Load a <code>.k</code> source or <code>.klib</code> library into current state</td></tr>
-              <tr><td><code>:t &lt;name&gt;</code></td><td>Display the derived type of relation <code>&lt;name&gt;</code></td></tr>
-              <tr><td><code>:d &lt;name&gt;</code></td><td>Display definition of relation <code>&lt;name&gt;</code></td></tr>
+              <tr><td><code>:rel &lt;name&gt;</code></td><td>Display definition of relation <code>&lt;name&gt;</code></td></tr>
               <tr><td><code>:type &lt;name&gt;</code></td><td>Display definition of type <code>&lt;name&gt;</code></td></tr>
-              <tr><td><code>:codes</code></td><td>List all type aliases and canonical hashes</td></tr>
+              <tr><td><code>:types</code></td><td>List all type aliases and canonical hashes</td></tr>
               <tr><td><code>:rels</code></td><td>List all relation aliases</td></tr>
               <tr><td><code>:codecs</code></td><td>List all loaded format codecs</td></tr>
               <tr><td><code>:codec load &lt;file.mjs&gt;</code></td><td>Load a codec from file (or load through Files)</td></tr>
               <tr><td><code>:codec unload &lt;file.mjs&gt;</code></td><td>Unload a loaded codec</td></tr>
               <tr><td><code>:input &lt;codec.mjs&gt; [text]</code></td><td>Parse input using specified codec (opens dialog if text omitted)</td></tr>
-              <tr><td><code>:time &lt;expr&gt;</code></td><td>Evaluate <code>&lt;expr&gt;</code> and report execution time</td></tr>
               <tr><td><code>:klib &lt;file&gt;</code></td><td>Export current state as a <code>.klib</code> binary file</td></tr>
               <tr><td><code>:reset</code></td><td>Clear state and reset to initial environment</td></tr>
               <tr><td><code>:help</code></td><td>Show command reference</td></tr>

package/tests/test-repl-html.mjs

@@ -539,11 +539,17 @@ if (chromiumBin) {
       btnHelp.click();
       const helpModalOpen = document.getElementById("help-modal")?.classList.contains("open");
       const modalText = document.getElementById("help-modal")?.textContent || "";
-      const hasRel = modalText.includes(":rel ");
+      const hasRel = modalText.includes(":rel <name>");
       const hasVal = modalText.includes(":val");
       const hasTiming = modalText.includes(":timing");
+      const hasTime = modalText.includes(":time");
+      const hasT = modalText.includes(":t <name>");
       const hasCodecDefine = modalText.includes(":codec define");
       const hasType = modalText.includes(":type <name>");
+      const hasTypes = modalText.includes(":types");
+      const hasCodes = modalText.includes(":codes");
+      const hasD = modalText.includes(":d <name>");
+      const hasEngine = modalText.includes(":engine");
       return {
         found: true,
         isVisible,
@@ -552,18 +558,48 @@ if (chromiumBin) {
         hasRel,
         hasVal,
         hasTiming,
+        hasTime,
+        hasT,
         hasCodecDefine,
-        hasType
+        hasType,
+        hasTypes,
+        hasCodes,
+        hasD,
+        hasEngine
       };
     })()`);
     assert.strictEqual(narrowNavbarCheck.found, true, "#btn-help should exist");
     assert.strictEqual(narrowNavbarCheck.isVisible, true, "#btn-help should be visible within narrow viewport");
     assert.strictEqual(narrowNavbarCheck.helpModalOpen, true, "Clicking #btn-help in narrow viewport should open help modal");
-    assert.strictEqual(narrowNavbarCheck.hasRel, false, "Help modal should not contain :rel");
+    assert.strictEqual(narrowNavbarCheck.hasRel, true, "Help modal should contain :rel <name>");
+    assert.strictEqual(narrowNavbarCheck.hasType, true, "Help modal should contain :type <name>");
+    assert.strictEqual(narrowNavbarCheck.hasTypes, true, "Help modal should contain :types");
+    assert.strictEqual(narrowNavbarCheck.hasEngine, true, "Help modal should contain :engine");
+    assert.strictEqual(narrowNavbarCheck.hasCodes, false, "Help modal should not contain :codes");
+    assert.strictEqual(narrowNavbarCheck.hasTime, false, "Help modal should not contain :time");
+    assert.strictEqual(narrowNavbarCheck.hasT, false, "Help modal should not contain :t <name>");
+    assert.strictEqual(narrowNavbarCheck.hasD, false, "Help modal should not contain :d <name>");
     assert.strictEqual(narrowNavbarCheck.hasVal, false, "Help modal should not contain :val");
     assert.strictEqual(narrowNavbarCheck.hasTiming, false, "Help modal should not contain :timing");
     assert.strictEqual(narrowNavbarCheck.hasCodecDefine, false, "Help modal should not contain :codec define");
-    assert.strictEqual(narrowNavbarCheck.hasType, true, "Help modal should contain :type <name>");
+
+    // 6. Test dual engine switching in browser (wasm <-> js)
+    const engineCheck = await evaluateAsync(`(async () => {
+      const initialEngine = window.kRepl.getEngine();
+      await window.kRepl.executeCommand(":engine js");
+      const jsEngine = window.kRepl.getEngine();
+      const badgeJsText = document.getElementById("engine-badge")?.textContent;
+      await window.kRepl.executeCommand("() | ok");
+      await window.kRepl.executeCommand(":engine wasm");
+      const wasmEngine = window.kRepl.getEngine();
+      const badgeWasmText = document.getElementById("engine-badge")?.textContent;
+      return { initialEngine, jsEngine, wasmEngine, badgeJsText, badgeWasmText };
+    })()`);
+    assert.strictEqual(engineCheck.initialEngine, "wasm");
+    assert.strictEqual(engineCheck.jsEngine, "js");
+    assert.strictEqual(engineCheck.badgeJsText, "js-in-process");
+    assert.strictEqual(engineCheck.wasmEngine, "wasm");
+    assert.strictEqual(engineCheck.badgeWasmText, "wasm-in-process");
 
     ws.close();
     console.log("   Browser execution verified successfully!");

package/tests/test-repl.mjs

@@ -29,16 +29,16 @@ output = await evaluateInput(":type nat", state);
 assert.match(output[0], /^\$ nat = /);
 
 output = await evaluateInput("succ = | succ;", state);
-output = await evaluateInput(":d succ", state);
+output = await evaluateInput(":rel succ", state);
 assert.match(output[0], /^succ = /);
 
-output = await evaluateInput(":codes", state);
+output = await evaluateInput(":types", state);
 assert.match(output[0], /^nat = @/m);
 
 output = await evaluateInput(":rels", state);
 assert.match(output[0], /^succ = @/m);
 
-output = await evaluateInput(":run succ", state);
+output = await evaluateInput("succ", state);
 assert.equal(output[0], "{}|succ ?<{} succ, ...>");
 
 output = await evaluateInput("/zero", state);
@@ -48,24 +48,38 @@ assert.equal(state.value.toJSON(), "succ");
 output = await evaluateInput("succ", state);
 assert.match(output[0], /^\{\}\|succ\|succ \?</);
 
-output = await evaluateInput(":t succ", state);
-assert.match(output[0], /^succ : /);
-
-output = await evaluateInput(":d succ", state);
+output = await evaluateInput(":rel succ", state);
 assert.match(output[0], /^succ = /);
 
 let completions = completeInput(":he", state)[0];
 assert.deepEqual(completions, [":help"]);
 
 const canonicalPartial = state.typeAliases.nat.slice(0, 8);
-completions = completeInput(`:run ${canonicalPartial}`, state)[0];
+completions = completeInput(`:rel ${canonicalPartial}`, state)[0];
 assert(completions.some((line) => line.endsWith(state.typeAliases.nat)));
 
 completions = completeInput(`(${canonicalPartial}`, state)[0];
 assert(completions.includes(`(${state.typeAliases.nat}`));
 
-completions = completeInput(":run su", state)[0];
-assert(completions.includes(":run succ"));
+completions = completeInput(":rel su", state)[0];
+assert(completions.includes(":rel succ"));
+completions = completeInput(":ty", state)[0];
+assert(completions.includes(":types"));
+assert(completions.includes(":type"));
+
+await assert.rejects(
+  () => evaluateInput(":run succ", state),
+  /Unknown command ':run'/
+);
+await assert.rejects(
+  () => evaluateInput(":time ()", state),
+  /Unknown command ':time'/
+);
+await assert.rejects(
+  () => evaluateInput(":t succ", state),
+  /Unknown command ':t'/
+);
+
 completions = completeInput(":co", state)[0];
 assert(completions.includes(":codec"));
 
@@ -134,11 +148,11 @@ fs.writeFileSync(sourcePath, "$ nat = <{} zero, nat succ>;\nsucc = $nat |succ $n
 const loadedSource = createState();
 output = await evaluateInput(`:load ${sourcePath}`, loadedSource);
 assert.equal(output[0], `loaded ${sourcePath}`);
-output = await evaluateInput(":codes", loadedSource);
+output = await evaluateInput(":types", loadedSource);
 assert.match(output[0], /^nat = @/m);
 output = await evaluateInput(":rels", loadedSource);
 assert.match(output[0], /^succ = @/m);
-output = await evaluateInput(":d twice", loadedSource);
+output = await evaluateInput(":rel twice", loadedSource);
 assert.match(output[0], /^twice = \$nat succ succ \$nat;  -- @/);
 output = await evaluateInput(":C nat", loadedSource);
 assert.match(output[0], /^\$ nat = < nat succ, @[^ ]+ zero >;  -- @/);
@@ -235,7 +249,7 @@ const reloaded = createState();
 output = await evaluateInput(`:load ${libPath}`, reloaded);
 assert.equal(output[0], `loaded ${libPath}`);
 
-output = await evaluateInput(":codes", reloaded);
+output = await evaluateInput(":types", reloaded);
 assert.match(output[0], /^nat = @/m);
 
 output = await evaluateInput(":rels", reloaded);
@@ -247,7 +261,7 @@ assert.equal(output[0], "{}|succ ?<{} succ, ...>");
 const noAliasReloaded = createState();
 output = await evaluateInput(`:load --no-alias ${libPath}`, noAliasReloaded);
 assert.equal(output[0], `loaded ${libPath}`);
-output = await evaluateInput(":codes", noAliasReloaded);
+output = await evaluateInput(":types", noAliasReloaded);
 assert.equal(output[0], "(none)");
 output = await evaluateInput(":rels", noAliasReloaded);
 assert.equal(output[0], "(none)");
@@ -255,7 +269,7 @@ assert.equal(output[0], "(none)");
 const shorthand = createState();
 output = await evaluateInput("$ nat = <{} zero, nat succ>\n; succ = |succ\n;", shorthand);
 assert.match(output[0], /\/\* comp: .* \*\//);
-output = await evaluateInput(":codes", shorthand);
+output = await evaluateInput(":types", shorthand);
 assert.match(output[0], /^nat = @/m);
 output = await evaluateInput(":rels", shorthand);
 assert.match(output[0], /^succ = @/m);
@@ -265,7 +279,7 @@ assert.match(output[0], / false/);
 assert.match(output[0], / true/);
 output = await evaluateInput("$ maybe = <{} none, {} some>;", shorthand);
 assert.match(output[0], /\/\* comp: .* \*\//);
-output = await evaluateInput(":codes", shorthand);
+output = await evaluateInput(":types", shorthand);
 assert.match(output[0], /^maybe = @/m);
 output = await evaluateInput("{} | true not", shorthand);
 assert.match(output[0], /^\{\}\|false \?</);
@@ -441,21 +455,75 @@ assert.equal(output[0], "loaded Examples/poly.k");
 assert.ok(polyAutoState.relAliases.reverse, "poly relations should be loaded");
 assert.ok(polyAutoState.typeAliases.int, "arithmetics int should be auto-loaded");
 
-// Verify timing reporting is always on and :time command
+// Verify timing reporting is always on and reflects active engine
 const timingState = createState();
 assert.equal(timingState.showTiming, true);
+assert.equal(timingState.engine, "wasm");
 
 output = await evaluateInput("()", timingState);
 assert.equal(output[0], "{} ?{}");
-assert.match(output[1], /\/\* comp: .*, exec: .* \*\//);
-
-output = await evaluateInput(":time ()", timingState);
-assert.equal(output[0], "{} ?{}");
-assert.match(output[1], /\/\* comp: .*, exec: .* \*\//);
+assert.match(output[1], /\/\* comp: .*, exec: .* \(wasm\) \*\//);
 assert.ok(timingState.lastTiming);
+assert.equal(timingState.lastTiming.engine, "wasm");
 assert.ok(typeof timingState.lastTiming.compileMs === "number");
 assert.ok(typeof timingState.lastTiming.executeMs === "number");
 
+// Verify :engine command and switching between wasm and js engines
+output = await evaluateInput(":engine", timingState);
+assert.equal(output[0], "Current engine: wasm");
+
+output = await evaluateInput(":engine js", timingState);
+assert.equal(output[0], "engine set to js");
+assert.equal(timingState.engine, "js");
+
+output = await evaluateInput("()", timingState);
+assert.equal(output[0], "{} ?{}");
+assert.match(output[1], /\/\* comp: .*, exec: .* \(js\) \*\//);
+assert.equal(timingState.lastTiming.engine, "js");
+
+// Verify shortcuts :wasm and :js
+output = await evaluateInput(":wasm", timingState);
+assert.equal(output[0], "engine set to wasm");
+assert.equal(timingState.engine, "wasm");
+
+output = await evaluateInput(":js", timingState);
+assert.equal(output[0], "engine set to js");
+assert.equal(timingState.engine, "js");
+
+// Verify :reset preserves the active engine
+output = await evaluateInput(":reset", timingState);
+assert.equal(output[0], "reset");
+assert.equal(timingState.engine, "js");
+
+// Verify invalid engine error
+await assert.rejects(
+  () => evaluateInput(":engine invalid", timingState),
+  /Invalid engine 'invalid'\. Valid engines: wasm, js/
+);
+
+// Verify autocompletion for :engine
+completions = completeInput(":engine ", timingState)[0];
+assert(completions.includes(":engine wasm"));
+assert(completions.includes(":engine js"));
+
+// Verify evaluating expressions in JS engine
+const jsState = createState({ engine: "js" });
+assert.equal(jsState.engine, "js");
+
+output = await evaluateInput("$ nat = < {} zero, nat succ >;\nsucc = | succ;\n{} | zero succ succ", jsState);
+assert.match(output[0], /^\{\}\|zero\|succ\|succ/);
+assert.match(output[1], /\(js\)/);
+
+output = await evaluateInput("$ bool = < {} true, {} false >;\nnot = $bool </true | false, {} | true >;\n{} | true not", jsState);
+assert.match(output[0], /^\{\}\|false/);
+assert.match(output[1], /\(js\)/);
+
+output = await evaluateInput(":load Examples/arithmetics.k", jsState);
+assert.equal(output[0], "loaded Examples/arithmetics.k");
+output = await evaluateInput("{ 10 int x, 5 int y } plus", jsState);
+assert.match(output[0], /^\{\}\|_\|1\|1\|1\|1\|\+/);
+assert.match(output[1], /\(js\)/);
+
 fs.rmSync(tmpDir, { recursive: true, force: true });
 fs.rmSync(symlinkPath, { force: true });
 console.log("OK");