@fraczak/k 6.3.2 → 6.4.0

package/backends/llvm/tests/product-driver.c

@@ -0,0 +1,23 @@
+#include "krt.h"
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+  k_value *val_a = k_variant(rt, "A", unit);
+  k_value *val_b = k_variant(rt, "B", unit);
+  k_value *input = k_product(rt, 2);
+  k_product_set(input, "x", val_a);
+  k_product_set(input, "y", val_b);
+
+  k_result result = k_main(rt, input);
+  if (result.status != K_STATUS_OK) return 2;
+  if (k_product_get(result.value, "fieldA") != val_a) return 3;
+  if (k_product_get(result.value, "fieldB") != val_b) return 4;
+
+  k_rt_free(rt);
+  return 0;
+}

package/backends/llvm/tests/projection-driver.c

@@ -0,0 +1,19 @@
+#include "krt.h"
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+  k_value *input = k_product(rt, 1);
+  k_product_set(input, "x", unit);
+
+  k_result result = k_main(rt, input);
+  if (result.status != K_STATUS_OK) return 2;
+  if (result.value != unit) return 3;
+
+  k_rt_free(rt);
+  return 0;
+}

package/backends/llvm/tests/relation-driver.c

@@ -0,0 +1,29 @@
+#include "krt.h"
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+  k_value *left_value = k_variant(rt, "left", unit);
+  k_value *right_value = k_variant(rt, "right", unit);
+
+  k_value *a = k_product(rt, 1);
+  k_product_set(a, "x", left_value);
+  k_value *b = k_product(rt, 1);
+  k_product_set(b, "x", right_value);
+
+  k_value *input = k_product(rt, 2);
+  k_product_set(input, "a", a);
+  k_product_set(input, "b", b);
+
+  k_result result = k_main(rt, input);
+  if (result.status != K_STATUS_OK) return 2;
+  if (k_product_get(result.value, "left") != left_value) return 3;
+  if (k_product_get(result.value, "right") != right_value) return 4;
+
+  k_rt_free(rt);
+  return 0;
+}

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

