@fraczak/k 6.10.3 → 6.10.5

package/core.k

@@ -39,11 +39,11 @@ concat_ = ${bits x, bits y}
 -- successor (increment by 1)
 succ = {inv x, _ y} _inc;
 
-_inc = ${bits x, bits y} <
-    {.x /0 x, .y |1 y} concat_,
-    {.x /1 x, .y |0 y} _inc,
-    .y |1
->;
+_inc = ?{X x, X y} 
+<
+    {.x </0,/_|_> x, .y |1 y} concat_,
+    {.x /1 x, .y |0 y} _inc
+> ?X;
 
 -- constants
 2 = 1 succ;
@@ -58,20 +58,27 @@ _inc = ${bits x, bits y} <
 
 -- addition on $bits (unsigned, LSB-first with carry)
 plus = ${bits x, bits y} {.x inv x, .y inv y, b0 c} _plus;
-_plus = ${bits x, bits y, bit c}
+_plus = {.x x, .y y, .c c, _ r} _plus_;
+_plus_ = ${bits x, bits y, bit c, bits r}
   <
-    {.x /_ if, .y /_ and, <.c/0 0, 1> then} .then,
-    {.x /_ if, .c/0 and, .y then} .then,
-    {.x y, .y /_|_ x, .c c} _plus,
-    {<.c/0 0, 1> x, .y y, .x /_ b0 c} _plus,
-    {.x /0 x, .y /0 y, .c/0 b0 c} _plus |0,
-    {.x /0 x, .y /0 y, .c/1 b0 c} _plus |1,
-    {.x /0 x, .y /1 y, .c/0 b0 c} _plus |1,
-    {.x /0 x, .y /1 y, .c/1 b1 c} _plus |0,
-    {.x /1 x, .y /0 y, .c/0 b0 c} _plus |1,
-    {.x /1 x, .y /0 y, .c/1 b1 c} _plus |0,
-    {.x /1 x, .y /1 y, .c/0 b1 c} _plus |0,
-    {.x /1 x, .y /1 y, .c/1 b1 c} _plus |1
+    {.x /_ if, .y /_ and, .c/0 c, .r then} .then,
+    {.x /_ if, .y /_ and, .c/1 c, .r |1 then} .then,
+    {.x /_ if, .c/0 and, {.y x, .r y} concat_ then} .then,
+    {.y /_ if, .c/0 and, {.x x, .r y} concat_ then} .then,
+    <
+      {.x/_ _ x, .y /0 y, b0 c, .r |1 r},
+      {.x/_ _ x, .y /1 y, b1 c, .r |0 r},
+      {.y/_ _ y, .x /0 x, b0 c, .r |1 r},
+      {.y/_ _ y, .x /1 x, b1 c, .r |0 r},
+      {.x /0 x, .y /0 y, .c/0 b0 c, .r |0 r},
+      {.x /0 x, .y /0 y, .c/1 b0 c, .r |1 r},
+      {.x /0 x, .y /1 y, .c/0 b0 c, .r |1 r},
+      {.x /0 x, .y /1 y, .c/1 b1 c, .r |0 r},
+      {.x /1 x, .y /0 y, .c/0 b0 c, .r |1 r},
+      {.x /1 x, .y /0 y, .c/1 b1 c, .r |0 r},
+      {.x /1 x, .y /1 y, .c/0 b1 c, .r |0 r},
+      {.x /1 x, .y /1 y, .c/1 b1 c, .r |1 r}
+    > _plus_
   >;
 
 -- multiplication on $bits (unsigned, shift-and-add)

package/harness/suites/poly.mjs

@@ -48,7 +48,7 @@ export async function createPolySuite({ listLength = 40, cacheDir = null } = {})
     return lines.join("\n") + "\n";
   }
 
