@fraczak/k 6.10.2 → 6.10.4

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/README.md

@@ -3,14 +3,15 @@
 **k is a small language for typed data transformations.**
 
 It describes data as algebraic shapes, programs as first-order partial
-functions, and runtime values as a binary `pattern + value` stream that can be
-parsed, transformed, printed, compiled, and inspected.
+functions, and runtime values as a binary `pattern + value` stream
+that can be parsed, transformed, printed, compiled, and inspected.
 
-Data descriptions and transformations share one syntax, so a k file can define
-both the shapes of values and the relations that move between them.
+Data descriptions and transformations share one syntax, so a k file can
+define both the shapes of values and the relations that move between them.
 
-k is experimental, but it already has a working parser, type-derivation engine,
-REPL, binary codec pipeline, object/library format, Node.js API, and test suite.
+k is experimental, but it already has a working parser, type-derivation
+engine, REPL, binary codec pipeline, object/library format, Node.js API,
+and test suite.
 
 ## Why k?
 
@@ -21,9 +22,10 @@ Many systems need to answer the same questions:
 - What does a program accept, produce, or reject?
 - Can this transformation be serialized, tested, reused, or inspected?
 
-k explores a compact answer: define algebraic data shapes, compose partial
-transformations over them, derive input/output patterns automatically, and move
-values across process boundaries with a canonical binary representation.
+k explores a compact answer: define algebraic data shapes, compose
+partial transformations over them, derive input/output patterns
+automatically, and move values across process boundaries with a canonical
+binary representation.
 
 That makes k interesting as a foundation for:
 
@@ -35,8 +37,8 @@ That makes k interesting as a foundation for:
 
 ## A Small Example
 
-k can define recursive data and transformations in the same file. Peano natural
-numbers are either `0` or one more than another natural number:
+k can define recursive data and transformations in the same file. Peano
+natural numbers are either `0` or one more than another natural number:
 
 ```k
 $ nat = < {} 0, nat +1 >;
@@ -49,8 +51,9 @@ add = $ { nat x, nat y } <
 >;
 ```
 
-`add` takes a product `{ x, y }`. If `x` has a `+1`, it moves that successor
-from `x` to `y` and recurses. When that no longer applies, it returns `y`.
+`add` takes a product `{ x, y }`. If `x` has a `+1`, it moves that
+successor from `x` to `y` and recurses. When that no longer applies, it
+returns `y`.
 
 In the REPL:
 
@@ -59,8 +62,8 @@ In the REPL:
 {}|0|+1|+1|+1 ?<X0 +1, {} 0>=X0
 ```
 
-That evaluates `2 + 1` to `3`: a value starts at `0`, and each `+1` tag adds
-one successor. The REPL also prints the inferred value envelope.
+That evaluates `2 + 1` to `3`: a value starts at `0`, and each `+1` tag
+adds one successor. The REPL also prints the inferred value envelope.
 
 ## Try It
 
@@ -69,7 +72,9 @@ one successor. The REPL also prints the inferred value envelope.
 Try k directly in your browser without installing anything:
 **[https://fraczak.github.io/k/](https://fraczak.github.io/k/)**
 
-The Web REPL is self-contained, powered by an in-process WebAssembly compiler and execution engine with built-in codecs, autocompletion, interactive input, and standard libraries.
+The Web REPL is self-contained, powered by an in-process WebAssembly
+compiler and execution engine with built-in codecs, autocompletion,
+interactive input, and standard libraries.
 
 ### From Source
 
@@ -121,8 +126,8 @@ $ byte = { bit 0, bit 1, bit 2, bit 3, bit 4, bit 5, bit 6, bit 7 };
 $ bits = < {} _, bits 0, bits 1 >;
 ```
 
-There are no built-in primitive values. The empty product `{}` is the only leaf
-in a non-recursive definition.
+There are no built-in primitive values. The empty product `{}` is the
+only leaf in a non-recursive definition.
 
 **Composable partial functions**
 
@@ -142,8 +147,9 @@ Core expressions are deliberately small:
 
 **Derived input/output patterns**
 
-k derives structural constraints for expressions. Those patterns become useful
-for diagnostics, REPL output, binary encoding, and object metadata.
+k derives structural constraints for expressions. Those patterns become
+useful for diagnostics, REPL output, binary encoding, and object
+metadata.
 
 **Binary-friendly runtime values**
 
@@ -163,15 +169,27 @@ k-print   # binary pattern+value stream -> textual value
 
 **Inspectable objects and libraries**
 
-k programs can be compiled into:
+`k` programs can be authored, compiled, and linked across four main
+file formats:
 
