@fraczak/k 6.10.3 → 6.10.4

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.4] — 2026-10-06 — Karatsuba Multiplication, Multi-Backend Harness, and CLI Help
+
+### Arithmetic & Algorithms
+
+- **Karatsuba Multiplication (`Examples/karatsuba-mult.k`)**:
+  - Implemented standalone, minimal Karatsuba integer multiplication with
+    asymptotic time complexity $O(n^{\log_2 3}) \approx O(n^{1.585})$.
+  - Utilizes unary counter (`$unat`) splitting with a 512-bit threshold
+    switching to grade-school multiplication (`times_bits`) for small
+    inputs.
+  - Implements direct bit-level arithmetic (`plus_bits`, `minus_bits`,
+    `times_bits`) and direct $2m$ bit shifting (`shift2_bits_u`).
+  - Added dedicated test suite in `tests/test-karatsuba.mjs` verifying
+    squaring cases and mixed-sign pair multiplications against BigInt
+    oracle.
+
+### Performance & Benchmarking
+
+- **Multiplication Performance Harness**
+  (`scripts/perf-multiplication.mjs`):
+  - Added multi-backend performance runner comparing `times` and
+    `karatsuba` across LLVM, Wasm, kVM, and JS engines.
+  - Supports `--mode squaring` (doubling bit width per step) and
+    `--mode sizes` (random operands of fixed bit lengths).
+  - Includes per-step timeout protection and process RSS memory guards.
+  - Added `npm run perf:mult` script in `package.json`.
+
+### CLI Usability & Backend Enhancements
+
+- **Unified `-h` and `--help` CLI Documentation**:
+  - Added comprehensive option and environment variable documentation
+    across all benchmark, performance, and test scripts in `scripts/`
+    and `backends/*/scripts/`.
+- **LLVM Direct `.kvm` Bytecode Compilation**:
+  - Added `compileKVMToExecutable` in `backends/llvm/src/executable.mjs`,
+    enabling direct binary compilation from lowered `.kvm` IR.
+- **Runtime Mark Compaction Fixes**:
+  - Updated LLVM runtime compaction tracking (`%k_rt_tail_mark`) to
+    accurately preserve base and last compaction arena marks in
+    tail loops.
+
+---
+
 ## [6.10.3] — 2026-10-04 — Unified File Formats Specification and Documentation Modernization
 
 ### Documentation & Core Architecture

package/DOCS/FILE_FORMATS.md

@@ -14,7 +14,7 @@ type-checked artifacts and JIT/native execution.
 | **`.k`**   | Human-readable source code         | UTF-8 plain text                                | Optional (trailing expression) | Editor, `k-decompile`             | `k.mjs`, `k-repl`, `k-compile`, backends                 |
 | **`.ko`**  | Executable compiled object         | Binary (`KOBJ\n` + JSON payload)                | **Required** (`"__main__"`)    | `k-compile`, REPL (`:ko`)         | `k.mjs`, `k-wasm-compile`, `k-llvm-build`, inspect tools  |
 | **`.klib`**| Reusable compiled library          | UTF-8 JSON payload                              | **None** (`null`)              | `k-compile --lib`, REPL (`:klib`) | REPL (`:load`), CLI linkers (`--lib`)                    |
-| **`.kvm`** | Polymorphic kVM bytecode template  | JSON / CBOR (`format: "k-vm", layer: "KVM-P"`)  | Per-relation functions         | `k-compile --format kvm`, kvm.mjs | kVM runtime, JIT specializer, `k-wasm-compile`           |
+| **`.kvm`** | Polymorphic kVM bytecode template  | JSON / CBOR (`format: "k-vm", layer: "KVM-P"`)  | Per-relation functions         | `k-compile --format kvm`, kvm.mjs | `kvm.mjs`, `k-wasm-compile`, `k-llvm-build`              |
 
 ### Format Transformation Workflow
 
@@ -63,6 +63,7 @@ flowchart TD
 
     %% Lowering from .kvm
     KVM -->|"k-wasm-compile"| WASM