@@ -0,0 +1,240 @@
+import assert from "node:assert";
+import { compileObjectBuffer, decodeObject } from "@fraczak/k/object.mjs";
+import { compileObjectToLLVM, emitLLVMModule, llvmIdentifier } from "../src/llvm.mjs";
+
+function kirP(body, { patternGraph = null } = {}) {
+  return {
+    format: "k-ir",
+    version: 1,
+    layer: "KIR-P",
+    sourceFormat: "test",
+    kind: "executable",
+    main: "__main__",
+    codes: {},
+    rels: {
+      __main__: {
+        inputPattern: 0,
+        outputPattern: 1,
+        typeDerivation: { status: "converged" },
+        ...(patternGraph ? { patternGraph } : {}),
+        body
+      }
+    },
+    relAlias: {},
+    compileStats: {},
+    meta: {}
+  };
+}
+
+const object = decodeObject(compileObjectBuffer("()", { source: "llvm-test.k" }));
+const { kir, relation, inputPattern, outputPattern, llvm } = compileObjectToLLVM(object, {
+  inputPattern: [["open-product", []]]
+});
+
+assert.equal(kir.layer, "KIR-P");
+assert.equal(kir.kind, "executable");
+assert.equal(kir.main, "__main__");
+assert.equal(relation, "__main__");
+assert.deepEqual(inputPattern, [["open-product", []]]);
+assert.deepEqual(outputPattern, [["open-product", []]]);
+assert(!("instanceKey" in kir));
+assert(!("callSites" in kir));
+assert.match(llvm, /^; k-llvm prototype artifact/m);
+assert.match(llvm, /@k_llvm_metadata = private unnamed_addr constant/);
+assert.match(llvm, /%k_rt_mark = type \{ ptr, i64 \}/);
+assert.match(llvm, /%k_result = type \{ i32, ptr \}/);
+assert.match(llvm, /declare %k_rt_mark @k_rt_mark\(ptr\)/);
+assert.match(llvm, /declare void @k_rt_rewind\(ptr, %k_rt_mark\)/);
+assert.match(llvm, /declare ptr @k_rt_alloc\(ptr, i64\)/);
+assert.match(llvm, /declare ptr @k_bit0\(ptr\)/);
+assert.match(llvm, /declare ptr @k_bit1\(ptr\)/);
+assert.match(llvm, /declare ptr @k_variant_borrowed_direct_n\(ptr, ptr, i64, ptr\)/);
+assert.match(llvm, /declare ptr @k_variant_unit_borrowed_n\(ptr, ptr, i64\)/);
+assert.match(llvm, /declare ptr @k_product_get_n\(ptr, ptr, i64\)/);
+assert.match(llvm, /declare ptr @k_product_get_at\(ptr, i64\)/);
+assert.match(llvm, /declare void @k_product_set_borrowed_n\(ptr, ptr, i64, ptr\)/);
+assert.match(llvm, /declare void @k_product_set_at\(ptr, i64, ptr, i64, ptr\)/);
+assert.match(llvm, /define %k_result @k_main\(ptr %rt, ptr %input\)/);
+assert.match(llvm, /insertvalue %k_result undef, i32 0, 0/);
+assert.match(llvm, /insertvalue %k_result %status\d+, ptr %input, 1/);
+
+const custom = emitLLVMModule(kir, { symbol: "rel name!" });
+assert.match(custom, /source_filename = "k-llvm:rel_name_"/);
+assert.equal(llvmIdentifier("a b/c"), "a_b_c");
+
+const filterLLVM = emitLLVMModule(kirP({
+  op: "comp",
+  items: [
+    {
+      op: "filter",
+      filter: ["closed-product", []],
+      patterns: [0, 0]
+    },
+    {
+      op: "code",
+      code: "@code",
+      patterns: [0, 0]
+    }
+  ],
+  patterns: [0, 0]
+}));
+assert.match(filterLLVM, /insertvalue %k_result %status\d+, ptr %input, 1/);
+assert.doesNotMatch(filterLLVM, /k_filter/);
+assert.doesNotMatch(filterLLVM, /k_code/);
+
+const projectionObject = decodeObject(compileObjectBuffer(".x", { source: "llvm-projection.k" }));
+const { llvm: projectionLLVM } = compileObjectToLLVM(projectionObject, {
+  inputPattern: [
+    ["closed-product", [["x", 1]]],
+    ["closed-product", []]
+  ]
+});
+assert.match(projectionLLVM, /load i32, ptr %product_kind_slot\d+/);
+assert.match(projectionLLVM, /load ptr, ptr %product_fields_ptr_slot\d+/);
+assert.doesNotMatch(projectionLLVM, /call ptr @k_product_get_at\(ptr %(?:input|tail_input), i64 0\)/);
+
+const productObject = decodeObject(compileObjectBuffer("{ .x fieldA, .y fieldB }", { source: "llvm-product.k" }));
+const { llvm: productLLVM } = compileObjectToLLVM(productObject, {
+  inputPattern: [
+    ["closed-product", [["x", 1], ["y", 2]]],
+    ["closed-product", [["valA", 1]]],
+    ["closed-product", [["valB", 2]]]
+  ]
+});
+assert.match(productLLVM, /store i32 1, ptr %i32_slot\d+/);
+assert.match(productLLVM, /store i64 2, ptr %i64_slot\d+/);
+assert.match(productLLVM, /store ptr %product_fields\d+, ptr %ptr_slot\d+/);
+assert.doesNotMatch(productLLVM, /call ptr @k_product\(ptr %rt/);
+assert.doesNotMatch(productLLVM, /call void @k_product_set_at\(ptr %product\d+/);
+
+const variantObject = decodeObject(compileObjectBuffer("|tag", { source: "llvm-variant.k" }));
+const { llvm: variantLLVM } = compileObjectToLLVM(variantObject, {
+  inputPattern: [["closed-product", []]]
+});
+assert.match(variantLLVM, /call ptr @k_rt_alloc\(ptr %rt, i64 40\)/);
+assert.match(variantLLVM, /store i32 2, ptr %i32_slot\d+/);
+assert.match(variantLLVM, /store ptr %(?:input|tail_input), ptr %ptr_slot\d+/);
+assert.doesNotMatch(variantLLVM, /call ptr @k_variant_borrowed_direct_n\(ptr %rt/);
+
+const variantProjectionObject = decodeObject(compileObjectBuffer("/tag", { source: "llvm-variant-projection.k" }));
+const { llvm: variantProjectionLLVM } = compileObjectToLLVM(variantProjectionObject, {
+  inputPattern: [
+    ["closed-union", [["tag", 1]]],
+    ["closed-product", []]
+  ]
+});
+assert.match(variantProjectionLLVM, /load i32, ptr %tag_kind_slot\d+/);
+assert.match(variantProjectionLLVM, /icmp eq i64 %tag_length\d+, 3/);
+assert.match(variantProjectionLLVM, /load i8, ptr %tag_byte_ptr\d+/);
+assert.match(variantProjectionLLVM, /load ptr, ptr %payload_slot\d+/);
+assert.doesNotMatch(variantProjectionLLVM, /call i32 @k_variant_tag_matches\(ptr %(?:input|tail_input)/);
+assert.doesNotMatch(variantProjectionLLVM, /call ptr @k_variant_payload\(ptr %(?:input|tail_input)\)/);
+
+const bitLLVM = emitLLVMModule(kirP({
+  op: "comp",
+  items: [
+    { op: "product", fields: [], patterns: [0, 1] },
+    { op: "vid", tag: "1", patterns: [1, 2] }
+  ],
+  patterns: [0, 2]
+}, {
+  patternGraph: {
+    nodes: [
+      { id: 0, kind: "closed-product", edges: [] },
+      { id: 1, kind: "closed-product", edges: [] },
+      { id: 2, kind: "closed-union", edges: [{ label: "1", target: 1 }] }
+    ]
+  }
+}));
+assert.match(bitLLVM, /load ptr, ptr %rt_bit1_slot\d+/);
+assert.match(bitLLVM, /store ptr %raw_alloc\d+, ptr %rt_bit1_slot\d+/);
+assert.doesNotMatch(bitLLVM, /call ptr @k_bit1\(ptr %rt\)/);
+assert.doesNotMatch(bitLLVM, /call ptr @k_unit\(ptr %rt\)/);
+assert.doesNotMatch(bitLLVM, /call ptr @k_variant_borrowed_n\(ptr %rt/);
+
+const unitVariantLLVM = emitLLVMModule(kirP({
+  op: "comp",
+  items: [
+    { op: "product", fields: [], patterns: [0, 1] },
+    { op: "vid", tag: "nil", patterns: [1, 2] }
+  ],
+  patterns: [0, 2]
+}, {
+  patternGraph: {
+    nodes: [
+      { id: 0, kind: "closed-product", edges: [] },
+      { id: 1, kind: "closed-product", edges: [] },
+      { id: 2, kind: "closed-union", edges: [{ label: "nil", target: 1 }] }
+    ]
+  }
+}));
+assert.match(unitVariantLLVM, /load ptr, ptr %rt_unit_slot\d+/);
+assert.match(unitVariantLLVM, /store ptr %raw_alloc\d+, ptr %rt_unit_slot\d+/);
+assert.doesNotMatch(unitVariantLLVM, /call ptr @k_unit\(ptr %rt\)/);
+assert.match(unitVariantLLVM, /call ptr @k_rt_alloc\(ptr %rt, i64 40\)/);
+assert.doesNotMatch(unitVariantLLVM, /call ptr @k_variant_unit_borrowed_n\(ptr %rt/);
+
+const compositionObject = decodeObject(compileObjectBuffer("(.x .y)", { source: "llvm-composition.k" }));
+const { llvm: compositionLLVM } = compileObjectToLLVM(compositionObject, {
+  inputPattern: [
+    ["closed-product", [["x", 1]]],
+    ["closed-product", [["y", 2]]],
+    ["closed-product", []]
+  ]
+});
+assert.match(compositionLLVM, /load ptr, ptr %product_fields_ptr_slot\d+/);
+assert.doesNotMatch(compositionLLVM, /call ptr @k_product_get_at\(ptr %(?:input|tail_input), i64 0\)/);
+assert.doesNotMatch(compositionLLVM, /call ptr @k_product_get_at\(ptr %field\d+, i64 0\)/);
+
+const relationObject = decodeObject(compileObjectBuffer("pick = .x; {.a pick left, .b pick right}", { source: "llvm-relation.k" }));
+const { llvm: relationLLVM } = compileObjectToLLVM(relationObject, {
+  inputPattern: [
+    ["open-product", [["a", 1], ["b", 2]]],
+    ["open-product", [["x", 3]]],
+    ["open-product", [["x", 4]]],
+    ["closed-product", []],
+    ["closed-product", []]
+  ]
+});
+assert.match(relationLLVM, /define internal %k_result @k_rel_pick_\d+\(ptr %rt, ptr %input\)/);
+assert.match(relationLLVM, /call %k_result @k_rel_pick_\d+\(ptr %rt, ptr %field_value\d+\)/);
+assert.match(relationLLVM, /extractvalue %k_result %call\d+, 0/);
+assert.match(relationLLVM, /extractvalue %k_result %call\d+, 1/);
+
+const emptyLLVM = emitLLVMModule(kirP({
+  op: "empty",
+  patterns: [0, 1]
+}));
+assert.match(emptyLLVM, /insertvalue %k_result undef, i32 1, 0/);
+
+const unionObject = decodeObject(compileObjectBuffer("< /x |left, /y |right >", { source: "llvm-union.k" }));
+const { llvm: unionLLVM } = compileObjectToLLVM(unionObject, {
+  inputPattern: [
+    ["closed-union", [["x", 1], ["y", 2]]],
+    ["closed-product", []],
+    ["closed-product", []]
+  ]
+});
+assert.match(unionLLVM, /define internal %k_result @k_union_arm_0\(ptr %rt, ptr %input\)/);
+assert.match(unionLLVM, /define internal %k_result @k_union_arm_1\(ptr %rt, ptr %input\)/);
+assert.match(unionLLVM, /call %k_result @k_union_arm_0\(ptr %rt, ptr %input\)/);
+assert.match(unionLLVM, /call %k_result @k_union_arm_1\(ptr %rt, ptr %input\)/);
+assert.match(unionLLVM, /load ptr, ptr %mark_block_slot\d+/);
+assert.match(unionLLVM, /%rewind_fast_ok\d+ = and i1 %rewind_has_mark\d+, %rewind_same_block\d+/);
+assert.match(unionLLVM, /call void @k_rt_rewind\(ptr %rt, %k_rt_mark %mark\d+\)/);
+
+const nestedUnionObject = decodeObject(compileObjectBuffer("{ < /x |left, /y |right > z }", { source: "llvm-nested-union.k" }));
+const { llvm: nestedUnionLLVM } = compileObjectToLLVM(nestedUnionObject, {
+  inputPattern: [
+    ["closed-union", [["x", 1], ["y", 2]]],
+    ["closed-product", []],
+    ["closed-product", []]
+  ]
+});
+assert.match(nestedUnionLLVM, /define internal %k_result @k_union_expr_\d+\(ptr %rt, ptr %input\)/);
+assert.match(nestedUnionLLVM, /call %k_result @k_union_expr_\d+\(ptr %rt, ptr %(?:input|tail_input)\)/);
+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/);
+
+console.log("OK");

package/backends/llvm/tests/union-driver.c

@@ -0,0 +1,31 @@
+#include "krt.h"
+
+#include <string.h>
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+static int expect_tag(k_result result, const char *tag, k_value *payload) {
+  if (result.status != K_STATUS_OK) return 1;
+  if (strcmp(k_variant_tag(result.value), tag) != 0) return 2;
+  if (k_variant_payload(result.value) != payload) return 3;
+  return 0;
+}
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+
+  k_value *x = k_variant(rt, "x", unit);
+  if (expect_tag(k_main(rt, x), "left", unit) != 0) return 2;
+
+  k_value *y = k_variant(rt, "y", unit);
+  if (expect_tag(k_main(rt, y), "right", unit) != 0) return 3;
+
+  k_value *z = k_variant(rt, "z", unit);
+  if (k_main(rt, z).status == K_STATUS_OK) return 4;
+
+  k_rt_free(rt);
+  return 0;
+}

package/backends/llvm/tests/variant-driver.c

@@ -0,0 +1,19 @@
+#include "krt.h"
+
+#include <string.h>
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+  k_result result = k_main(rt, unit);
+  if (result.status != K_STATUS_OK) return 2;
+  if (strcmp(k_variant_tag(result.value), "tag") != 0) return 3;
+  if (k_variant_payload(result.value) != unit) return 4;
+
+  k_rt_free(rt);
+  return 0;
+}

package/backends/llvm/tests/variant-projection-driver.c

@@ -0,0 +1,21 @@
+#include "krt.h"
+
+extern k_result k_main(k_rt *rt, k_value *input);
+
+int main(void) {
+  k_rt *rt = k_rt_new();
+  if (rt == NULL) return 1;
+
+  k_value *unit = k_unit(rt);
+  k_value *matching = k_variant(rt, "tag", unit);
+  k_result result = k_main(rt, matching);
+  if (result.status != K_STATUS_OK) return 2;
+  if (result.value != unit) return 3;
+
+  k_value *other = k_variant(rt, "other", unit);
+  k_result mismatch = k_main(rt, other);
+  if (mismatch.status == K_STATUS_OK) return 4;
+
+  k_rt_free(rt);
+  return 0;
+}

package/backends/wasm/DOCS/USE-WEB-ASSEMBLY.md

@@ -0,0 +1,233 @@
+# Using WebAssembly
+
+The experimental WebAssembly backend can compile a k program into a binary
+`.wasm` artifact and run that artifact later without loading the original k
+source. It uses the same binary `pattern + value` streams as the normal `k`
+runtime, so the existing codecs remain the pipeline boundaries.
+
+## Install the Commands
+
+From the monorepo root:
+
+```bash
+npm install
+cd backends/wasm
+npm link
+```
+
+This installs three commands:
+
+| Command | Purpose |
+| --- | --- |
+| `k-wasm` | Compile k source, `.ko`, or `.kvm` input in memory and run it immediately |
+| `k-wasm-compile` | Compile k source, `.ko`, or `.kvm` input into a standalone `.wasm` artifact |
+| `k-wasm-run` | Run a previously compiled `.wasm` artifact |
+
+The same tools can be called directly from a checkout with
+`node ./bin/k-wasm.mjs`, `node ./bin/k-wasm-compile.mjs`, and
+`node ./bin/k-wasm-run.mjs`.
+
+## Compile and Run a Source File
+
+A source file must end with the expression that becomes its entry point:
+
+```k
+|ok
+```
+
+Compile it:
+
+```bash
+k-wasm-compile program.k program.wasm
+```
+
+Run it over a binary input stream:
+
+```bash
+k-unit --parse |
+  k-wasm-run program.wasm |
+  k-print
+```
+
+Expected output:
+
+```json
+"ok"
+```
+
+The `.wasm` artifact is a standard WebAssembly binary module:
+
+```bash
+file program.wasm
+```
+
+It can be stored or transferred as one file. The runner does not need
+`program.k` after compilation.
+
+## Compile an Expression
+
+For a small program, pass a k expression directly:
+
+```bash
+k-wasm-compile '|ok' program.wasm
+```
+
+The `k-wasm` convenience command performs compilation and execution in one
+process:
+
+```bash
+k-unit --parse |
+  k-wasm '|ok' |
+  k-print
+```
+
+For compile inputs, existing paths are read as files. Missing names with
+`.k`, `.ko`, `.kvm`, `.klib`, or `.wasm` extensions are reported as missing
+files; other arguments are interpreted as inline source snippets.
+
+## Read Input from a File
+
+Both runners accept an optional binary input file:
+
+```bash
+k-unit --parse > input.kv
+k-wasm-run program.wasm input.kv > output.kv
+k-print < output.kv
+```
+
+The one-step command has the same input-file form:
+
+```bash
+k-wasm program.k input.kv > output.kv
+```
+
+## Compile from k Objects or kVM
+
+`k-wasm-compile` can consume the object and kVM outputs produced by
+`k-compile`:
+
+```bash
+k-compile program.k program.ko
+k-wasm-compile program.ko program.wasm
+
+k-compile program.k program.kvm
+k-wasm-compile program.kvm program.wasm
+```
+
+Use `.ko` when you want to preserve the compiled object form for the normal k
+toolchain. Use `.kvm` when you want to inspect or cache the lowered kVM program
+before producing WebAssembly.
+
+## Compile with Libraries
+
+`k-wasm-compile` and `k-wasm` accept one `--lib` option before the program.
+Use repeated `--export` options to bring aliases from that library into the
+source scope. The export spec is `name` or `libname:localname`.
+
+For a library that defines `transform`:
+
+```bash
+k-compile library.k library.klib
+k-wasm-compile --lib library.klib --export transform 'transform' program.wasm
+k-parse |
+  k-wasm-run program.wasm |
+  k-print
+```
+
+The `.klib` file is required while compiling the artifact. It is not required
+when running the resulting `.wasm` file.
+
+## Profile IEEE Execution
+
+The comparative IEEE benchmark moved with the backend:
+
+```bash
+npm run perf:ieee
+```
+
+To isolate WebAssembly execution and report arena allocation statistics:
+
+```bash
+WASM_ONLY=1 WASM_PROFILE=1 ITERATIONS=3 npm run perf:ieee
+```
+
+Set `WASM_RESET=0` to reproduce retained-arena growth and
+`WASM_WARMUP_ITERATIONS=0` to include cold-start behavior.
+
+## What the Artifact Contains
+
+`k-wasm-compile` produces one WebAssembly binary module. The module contains:
+
+- the bump-allocator runtime from [`runtime.wat`](../runtime.wat)
+- one WebAssembly function for each reachable k relation
+- the exported `rel___main__` entry point
+- a WebAssembly custom section named `k.metadata`
+
+The custom section stores runner metadata:
+
+| Field | Meaning |
+| --- | --- |
+| `format` | Artifact family, currently `k-wasm` |
+| `version` | Artifact format version, currently `1` |
+| `abi` | Runtime ABI, currently `arena-v1` |
+| `entry` | Exported WebAssembly function called by the runner |
+| `inputPattern` | Pattern graph used to serialize the input into the arena |
+| `outputPattern` | Pattern graph used to decode the output from the arena |
+| `tags` | Stable integer IDs assigned to statically known variant tags |
+
+Embedding metadata in a custom section keeps the artifact self-contained.
+Unknown WebAssembly engines ignore custom sections, while `k-wasm-run` reads
+the section with `WebAssembly.Module.customSections(...)`.
+
+## Compilation Pipeline
+
+Compilation follows these steps:
+
+1. Resolve the input as inline source, a source file, a `.ko` object, or a
+   `.kvm` program.
+2. For source input, parse and annotate the source, including any loaded
+   `.klib` dependencies and `--export` aliases.
+3. For `.ko` input, use the hydrated relation definitions directly.
+4. For `.kvm` input, use the already-lowered kVM functions directly.
+5. Lower each reachable kVM function to WebAssembly text.
+6. Combine the generated functions with `runtime.wat`.
+7. Use WABT to validate the text and emit a binary WebAssembly module.
+8. Append the `k.metadata` custom section to the binary module.
+
+The implementation lives in [`src/wasm.mjs`](../src/wasm.mjs). The command-line
+wrappers are [`k-wasm-compile.mjs`](../bin/k-wasm-compile.mjs),
+[`k-wasm-run.mjs`](../bin/k-wasm-run.mjs), and
+[`k-wasm.mjs`](../bin/k-wasm.mjs).
+
+## Execution Pipeline
+
+`k-wasm-run` performs these steps:
+
+1. Load and compile the `.wasm` module with Node.js `WebAssembly.compile(...)`.
+2. Read and validate the `k.metadata` custom section.
+3. Decode the input `pattern + value` stream.
+4. Serialize the input tree into the module's linear-memory arena.
+5. Call the artifact entry point with the input arena pointer.
+6. Decode the returned arena pointer under the stored output pattern.
+7. Write the result as a binary `pattern + value` stream.
+
+The WebAssembly entry-point ABI is:
+
+```text
+(param input_pointer i32) -> (result output_pointer i32, ok i32)
+```
+
+An `ok` result of `1` means that the partial function produced a value. A
+result of `0` means that the k relation was undefined for that input.
+
+## Current Limitations
+
+- The artifact is a WebAssembly module, not a native executable. It still needs
+  a host runner that understands k binary streams and the `k.metadata` section.
+- `k-wasm-run` currently targets Node.js. A browser runner can use the same
+  artifact contract but has not been added yet.
+- `.klib` files are compile-time dependencies, not standalone WebAssembly
+  inputs. Load them with `--lib` and compile source, `.ko`, or `.kvm` input with
+  a main relation.
+- The backend is experimental. Use `k` as the general-purpose runtime while
+  WebAssembly pattern coverage and optimization continue to evolve.