-- `.klib`: library objects
-- `.ko`: executable binary object containers
-- `.kvm`: specialized kVM backend artifacts
+- `.k`: human-readable source code defining algebraic types and relations.
+- `.klib`: ahead-of-time (AOT) type-checked library objects (`main: null`)
+  storing canonical relation definitions, type codes, and local aliases.
+- `.ko`: ahead-of-time (AOT) type-checked executable containers (`KOBJ\n`
+  magic header) with entrypoint `main: "__main__"`, skipping parsing and
+  type derivation at runtime.
+- `.kvm`: polymorphic register-IR template artifacts (`layer: "KVM-P"`)
+  carrying principal pattern graphs for instant runtime specialization
+  (`specializeKVM`).
 
-Object and library files keep canonical code/relation definitions, aliases,
-metadata, and type-derivation status. The `.kvm` output is a lowered backend
-artifact for inspection and execution experiments.
+In `k`, all relations and types are identified canonically by immutable
+content-addressed hashes (`@hash`). There is no global symbol namespace;
+friendly names (such as `plus`, `int`, or `5`) are local aliases stored
+in metadata. Similarly, there are no primitive numbers: numerical
+identifiers like `5` or `10` are nullary relations mapping `${} -> $bits`.
+
+For a detailed guide to all four formats, commands, and workflows, see
+[DOCS/FILE_FORMATS.md](DOCS/FILE_FORMATS.md).
 
 ## CLI Tour
 
@@ -215,20 +233,22 @@ artifact for inspection and execution experiments.
 | `k-llvm-build` / `k-llvm-compile` / `k-llvm-run` | Compile and run via LLVM backend |
 | `k-arm64` / `k-arm64-compile` / `k-arm64-run` | Compile and run via Linux ARM64 native backend |
 
-Installed binary names are `k-` plus the source basename without `.mjs`, except
-for `k.mjs` itself. Source names that already include `k-`, such as
-`codecs/k-parse.mjs`, keep that name.
+Installed binary names are `k-` plus the source basename without
+`.mjs`, except for `k.mjs` itself. Source names that already include
+`k-`, such as `codecs/k-parse.mjs`, keep that name.
 
 ## Backends
 
 Backends live under [`backends/`](backends/) as npm workspaces:
 
-- [`backends/wasm`](backends/wasm/) lowers typed k programs through kVM into
-  WebAssembly artifacts. Powers both the CLI REPL (`wasm-in-process`) and the standalone Web REPL.
-- [`backends/llvm`](backends/llvm/) lowers polymorphic kVM programs into LLVM IR and
-  compiled native test executables.
-- [`backends/arm64`](backends/arm64/) lowers polymorphic kVM programs directly into
-  standalone Linux ARM64 native executables without external compiler dependencies.
+- [`backends/wasm`](backends/wasm/) lowers typed k programs through kVM
+  into WebAssembly artifacts. Powers both the CLI REPL (`wasm-in-process`)
+  and the standalone Web REPL.
+- [`backends/llvm`](backends/llvm/) lowers polymorphic kVM programs into
+  LLVM IR and compiled native test executables.
+- [`backends/arm64`](backends/arm64/) lowers polymorphic kVM programs
+  directly into standalone Linux ARM64 native executables without external
+  compiler dependencies.
 
 All backends integrate with the compiler and binary codecs through
 [`backend-api.mjs`](backend-api.mjs).
@@ -255,8 +275,8 @@ console.log(annotated.compileStats);
 
 ## Project Status
 
-k is usable as an experimental language and toolkit, not a stable production
-platform yet.
+k is usable as an experimental language and toolkit, not a stable
+production platform yet.
 
 Working today:
 
@@ -266,7 +286,8 @@ Working today:
 - binary pattern+value codec
 - object and library files
 - Node.js API
-- regression tests for runtime, codecs, objects, hashes, and type derivation
+- regression tests for runtime, codecs, objects, hashes, and type
+  derivation
 
 Still evolving:
 
@@ -281,20 +302,24 @@ Still evolving:
 
 k is small enough to study, but there are several useful directions:
 
-- examples: schema transformations, codecs, protocol examples, teaching tasks
+- examples: schema transformations, codecs, protocol examples, teaching
+  tasks
 - documentation: tutorials, diagrams, and clearer language walkthroughs
-- tooling: formatter, editor integration, better diagnostics, REPL ergonomics
+- tooling: formatter, editor integration, better diagnostics, REPL
+  ergonomics
 - compiler work: optimization, object inspection, backend experiments
 - theory: normalization, equivalence, convergence, and pattern derivation