+    KVM -->|"k-llvm-build"| NATIVE
     KVM -->|"kvm.mjs / specializeKVM"| INTERP
 ```
 
@@ -276,21 +277,38 @@ Export all currently loaded relations and types into a reusable library:
 `.kvm` is a polymorphic register-IR template artifact
 (`format: "k-vm"`, `layer: "KVM-P"`, `isPolymorphic: true`).
 
-#### How `.kvm` Differs from `.ko` and `.klib`:
-- **Abstraction Level:** `.ko` and `.klib` store high-level relational
-  expressions (KIR) and structural type graphs. In contrast, `.kvm` is
-  lowered into explicit register-based virtual machine instructions
-  (`alloc`, `make_variant`, `project_variant`, `union`, `call`, and
-  tail loops).
-- **Polymorphic Template vs. Fixed Object:**
-  - `.ko` is a concrete executable bound to an entrypoint (`main`).
-  - `.klib` is a library of high-level relation definitions for linking.
-  - `.kvm` stores compiled bytecode functions paired with principal
-    pattern graphs ($P_{in}, P_{out}$).
-- **Instant Specialization:** Instead of running the compiler's full
-  constraint-derivation engine, the runtime specializer (`specializeKVM`)
-  prunes dead union branches and folds redundant guards on-the-fly
-  against concrete input envelopes $(v, P_v)$.
+#### Why `.kvm` Exists (What You Gain):
+
+1. **Relational AST vs. Linear Register Machine:**
+   `.ko` and `.klib` store high-level relational combinators (compositions
+   `(f g)`, products `{a x, b y}`, unions `<f, g>`) and structural type
+   graphs. They contain no virtual registers, instruction sequences, or
+   control-flow branches. `.kvm` transforms this functional tree into a
+   linear 3-address virtual register machine IR (`alloc`, `project_field`,
+   `make_variant`, `project_variant`, `jump_if_fail`, `call`, and loops).
+
+2. **$1 \times N$ Backend Decoupling:**
+   Rather than having every code generator (LLVM, WebAssembly, ARM64,
+   and the JIT interpreter) independently lower the relational tree and
+   re-implement type-guided control flow, relational-to-imperative
+   lowering occurs once in `kvm.mjs`. All backends consume the exact same
+   ~10 linear kVM instructions (`kvm2llvm.mjs`, `kvm2wasm.mjs`,
+   `kvm2arm64.mjs`, `kvm.mjs`).
+
+3. **Microsecond Polymorphic Specialization (`layer: "KVM-P"`):**
+   In polymorphic programs, specializing `.ko` requires re-running the
+   compiler's full structural type derivation and constraint convergence
+   engine. A `.kvm` template stores pre-compiled register bytecode with
+   principal pattern graphs. The runtime specializer (`specializeKVM`)
+   prunes dead branches and folds redundant guards against concrete
+   runtime input envelopes $(v, P_v)$ in microseconds with zero AST
+   recompilation overhead.
+
+4. **Inspectable & Cacheable Register IR:**
+   `.kvm` produces a human- and machine-readable JSON or CBOR format.
+   You can inspect virtual register assignments, verify dead-branch
+   elimination, diff compiler output across runs, or cache the lowered IR
+   to bypass frontend compilation when building native or WASM targets.
 
 ### How to Generate
 
@@ -309,7 +327,24 @@ k-compile add5.ko add5.kvm
 
 ### How to Consume
 
+- **Direct lowering from `.kvm` to Native Binaries (`k-llvm-build`):**
+  Compile a `.kvm` template directly into a native executable:
+  ```bash
+  k-llvm-build add5.kvm add5-bin
+  echo "10" | ./codecs/int.mjs --parse | \
+    ./add5-bin | \
+    ./codecs/int.mjs --print
+  # Output: 15
+  ```
+
+- **Direct lowering from `.kvm` to LLVM IR (`k-llvm-compile`):**
+  Emit LLVM assembly directly from the register IR:
+  ```bash
+  k-llvm-compile add5.kvm add5.ll
+  ```
+
 - **Direct lowering from `.kvm` to WebAssembly (`k-wasm-compile`):**
+  Compile a `.kvm` template directly into a standalone `.wasm` module:
   ```bash
   k-wasm-compile add5.kvm add5.wasm
   echo "10" | ./codecs/int.mjs --parse | \