-  const neededExports = ["0", "int", "inc", "dec", "nat", "zero_int?", "nil", "cons", "car", "cdr"];
+  const neededExports = ["0", "int", "inc", "dec", "nat", "zero_int?"];
   const exportPreamble = buildExportPreamble(neededExports, [arithmeticsLib]);
   const polyLib = loadLibrary(compileLibrary(exportPreamble + polySource, {
     source: polyPath,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.10.3",
+    "version": "6.10.5",
     "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": {
@@ -20,6 +20,7 @@
         "perf:ieee": "node scripts/perf-ieee.mjs",
         "perf:ieee:full": "node scripts/perf-ieee.mjs --full",
         "perf:int": "node scripts/perf-int.mjs",
+        "perf:mult": "node scripts/perf-multiplication.mjs",
         "perf:poly": "node scripts/perf-poly.mjs",
         "perf:poly:trace": "node scripts/perf-poly.mjs --trace",
         "perf:idempotency": "node scripts/benchmark-idempotency.mjs",

package/repl-codecs.mjs

@@ -107,8 +107,10 @@ function registerCodec(state, rawCodec, filePath) {
 
 function unregisterCodec(state, codecName) {
   const store = codecStore(state);
-  if (!store[codecName]) return 0;
-  delete store[codecName];
+  const baseName = path.basename(codecName);
+  const key = store[codecName] ? codecName : (store[baseName] ? baseName : null);
+  if (!key) return 0;
+  delete store[key];
   return 1;
 }
 
@@ -129,7 +131,8 @@ function resolveCodec(state, codecName, capability = null) {
     throw new Error("Codec name is required");
   }
   const store = codecStore(state);
-  const codec = store[codecName];
+  const baseName = path.basename(codecName);
+  const codec = store[codecName] || store[baseName];
   if (!codec) {
     throw new Error(`Codec '${codecName}' is not loaded`);
   }

package/scripts/benchmark-idempotency.mjs

@@ -14,6 +14,33 @@ const DEFAULT_EXAMPLES = [
   "Examples/ieee.k"
 ];
 
+function printHelp() {
+  console.log(
+`Usage: node scripts/benchmark-idempotency.mjs [options] [files...]
+
+Measures compile and decompile round-trip idempotency performance
+for K source files through the .klib object format.
+
+Arguments:
+  example.k ...
+      One or more .k source files to benchmark.
+      (default: Examples/nat.k Examples/byte.k Examples/bnat.k
+                Examples/arithmetics.k Examples/ieee.k)
+
+Options:
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  K_BENCH_ITERATIONS
+      Number of round-trip benchmark iterations (default: 5).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 const iterations = Number(process.env.K_BENCH_ITERATIONS || 5);
 const examples = process.argv.slice(2);
 const benchmarkExamples = examples.length > 0 ? examples : DEFAULT_EXAMPLES;

package/scripts/benchmark.mjs

@@ -733,7 +733,58 @@ function printSummary(document) {
   console.log("=============================================================\n");
 }
 
+function printHelp() {
+  console.log(`Usage: node scripts/benchmark.mjs [options]
+
+Unified Multi-Backend Benchmark Suite.
+Runs comprehensive arithmetic and IEEE benchmarks across Native JS,
+kVM, KIR-P, Wasm, and LLVM-JIT execution engines.
+
+Options:
+  --worker
+      Internal flag: execute an isolated benchmark worker job.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BENCHMARK_CASES
+      Comma-separated benchmark cases to run (default: all).
+      Cases: ieee.add, ieee.sub, ieee.mul, ieee.div,
+             int.times.220d, int.gcd.90d, int.factorial.101,
+             int.factorial.242, int.factorial.1174
+  BENCHMARK_MODES
+      Comma-separated execution modes to run (default: all).
+      Modes: Native JS (Envelope-Aware), Native JS (Envelope-Free),
+             kVM Interpreter (Env-Free), KIR-P Export,
+             k-wasm, k-llvm-jit
+  BENCHMARK_SAMPLES
+      Number of measurement samples per benchmark (default: 3).
+  BENCHMARK_TIMEOUT_MS
+      Timeout per benchmark job in milliseconds (default: 120000).
+  BENCHMARK_JOBS
+      Maximum parallel worker concurrency (default: 1).
+  BENCHMARK_STRICT
+      Exit with non-zero exit code if any case fails ('1' to enable).
+  K_LLVM_RUNTIME_MODE
+      Default LLVM runtime compilation mode (default: fast).
+  K_LLVM_IEEE_RUNTIME_MODE
+      LLVM runtime mode for IEEE benchmarks (default: compact).
+  K_LLVM_CLANG_OPT
+      Clang optimization flag for LLVM (default: -O3).
+  K_LLVM_IEEE_CLANG_OPT
+      Clang optimization flag for IEEE LLVM (default: -O0).
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  K_BENCHMARK_RESULT_PATH
+      Custom destination file path for benchmark results JSON.`);
+}
+
 async function main() {
+  if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    printHelp();
+    return;
+  }
+
   if (process.env.K_BENCHMARK_WORKER === "1" || process.argv.includes("--worker")) {
     await workerMain();
     return;

package/scripts/build-repl-html.mjs

@@ -10,6 +10,23 @@ const __dirname = path.dirname(__filename);
 const projectRoot = path.resolve(__dirname, "..");
 const workspaceRoot = path.resolve(projectRoot, "..");
 
+function printHelp() {
+  console.log(`Usage: node scripts/build-repl-html.mjs [options]
+
+Builds the standalone, self-contained K web REPL (repl.html).
+Bundles browser shims, virtual file system (core.k, Examples, Wasm),
+and UI components into a single zero-dependency HTML file.
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 console.log("=== Building Self-Contained K REPL HTML ===");
 
 // 1. Node shims plugin for esbuild
@@ -61,8 +78,8 @@ if (fs.existsSync(coreKPath)) {
   vfsFiles["core.k"] = fs.readFileSync(coreKPath, "utf8");
 }
 
-// Add verified k-code files: arithmetics.k, ieee.k, poly.k
-const verifiedExamples = ["arithmetics.k", "ieee.k", "poly.k"];
+// Add verified k-code files: arithmetics.k, ieee.k, poly.k, karatsuba-mult.k
+const verifiedExamples = ["arithmetics.k", "ieee.k", "poly.k", "karatsuba-mult.k"];
 const examplesDir = path.join(projectRoot, "Examples");
 for (const filename of verifiedExamples) {
   const fullPath = path.join(examplesDir, filename);
@@ -113,7 +130,6 @@ for (const filename of verifiedCodecs) {
       }]
     });
     const bundledContent = buildRes.outputFiles[0].text;
-    vfsFiles[filename] = bundledContent;
     vfsFiles[`codecs/${filename}`] = bundledContent;
   }
 }
@@ -1646,6 +1662,7 @@ const htmlContent = `<!DOCTYPE html>
               <option value="arithmetics.k">arithmetics.k</option>
               <option value="ieee.k">ieee.k</option>
               <option value="poly.k">poly.k</option>
+              <option value="karatsuba-mult.k">karatsuba-mult.k</option>
             </optgroup>
             <optgroup label="Quick Expressions">
               <option value="expr:{} | ok">{} | ok</option>
@@ -1654,6 +1671,7 @@ 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:{10 int x, 5 int y} karatsuba">{10 int x, 5 int y} karatsuba</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>
@@ -1663,13 +1681,13 @@ const htmlContent = `<!DOCTYPE html>
             <optgroup label="Codecs &amp; Format Adapters">
               <option value="expr::codecs">:codecs</option>
               <option value="expr::input">:input (interactive dialog)</option>
-              <option value="expr::codec load int.mjs">:codec load int.mjs</option>
-              <option value="expr::codec load utf8.mjs">:codec load utf8.mjs</option>
-              <option value="expr::codec load json.mjs">:codec load json.mjs</option>
-              <option value="expr::codec load ieee.mjs">:codec load ieee.mjs</option>
-              <option value="expr::codec load unit.mjs">:codec load unit.mjs</option>
-              <option value="expr::input json.mjs {&quot;a&quot;:12,&quot;b&quot;:&quot;hello&quot;}">:input json.mjs {"a":12,"b":"hello"}</option>
-              <option value="expr::input int.mjs [0,1,2]">:input int.mjs [0,1,2]</option>
+              <option value="expr::codec load codecs/int.mjs">:codec load codecs/int.mjs</option>
+              <option value="expr::codec load codecs/utf8.mjs">:codec load codecs/utf8.mjs</option>
+              <option value="expr::codec load codecs/json.mjs">:codec load codecs/json.mjs</option>
+              <option value="expr::codec load codecs/ieee.mjs">:codec load codecs/ieee.mjs</option>
+              <option value="expr::codec load codecs/unit.mjs">:codec load codecs/unit.mjs</option>
+              <option value="expr::input codecs/json.mjs {&quot;a&quot;:12,&quot;b&quot;:&quot;hello&quot;}">:input codecs/json.mjs {"a":12,"b":"hello"}</option>
+              <option value="expr::input codecs/int.mjs [0,1,2]">:input codecs/int.mjs [0,1,2]</option>
             </optgroup>
           </select>
           <button id="btn-load-example" class="btn btn-primary">Load</button>

package/scripts/generate-dependency-graph.mjs

@@ -8,7 +8,31 @@ import { execSync } from "node:child_process";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const root = path.resolve(__dirname, "..");
-const outPath = path.join(root, "DOCS", "dependency-graph.md");
+
+function printHelp() {
+  console.log(
+`Usage: node scripts/generate-dependency-graph.mjs [options] [out]
+
+Generates a Mermaid dependency diagram from tracked ESM imports.
+
+Arguments:
+  out-file
+      Destination markdown file path.
+      (default: DOCS/dependency-graph.md)
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
+const outPath = process.argv[2]
+  ? path.resolve(root, process.argv[2])
+  : path.join(root, "DOCS", "dependency-graph.md");
 
 function getTrackedMjsFiles() {
   const raw = execSync("git ls-files '*.mjs'", {

package/scripts/perf-ieee.mjs

@@ -52,6 +52,81 @@ import {
 import { compileWasmArtifactFromObject } from "../backends/wasm/src/wasm.mjs";
 import { compileARM64ArtifactFromObject } from "../backends/arm64/src/arm64.mjs";
 
+function printHelp() {
+  console.log(`Usage: node scripts/perf-ieee.mjs [options]
+
+IEEE 754 Floating-Point Arithmetic Benchmark Harness.
+Benchmarks add, sub, mul, and div on Examples/ieee.k across
+Native JS, kVM interpreter, LLVM, Wasm, and ARM64 backends.
+
+Options:
+  --opt=<levels>, --opts=<levels>
+      Comma-separated Clang optimization levels for LLVM (e.g. -O1,-O2).
+  --O0, --O1, --O2, --O3
+      Direct Clang optimization level flags for LLVM.
+  --full
+      Run full LLVM optimization sweep (-O0, -O1, -O2).
+  --wasm-in-process
+      Run WebAssembly in-process instead of persistent subprocess runner.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BACKENDS
+      Target backend to run: 'llvm', 'wasm', or 'arm64'.
+  LLVM_ONLY
+      Run only LLVM backend ('1' to enable).
+  WASM_ONLY
+      Run only WebAssembly backend ('1' to enable).
+  ARM64_ONLY
+      Run only ARM64 backend ('1' to enable).
+  BACKENDS_ONLY
+      Skip JS and kVM interpreter baselines ('1' to enable).
+  VALUES
+      Comma-separated float values to benchmark
+      (default: 0.5,-4,0,Infinity,-Infinity,NaN).
+  ITERATIONS
+      Measured iterations per benchmark (default: 3).
+  ARM64_WARMUP_ITERATIONS
+      Warmup iterations for ARM64 backend (default: 1).
+  ARM64_OPT
+      ARM64 backend optimization flags (default: -O2).
+  ARM64_SPAWN_PER_CALL
+      Spawn process per ARM64 call instead of persistent ('1' or '0').
+  ARM64_PIPELINE
+      Use persistent pipelined runner for ARM64 ('1' or '0').
+  LLVM_WARMUP_ITERATIONS
+      Warmup iterations for LLVM backend (default: 1).
+  LLVM_SPAWN_PER_CALL
+      Spawn process per LLVM call instead of persistent ('1' or '0').
+  LLVM_PIPELINE
+      Use persistent pipelined runner for LLVM ('1' or '0').
+  LLVM_OPTS
+      Comma-separated Clang optimization levels for LLVM.
+  K_LLVM_IEEE_RUNTIME_MODE
+      LLVM runtime compilation mode for IEEE (default: fast).
+  K_LLVM_IEEE_CLANG_OPT
+      Clang optimization levels for IEEE LLVM (default: -O1).
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  PERF_FULL
+      Set to '1' to test multiple LLVM optimization levels
+      (-O0, -O1, -O2).
+  WASM_WARMUP_ITERATIONS
+      Warmup iterations for WebAssembly backend (default: 10).
+  WASM_RESET
+      Reset WebAssembly memory between iterations (default: 1).
+  WASM_PIPE
+      Use persistent subprocess for Wasm (default: 1, '0': in-process).
+  WASM_IN_PROCESS
+      Run WebAssembly in-process ('1' to enable).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 // Backend selection
 const backendsEnv = process.env.BACKENDS?.toLowerCase();
 const llvmOnly = process.env.LLVM_ONLY === "1" || backendsEnv === "llvm";

package/scripts/perf-int.mjs

@@ -56,6 +56,73 @@ import {
 import { compileARM64ArtifactFromObject } from "../backends/arm64/src/arm64.mjs";
 import { compileWasmArtifactFromObject } from "../backends/wasm/src/wasm.mjs";
 
+function printHelp() {
+  console.log(`Usage: node scripts/perf-int.mjs [options]
+
+Big Integer Arithmetic Performance Benchmark Harness.
+Benchmarks plus, minus, times, and squaring scale on arithmetics.k
+across Native JS, kVM interpreter, LLVM, Wasm, and ARM64 backends.
+
+Options:
+  --wasm-in-process
+      Run WebAssembly in-process instead of persistent subprocess runner.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BACKENDS
+      Target backend to run: 'llvm', 'wasm', or 'arm64'.
+  LLVM_ONLY
+      Run only LLVM backend ('1' to enable).
+  WASM_ONLY
+      Run only WebAssembly backend ('1' to enable).
+  ARM64_ONLY
+      Run only ARM64 backend ('1' to enable).
+  BACKENDS_ONLY
+      Skip JS and kVM interpreter baselines ('1' to enable).
+  INPUTS
+      Comma-separated integer strings to benchmark.
+  ITERATIONS
+      Measured iterations per benchmark (default: 3).
+  ARM64_WARMUP_ITERATIONS
+      Warmup iterations for ARM64 backend (default: 1).
+  ARM64_OPT
+      ARM64 backend optimization flags (default: -O2).
+  ARM64_SPAWN_PER_CALL
+      Spawn process per ARM64 call instead of persistent ('1' or '0').
+  ARM64_PIPELINE
+      Use persistent pipelined runner for ARM64 ('1' or '0').
+  LLVM_WARMUP_ITERATIONS
+      Warmup iterations for LLVM backend (default: 1).
+  LLVM_SPAWN_PER_CALL
+      Spawn process per LLVM call instead of persistent ('1' or '0').
+  LLVM_PIPELINE
+      Use persistent pipelined runner for LLVM ('1' or '0').
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  WASM_WARMUP_ITERATIONS
+      Warmup iterations for WebAssembly backend (default: 3).
+  WASM_RESET
+      Reset WebAssembly memory between iterations (default: 1).
+  WASM_PIPE
+      Use persistent subprocess for Wasm (default: 1, '0': in-process).
+  WASM_IN_PROCESS
+      Run WebAssembly in-process ('1' to enable).
+  SQUARING_INPUT
+      Initial integer for squaring benchmark (default: 987654321).
+  SQUARING_STEPS
+      Number of squaring steps (default: 10).
+  SQUARING_STEP_TIMEOUT_MS
+      Timeout per squaring step in milliseconds (default: 60000).
+  K_ARENA_CAPACITY_MB
+      Memory arena capacity in MB (default: 4096).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 // Backend selection
 const backendsEnv = process.env.BACKENDS?.toLowerCase();
 const llvmOnly = process.env.LLVM_ONLY === "1" || backendsEnv === "llvm";