-- applications: hardware modeling, asynchronous/synchronous test pipelines,
+- applications: hardware modeling, asynchronous/synchronous pipelines,
   schema repositories, and data migration tooling
 
-If you are interested in languages, compilers, data modeling, formal methods,
-serialization, or teaching tools, there is room to shape the project.
+If you are interested in languages, compilers, data modeling, formal
+methods, serialization, or teaching tools, there is room to shape the
+project.
 
 ## Examples
 
-The [`Examples/`](Examples/) directory contains language demonstrations and standard libraries:
+The [`Examples/`](Examples/) directory contains language demonstrations
+and standard libraries:
 
 | File | Contents |
 | --- | --- |
@@ -307,13 +332,14 @@ The [`Examples/`](Examples/) directory contains language demonstrations and stan
 | `bnat.k` | Binary natural numbers |
 | `buda.k` | Compact relational data transformations |
 
-`list.k` is also useful as a focused demonstration of filters and patterns.
+`list.k` is also useful as a focused demonstration of filters and
+patterns.
 
-`ieee.k` is a complete IEEE-754 binary64 model built from bit-level types
-upward with hierarchical significand adders, including comparison and
-floating-point `add`, `sub`, `mul`, and `div` relations. Those public aliases
-return `{ result, flags }`; compose with `.result` when only the floating-point
-value is needed.
+`ieee.k` is a complete IEEE-754 binary64 model built from bit-level
+types upward with hierarchical significand adders, including comparison
+and floating-point `add`, `sub`, `mul`, and `div` relations. Those public
+aliases return `{ result, flags }`; compose with `.result` when only the
+floating-point value is needed.
 
 ## Development
 
@@ -331,8 +357,9 @@ npm run perf:int        # run integer arithmetic benchmark across backends
 npm run perf:ieee       # run IEEE-754 arithmetic benchmark across backends
 ```
 
-The test runner prints each test before execution and reports its elapsed time
-afterward. It stops immediately when a test fails. The suite covers:
+The test runner prints each test before execution and reports its
+elapsed time afterward. It stops immediately when a test fails.
+The suite covers:
 
 - core runtime and parser behavior
 - type derivation cases in `tests/code-derivation/`
@@ -345,14 +372,21 @@ afterward. It stops immediately when a test fails. The suite covers:
 
 ## Further Reading
 
+- [DOCS/FILE_FORMATS.md](DOCS/FILE_FORMATS.md) - guide to
+  .k, .ko, .klib, and .kvm file formats and workflows
 - [DOCS/DICTIONARY.md](DOCS/DICTIONARY.md) - concept names and terminology
 - [DOCS/REPL.md](DOCS/REPL.md) - interactive interpreter and codec details
-- [DOCS/WEB_REPL_REQUIREMENTS.md](DOCS/WEB_REPL_REQUIREMENTS.md) - Web REPL architecture and requirements
-- [DOCS/KVM_EXECUTION_MODEL.md](DOCS/KVM_EXECUTION_MODEL.md) - kVM execution model and bytecode design
-- [DOCS/TEXTUAL_VALUES.md](DOCS/TEXTUAL_VALUES.md) - textual boundary notation
+- [DOCS/WEB_REPL_REQUIREMENTS.md](DOCS/WEB_REPL_REQUIREMENTS.md) -
+  Web REPL architecture and requirements
+- [DOCS/KVM_EXECUTION_MODEL.md](DOCS/KVM_EXECUTION_MODEL.md) -
+  kVM execution model and bytecode design
+- [DOCS/TEXTUAL_VALUES.md](DOCS/TEXTUAL_VALUES.md) -
+  textual boundary notation
 - [DOCS/PATTERNS.md](DOCS/PATTERNS.md) - pattern representation
-- [DOCS/OBJECT_FILE_AND_PATTERN.md](DOCS/OBJECT_FILE_AND_PATTERN.md) - object format
-- [DOCS/PROFILING_AND_TRACING.md](DOCS/PROFILING_AND_TRACING.md) - execution phase tracing and function call profiling across backends
+- [DOCS/OBJECT_FILE_AND_PATTERN.md](DOCS/OBJECT_FILE_AND_PATTERN.md) -
+  object format and pattern encoding
+- [DOCS/PROFILING_AND_TRACING.md](DOCS/PROFILING_AND_TRACING.md) -
+  execution phase tracing and function call profiling across backends
 - [DOCS/CODECS.md](DOCS/CODECS.md) - writing external codecs
 - [codecs/README.md](codecs/README.md) - binary codec internals
 - [objects/README.md](objects/README.md) - object/library tools

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();