package/Examples/karatsuba-mult.k

@@ -0,0 +1,215 @@
+-- Karatsuba multiplication O(n^1.585)
+-- Self-contained and minimal implementation
+-- for arbitrary-precision integers
+
+$ yes_no = < {} yes, {} no >;
+yes = {} | yes $yes_no;
+no = {} | no $yes_no;
+
+$ bits = < {} _, bits 0, bits 1 >;
+0b = {} | _;
+0 = 0b |0;
+1 = 0b |1;
+
+$ unat = < {} _, unat 1 >;
+0u = {} | _ $unat;
+
+empty = $bits < /_ yes, no >;
+empty? = {empty /yes if, () then} .then;
+
+inv = {()x, 0b r} _inv;
+_inv = ${bits x, bits r}
+<
+  {.x empty? if, .r then} .then,
+  <
+    {.x /0 x, .r |0 r},
+    {.x /1 x, .r |1 r}
+  > _inv
+>;
+
+concat = ${bits x, bits y} {.x inv x, .y y} concat_;
+concat_ = ${bits x, bits y}
+<
+  {.x empty? if, .y then} .then,
+  <
+    {.x /0 x, .y |0 y},
+    {.x /1 x, .y |1 y}
+  > concat_
+>;
+
+remove_leading_zeros = < /0 remove_leading_zeros, () >;
+nat = remove_leading_zeros <empty? 0, ()>;
+
+$ int = < bits '+', bits '-' >;
+int = nat | '+' $int;
+abs = $int </'+', /'-'>;
+
+$ sign = < {} '+', {} '-' >;
+sign_plus = {} | '+' $sign;
+sign_minus = {} | '-' $sign;
+swap_sign = < /'+' | '-', /'-' | '+' >;
+
+$ carry = < {} 0, {} 1 >;
+c0 = {} | 0 $carry;
+c1 = {} | 1 $carry;
+
+_plus = {.x x, .y y, .c c, 0b r} _plus_;
+_plus_ = ${bits x, bits y, carry c, bits r}
+<
+  {.x empty? if, .y empty? and, .c/0 c, .r inv then} .then,
+  {.x empty? if, .y empty? and, {.r x, 1 r} _inv then} .then,
+  {.x empty? if, .c/0 and, {.r x, .y r} _inv then} .then,
+  <
+    {.x y, .y empty? x, .c c, .r r},
+    {<.c/0 0, 1> x, .y y, .x empty? c0 c, .r r},
+    {.x /0 x, .y /0 y, .c/0 c0 c, .r |0 r},
+    {.x /0 x, .y /0 y, .c/1 c0 c, .r |1 r},
+    {.x /0 x, .y /1 y, .c/0 c0 c, .r |1 r},
+    {.x /0 x, .y /1 y, .c/1 c1 c, .r |0 r},
+    {.x /1 x, .y /0 y, .c/0 c0 c, .r |1 r},
+    {.x /1 x, .y /0 y, .c/1 c1 c, .r |0 r},
+    {.x /1 x, .y /1 y, .c/0 c1 c, .r |0 r},
+    {.x /1 x, .y /1 y, .c/1 c1 c, .r |1 r}
+  > _plus_
+>;
+
+_minus = {.x x, .y y, .c c, 0b r} _minus_;
+_minus_ = ${bits x, bits y, carry c, bits r}
+<
+  {.y empty? if, .c/0 and, {.r x, .x r} _inv then} .then,
+  <
+    {.x/0 x, .y empty? y, .c/1 c1 c, .r |1 r},
+    {.x/1 x, .y empty? y, .c/1 c0 c, .r |0 r},
+    {.x/0 x, .y/0   y, .c/0 c0 c, .r |0 r},
+    {.x/0 x, .y/0   y, .c/1 c1 c, .r |1 r},
+    {.x/0 x, .y/1   y, .c/0 c1 c, .r |1 r},
+    {.x/0 x, .y/1   y, .c/1 c1 c, .r |0 r},
+    {.x/1 x, .y/0   y, .c/0 c0 c, .r |1 r},
+    {.x/1 x, .y/0   y, .c/1 c0 c, .r |0 r},
+    {.x/1 x, .y/1   y, .c/0 c0 c, .r |0 r},
+    {.x/1 x, .y/1   y, .c/1 c1 c, .r |1 r}
+  > _minus_
+>;
+
+plus_bits = ${bits x, bits y} {.x inv x, .y inv y, c0 c} _plus inv nat;
+minus_bits = ${bits x, bits y} {.x inv x, .y inv y, c0 c} _minus inv nat;
+
+_times = ${bits result, bits _x, bits y}
+<
+  {.y empty? if, .result then} .then,
+  <
+    {.result |0 result, ._x _x, .y /0 y},
+    {{._x x, .result |0 y, c0 c} _plus result, ._x _x, .y /1 y}
+  > _times
+>;
+times_bits = ${bits x, bits y} {0 result, .x inv _x, .y y} _times inv nat;
+
+unat_to_zeros = $unat < /_ 0b, /1 unat_to_zeros |0 > $bits;
+unat_to_double_zeros = $unat
+  < /_ 0b, /1 unat_to_double_zeros |0 |0 > $bits;
+
+_peel2 = < </0,/1> </0,/1>, </0,/1>, () >;
+_half_unat = ${bits x, bits y, unat m}
+<
+  {.x empty? if, .y empty? and, .m then} .then,
+  {.x _peel2 x, .y _peel2 y, .m |1 m} _half_unat
+>;
+half_unat = {.x x, .y y, 0u m} _half_unat;
+
+_split_rev_u = ${bits x_rev, unat m, bits low}
+<
+  {.m /_ if, {.low nat low, .x_rev inv nat high} then} .then,
+  {.x_rev empty? if, {.low nat low, 0 high} then} .then,
+  <
+    {.x_rev /0 x_rev, .m /1 m, .low |0 low},
+    {.x_rev /1 x_rev, .m /1 m, .low |1 low}
+  > _split_rev_u
+>;
+split_at = {.x inv x_rev, .m m, 0b low} _split_rev_u;
+
+at_least_256_u? = <
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1 /1
+  yes, no
+>;
+
+shift_bits_u = ${bits val, unat m}
+<
+  {.val empty? if, 0b then} .then,
+  {.val x, .m unat_to_zeros y} concat
+>;
+
+shift2_bits_u = ${bits val, unat m}
+<
+  {.val empty? if, 0b then} .then,
+  {.val x, .m unat_to_double_zeros y} concat
+>;
+
+_karatsuba = ${bits x, bits y}
+<
+  -- Base case: if m < 256 (< 512 bits), fall back to times_bits
+  {{.x x, .y y} half_unat m, .x x, .y y}
+  <
+    {
+      .m at_least_256_u? /no if,
+      {.x x, .y y} times_bits then
+    } .then,
+    -- Recursive Karatsuba:
+    {
+      {.x x, .m m} split_at sx,
+      {.y x, .m m} split_at sy,
+      .m m
+    }
+    {
+      {.sx.high x, .sy.high y} _karatsuba z2,
+      {.sx.low  x, .sy.low  y} _karatsuba z0,
+      {
+        {.sx.high x, .sx.low y} plus_bits x,
+        {.sy.high x, .sy.low y} plus_bits y
+      } _karatsuba z_sum,
+      .m m
+    }
+    {
+      .z2 z2,
+      .z0 z0,
+      {{.z_sum x, .z2 y} minus_bits x, .z0 y} minus_bits z1,
+      .m m
+    }
+    {
+      {.z2 val, .m m} shift2_bits_u z2_s,
+      {.z1 val, .m m} shift_bits_u  z1_s,
+      .z0 z0
+    }
+    {{.z2_s x, .z1_s y} plus_bits x, .z0 y} plus_bits
+  >
+>;
+
+karatsuba = ${int x, int y}
+{
+  <
+    {.x/'+' if, .y /'+' and} sign_plus,
+    {.x/'-' if, .y /'-' and} sign_plus,
+    sign_minus
+  > sign,
+  {.x abs x, .y abs y} _karatsuba result
+}
+<
+  {.sign/'+' if, .result int then} .then,
+  {.sign/'-' if, .result int swap_sign then} .then
+>;
+
+()

package/backends/arm64/scripts/run-tests.mjs

@@ -6,6 +6,22 @@ import { fileURLToPath } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const node = process.execPath;
+
+function printHelp() {
+  console.log(`Usage: node backends/arm64/scripts/run-tests.mjs [options]
+
+Runs ARM64 backend test suite and integration tests.
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 const tests = [
   ["tests/test-arm64.mjs", node, ["tests/test-arm64.mjs"]],
   ["tests/integration.sh", path.join(root, "tests/integration.sh"), []]

package/backends/llvm/bin/k-llvm-build.mjs

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
 
+import fs from "node:fs";
 import { argv, exit, stdin } from "node:process";
 import {
   compileProgramInputToObject,
   parseCompileOptions,
   resolveProgramInput
 } from "../src/cli.mjs";
-import { compileObjectToExecutable } from "../src/executable.mjs";
+import {
+  compileKVMToExecutable,
+  compileObjectToExecutable
+} from "../src/executable.mjs";
 
 function usage(stream = console.error) {
   const prog = argv[1] || "k-llvm-build.mjs";
   stream(`Usage: node ${prog} [options] [source-snippet | input-file [output-exe]]`);
-  stream("Compile k source, .ko, or .klib input into a native executable.");
+  stream("Compile k source, .ko, .klib, or .kvm input into a native executable.");
   stream("");
   stream("Arguments:");
   stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, or .klib file. Reads UTF-8 source from stdin when omitted.");
+  stream("  input-file      Source .k, .ko, .klib, or .kvm file. Reads UTF-8 source from stdin when omitted.");
   stream("  output-exe      Output executable path.");
   stream("");
   stream("The executable reads a binary k pattern+value envelope from stdin and");
@@ -24,11 +28,21 @@ function usage(stream = console.error) {
   stream("stdout is encoded with the compiled output pattern.");
   stream("");
   stream("Options:");
-  stream("  -o, --output path  Specify output file path explicitly.");
-  stream("  --lib file         Load one .klib dependency before compiling.");
-  stream("  --export spec      Export a library alias into source scope. May be repeated.");
-  stream("                     spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help         Show this help.");
+  stream("  -o, --output path        Specify output file path explicitly.");
+  stream("  --input-pattern pattern  Input pattern JSON or file path for specialization.");
+  stream("  --lib file               Load one .klib dependency before compiling.");
+  stream("  --export spec            Export a library alias into source scope. May be repeated.");
+  stream("                           spec is 'name' or 'libname:localname'.");
+  stream("  -h, --help               Show this help.");
+}
+
+function readMaybeFile(textOrPath) {
+  return fs.existsSync(textOrPath) ? fs.readFileSync(textOrPath, "utf8") : textOrPath;
+}
+
+function readPattern(inputPattern) {
+  if (inputPattern == null) return null;
+  return JSON.parse(readMaybeFile(inputPattern));
 }
 
 try {
@@ -39,6 +53,7 @@ try {
   }
 
   let explicitOutput = null;
+  let rawInputPattern = null;
   const remainingArgs = [];
   while (args.length > 0) {
     const arg = args[0];
@@ -46,11 +61,17 @@ try {
       args.shift();
       explicitOutput = args.shift();
       if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+    } else if (arg === "--input-pattern") {
+      args.shift();
+      rawInputPattern = args.shift();
+      if (!rawInputPattern) throw new Error("--input-pattern requires a JSON or file argument");
     } else {
       remainingArgs.push(args.shift());
     }
   }
 
+  const inputPattern = readPattern(rawInputPattern);
+
   const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
   const input = resolveProgramInput(remainingArgs, { allowStdinSource: true });
   const positionalOutput = remainingArgs.shift();
@@ -59,13 +80,18 @@ try {
   const outputPath = explicitOutput || positionalOutput || null;
   if (outputPath == null) throw new Error("Output executable path is required (pass output-exe or -o/--output)");
 
-  const object = await compileProgramInputToObject(input, {
-    libraries,
-    exportSpecs,
-    stdin
-  });
+  if (input.kind === "kvm") {
+    const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    compileKVMToExecutable(kvm, outputPath, { inputPattern });
+  } else {
+    const object = await compileProgramInputToObject(input, {
+      libraries,
+      exportSpecs,
+      stdin
+    });
 
-  compileObjectToExecutable(object, outputPath);
+    compileObjectToExecutable(object, outputPath, { inputPattern });
+  }
 } catch (error) {
   console.error(error.stack || error.message || String(error));
   usage();

package/backends/llvm/bin/k-llvm-compile.mjs

@@ -7,17 +7,20 @@ import {
   parseCompileOptions,
   resolveProgramInput
 } from "../src/cli.mjs";
-import { compileObjectToLLVM } from "../src/llvm.mjs";
+import {
+  compileObjectToLLVM,
+  compileLLVMArtifactFromKVM
+} from "../src/llvm.mjs";
 import { inputPatternForObjectRelation } from "../src/executable.mjs";
 
 function usage(stream = console.error) {
   const prog = argv[1] || "k-llvm-compile.mjs";
   stream(`Usage: node ${prog} [options] [source-snippet | input-file [output.ll]]`);
-  stream("Compile a k .ko/.klib object into prototype LLVM IR.");
+  stream("Compile a k .ko/.klib object, source, or .kvm input into prototype LLVM IR.");
   stream("");
   stream("Arguments:");
   stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, or .klib file. Reads UTF-8 source from stdin when omitted.");
+  stream("  input-file      Source .k, .ko, .klib, or .kvm file. Reads UTF-8 source from stdin when omitted.");
   stream("  output.ll       Output LLVM IR path. Writes to stdout when omitted.");
   stream("");
   stream("Options:");
@@ -55,16 +58,30 @@ try {
 
   const outputPath = explicitOutput || positionalOutput || null;
 
-  const object = await compileProgramInputToObject(input, {
-    libraries,
-    exportSpecs,
-    stdin
-  });
+  let llvm;
+  if (input.kind === "kvm") {
+    const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    const entry = kvm.entry || kvm.relation || "__main__";
+    const mainFunc = kvm.functions?.[entry];
+    const artifact = compileLLVMArtifactFromKVM(kvm, {
+      relation: entry,
+      inputPattern: mainFunc?.inputPattern || kvm.inputPattern,
+      outputPattern: mainFunc?.outputPattern || kvm.outputPattern
+    });
+    llvm = typeof artifact === "string" ? artifact : artifact.llvm;
+  } else {
+    const object = await compileProgramInputToObject(input, {
+      libraries,
+      exportSpecs,
+      stdin
+    });
 
-  const { llvm } = compileObjectToLLVM(object, {
-    relation: object.main,
-    inputPattern: inputPatternForObjectRelation(object, object.main)
-  });
+    const res = compileObjectToLLVM(object, {
+      relation: object.main,
+      inputPattern: inputPatternForObjectRelation(object, object.main)
+    });
+    llvm = res.llvm;
+  }
 
   if (outputPath == null) {
     stdout.write(llvm);

package/backends/llvm/runtime/krt.c

@@ -553,17 +553,17 @@ static void rt_rewind_and_free(k_rt *rt, k_rt_checkpoint mark) {
   rt->has_reusable_blocks = 0;
 }
 
-k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr) {
-  if (rt == NULL || root == NULL || mark_ptr == NULL) return root;
+k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_tail_mark *tm) {
+  if (rt == NULL || root == NULL || tm == NULL) return root;
 
-  size_t bytes = bytes_since_mark(rt, *mark_ptr);
+  size_t bytes = bytes_since_mark(rt, tm->last_mark);
   if (bytes < 4194304) {
     return root;
   }
 
-  if (!is_after_mark(rt, root, *mark_ptr)) {
-    rt_rewind_and_free(rt, *mark_ptr);
-    *mark_ptr = k_rt_mark(rt);
+  if (!is_after_mark(rt, root, tm->base_mark)) {
+    rt_rewind_and_free(rt, tm->base_mark);
+    tm->last_mark = tm->base_mark;
     return root;
   }
 
@@ -574,14 +574,14 @@ k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr) {
 
   k_fixup_list fixups = {NULL, 0, 0};
 
-  k_value *staged_root = copy_value(rt, root, &staging, &staging_used, &staging_cap, &fixups, *mark_ptr);
+  k_value *staged_root = copy_value(rt, root, &staging, &staging_used, &staging_cap, &fixups, tm->base_mark);
 
-  rt_rewind_and_free(rt, *mark_ptr);
+  rt_rewind_and_free(rt, tm->base_mark);
 
   if (staging_used == 0) {
     free(staging);
     if (fixups.offsets != NULL) free(fixups.offsets);
-    *mark_ptr = k_rt_mark(rt);
+    tm->last_mark = tm->base_mark;
     return staged_root;
   }
 
@@ -605,7 +605,7 @@ 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);
+  tm->last_mark = k_rt_mark(rt);
 
   return new_root;
 }

package/backends/llvm/runtime/krt.h

@@ -13,6 +13,11 @@ typedef struct {
   size_t used;
 } k_rt_checkpoint;
 
+typedef struct {
+  k_rt_checkpoint base_mark;
+  k_rt_checkpoint last_mark;
+} k_rt_tail_mark;
+
 typedef struct {
   const char *label;
   size_t label_length;
@@ -66,7 +71,7 @@ k_rt *k_rt_new(void);
 void k_rt_reset(k_rt *rt);
 k_rt_checkpoint k_rt_mark(k_rt *rt);
 void k_rt_rewind(k_rt *rt, k_rt_checkpoint mark);
-k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_checkpoint *mark_ptr);
+k_value *k_rt_compact(k_rt *rt, k_value *root, k_rt_tail_mark *mark_ptr);
 void *k_rt_alloc(k_rt *rt, size_t size);
 void k_rt_free(k_rt *rt);
 

package/backends/llvm/scripts/run-tests.mjs

@@ -6,6 +6,22 @@ import { fileURLToPath } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const node = process.execPath;
+
+function printHelp() {
+  console.log(`Usage: node backends/llvm/scripts/run-tests.mjs [options]
+
+Runs LLVM backend test suite, integration tests, and conformance suite.
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 const tests = [
   ["tests/test-llvm.mjs", node, ["tests/test-llvm.mjs"]],
   ["tests/integration.sh", path.join(root, "tests/integration.sh"), []],

package/backends/llvm/src/cli.mjs

@@ -135,7 +135,7 @@ export async function compileProgramInputToObject(
   } else if (input.kind === "ko" || input.kind === "klib") {
     object = decodeObject(fs.readFileSync(input.path));
   } else if (input.kind === "kvm") {
-    throw new Error("Compiling directly from .kvm to LLVM is not yet supported; use .k or .ko input.");
+    throw new Error("Input is already lowered to .kvm bytecode; use compileLLVMArtifactFromKVM or compileKVMToExecutable.");
   } else {
     throw new Error(`Unsupported input kind: ${input.kind}`);
   }