@fraczak/k 7.0.1 → 7.1.0

package/DOCS/PROFILING_AND_TRACING.md

@@ -5,7 +5,6 @@ and function-level call profiling infrastructure for `k` backends.
 
 The profiling framework allows fine-grained performance analysis of polymorphic `k`
 programs across multiple execution targets:
-- **Linux ARM64** (native standalone ELF executable via direct kVM assembly emission)
 - **WebAssembly** (in-process Wasm module via single-pass kVM lowering)
 - **LLVM** (native specialized executable via KIR-P lowering)
 - **kVM Interpreter** (in-process TypeScript/JavaScript kVM evaluator)
@@ -15,17 +14,23 @@ programs across multiple execution targets:
 
 ## 1. Motivation: Apples-to-Apples Backend Comparison
 
-When measuring end-to-end request latency across backends, wall-clock time can be
-dominated by factors outside the core relation algorithm:
-- **Process IPC**: Out-of-process native executables (ARM64, LLVM) communicate via stdin/stdout pipes, incurring OS context switches and pipe buffer copies.
-- **Wire Codec**: Decoding and validating the binary wire format (`pattern + value`) and encoding the response.
-- **In-Memory Representation**: WebAssembly converts incoming values into a flat linear memory arena layout.
-- **Pure Evaluation**: The actual relational instruction loop performing the algorithm.
-
-Without detailed accounting, native ARM64 or LLVM binaries communicating over pipes can
-appear slower than in-process WebAssembly or the interpreter simply because of IPC overhead.
-The tracing infrastructure breaks request latency down into nanosecond-level phases so that
-pure execution time can be measured and compared directly.
+When measuring end-to-end request latency across backends, wall-clock
+time can be dominated by factors outside the core relation algorithm:
+- **Process IPC**: Out-of-process native executables (LLVM)
+  communicate via stdin/stdout pipes, incurring OS context switches and
+  pipe buffer copies.
+- **Wire Codec**: Decoding and validating the binary wire format
+  (`pattern + value`) and encoding the response.
+- **In-Memory Representation**: WebAssembly converts incoming values into
+  a flat linear memory arena layout.
+- **Pure Evaluation**: The actual relational instruction loop performing
+  the algorithm.
+
+Without detailed accounting, native LLVM binaries communicating over
+pipes can appear slower than in-process WebAssembly or the interpreter
+simply because of IPC overhead. The tracing infrastructure breaks
+request latency down into nanosecond-level phases so that pure
+execution time can be measured and compared directly.
 
 In addition, **per-function invocation profiling** verifies that every backend performs the
 exact same number of relational evaluations and loop iterations for a given input.
@@ -56,37 +61,41 @@ Following `k`'s canonical content-addressed design:
 
 When tracing is enabled, each request is instrumented to measure 7 discrete phases with nanosecond precision:
 
-| Phase | Description | Linux ARM64 | LLVM | WebAssembly | kVM Interp |
-| :--- | :--- | :---: | :---: | :---: | :---: |
-| **1. IPC Read (Pipe In)** | Waiting for and reading input payload from stdin | Yes | Yes | N/A (in-process) | N/A (in-process) |
-| **2. Wire Decode & Validate** | Decoding wire buffer and validating against pattern | Yes | Yes | N/A (in-process) | N/A (in-process) |
-| **3. Flat Input Prep (Arena)** | Flattening decoded structures into linear arena memory | Yes | N/A | Yes | N/A |
-| **4. Pure Evaluation** | Core relational execution loop | **Yes** | **Yes** | **Yes** | **Yes** |
-| **5. Flat Output Prep (Arena)** | Serializing/reading in-memory representations | Yes | N/A | Yes | N/A |
-| **6. Wire Encode** | Encoding result to canonical wire format | Yes | Yes | N/A (in-process) | N/A (in-process) |
-| **7. IPC Write (Pipe Out)** | Writing output wire bytes to stdout pipe | Yes | Yes | Yes (driver) | N/A |
+| Phase | Description | LLVM | WebAssembly | kVM Interp |
+| :--- | :--- | :---: | :---: | :---: |
+| **1. IPC Read (Pipe In)** | Waiting for and reading input payload from stdin | Yes | N/A (in-process) | N/A (in-process) |
+| **2. Wire Decode & Validate** | Decoding wire buffer and validating against pattern | Yes | N/A (in-process) | N/A (in-process) |
+| **3. Flat Input Prep (Arena)** | Flattening decoded structures into linear arena memory | N/A | Yes | N/A |
+| **4. Pure Evaluation** | Core relational execution loop | **Yes** | **Yes** | **Yes** |
+| **5. Flat Output Prep (Arena)** | Serializing/reading in-memory representations | N/A | Yes | N/A |
+| **6. Wire Encode** | Encoding result to canonical wire format | Yes | N/A (in-process) | N/A (in-process) |
+| **7. IPC Write (Pipe Out)** | Writing output wire bytes to stdout pipe | Yes | Yes (driver) | N/A |
 
 ### Phase Timing Output Example
 
 ```text
 --- Operation: reverse (len 40) ---
-Phase                    | Linux ARM64   | LLVM          | WebAssembly   | kVM Interp
--------------------------+---------------+---------------+---------------+---------------
-1. IPC Read (Pipe In)    |    169.83 µs  |    161.42 µs  |       -       |       -     
-2. Wire Decode & Validate |      2.04 µs  |      1.58 µs  |       -       |       -     
-3. Flat Input Prep (Arena) |      3.08 µs  |       -       |     80.88 µs  |       -     
-4. Pure Evaluation       |      0.46 µs  |      0.54 µs  |      1.71 µs  |     26.04 µs
-5. Flat Output Prep (Arena) |      2.67 µs  |       -       |     76.71 µs  |       -     
-6. Wire Encode           |      1.96 µs  |      4.88 µs  |       -       |       -     
-7. IPC Write (Pipe Out)  |     11.29 µs  |     11.08 µs  |      0.62 µs  |       -     
--------------------------+---------------+---------------+---------------+---------------
-Total Request Time       |    191.33 µs  |    179.50 µs  |    159.92 µs  |     26.04 µs
+Phase                    | LLVM          | WebAssembly   | kVM Interp
+-------------------------+---------------+---------------+---------------
+1. IPC Read (Pipe In)    |    161.42 µs  |       -       |       -     
+2. Wire Decode & Validate |      1.58 µs  |       -       |       -     
+3. Flat Input Prep (Arena) |       -       |     80.88 µs  |       -     
+4. Pure Evaluation       |      0.54 µs  |      1.71 µs  |     26.04 µs
+5. Flat Output Prep (Arena) |       -       |     76.71 µs  |       -     
+6. Wire Encode           |      4.88 µs  |       -       |       -     
+7. IPC Write (Pipe Out)  |     11.08 µs  |      0.62 µs  |       -     
+-------------------------+---------------+---------------+---------------
+Total Request Time       |    179.50 µs  |    159.92 µs  |     26.04 µs
 ```
 
 **Key Takeaways**:
-- **Pure evaluation** in Linux ARM64 native code (`0.46 µs`) is ~3.7× faster than WebAssembly (`1.71 µs`) and ~56× faster than the interpreter (`26.04 µs`).
-- **End-to-end request time** for native binaries is dominated by pipe IPC read (`~160–170 µs`).
-- **WebAssembly overhead** is concentrated in flat arena conversion (`~80 µs` in, `~76 µs` out).
+- **Pure evaluation** in LLVM native code (`0.54 µs`) is ~3.2× faster
+  than WebAssembly (`1.71 µs`) and ~48× faster than the interpreter
+  (`26.04 µs`).
+- **End-to-end request time** for native binaries is dominated by pipe
+  IPC read (`~160 µs`).
+- **WebAssembly overhead** is concentrated in flat arena conversion
+  (`~80 µs` in, `~76 µs` out).
 
 ---
 
@@ -100,22 +109,20 @@ every backend executes the exact same call path.
 
 ```text
   Function Call Profile: reverse
-  Function Name            | Linux ARM64 Calls | WebAssembly Calls | kVM Interp Calls
-  -------------------------+-------------------+-------------------+------------------
-  reverse                  |                 - |                 1 |                1
-  _reverse                 |                 - |                41 |               41
-  @dhiaXnh7AYZnewyvbXdh... |                 1 |                 - |                -
-  @EwQ2P3yZ8v4z2qA7kF...   |                41 |                 - |                -
-  car                      |                40 |                40 |               40
-  cdr                      |                40 |                40 |               40
-  cons                     |                40 |                40 |               40
-  nil                      |                 1 |                 1 |                1
-  -------------------------+-------------------+-------------------+------------------
-  Total Calls              |               163 |               163 |              163
+  Function Name            | WebAssembly Calls | kVM Interp Calls
+  -------------------------+-------------------+------------------
+  reverse                  |                 1 |                1
+  _reverse                 |                41 |               41
+  car                      |                40 |               40
+  cdr                      |                40 |               40
+  cons                     |                40 |               40
+  nil                      |                 1 |                1
+  -------------------------+-------------------+------------------
+  Total Calls              |               163 |              163
 ```
 
-*(Note: ARM64 displays canonical content hashes `@hash` for unaliased internal relations.
-All three backends arrive at the exact same total call count: 163 calls for reversing a list of length 40).*
+*(Note: Both backends arrive at the exact same total call count:
+163 calls for reversing a list of length 40).*
 
 ---
 
@@ -143,9 +150,7 @@ node scripts/perf-poly.mjs --trace
 | `TRACE_SAMPLES` | `5` | Repetitions sampled and averaged for phase timings. |
 | `TRACE` | `0` | Set to `1` (or pass `--trace`) to enable phase breakdown. |
 | `PROFILE` | `1` (with trace) | Set to `0` to disable function call counters. |
-| `ARM64_OPT` | `-O2` | Optimization level for the native ARM64 runtime (`-O0`, `-O1`, `-O2`, `-O3`). |
 | `WASM_RESET` | `1` | Reset the WebAssembly linear memory arena between calls (`1` or `0`). |
-| `ARM64_ONLY` | `0` | Run only the Linux ARM64 native target. |
 | `WASM_ONLY` | `0` | Run only the WebAssembly target. |
 | `LLVM_ONLY` | `0` | Run only the LLVM target. |
 | `BACKENDS_ONLY` | `0` | Skip the native JS baseline lanes. |
@@ -156,34 +161,17 @@ node scripts/perf-poly.mjs --trace
 # Fast smoke check with list length 10 and 1 iteration:
 ITERATIONS=1 LIST_LENGTH=10 npm run perf:poly:trace
 
-# Measure high-optimization ARM64 (-O3) vs WebAssembly on large lists (100 elements):
-LIST_LENGTH=100 ARM64_OPT=-O3 npm run perf:poly:trace
+# Trace WebAssembly on large lists (100 elements):
+LIST_LENGTH=100 WASM_ONLY=1 npm run perf:poly:trace
 
-# Isolate ARM64 native execution:
-ARM64_ONLY=1 npm run perf:poly:trace
+# Isolate LLVM native execution:
+LLVM_ONLY=1 npm run perf:poly:trace
 ```
 
 ---
 
 ## 6. Implementation Architecture
 
-### Linux ARM64 Backend
-- **Code Emission** ([`backends/arm64/src/kvm2arm64.mjs`](../backends/arm64/src/kvm2arm64.mjs)): When `options.profile` is active, each function emits counter increment instructions in its entry sequence:
-  ```asm
-      adrp  x9, k_prof_<func>
-      add   x9, x9, :lo12:k_prof_<func>
-      ldr   x10, [x9]
-      add   x10, x10, #1
-      str   x10, [x9]
-  ```
-  Counters are emitted into a dedicated `.data` section, and an exported metadata table `k_profile_entries[]` is generated.
-- **Runtime Reporting** ([`backends/arm64/src/runtime.c`](../backends/arm64/src/runtime.c)):
-  - Nanosecond phase timestamps are sampled via `clock_gettime(CLOCK_MONOTONIC, ...)` and emitted over stderr formatted as:
-    ```text
-    K_TRACE_PHASES backend=arm64 ipc_read_ns=... decode_ns=... flat_in_ns=... eval_ns=... flat_out_ns=... encode_ns=... ipc_write_ns=... total_ns=...
-    ```
-  - `dump_profile_counts()` emits nonzero function call counts between `K_PROFILE_BEGIN` and `K_PROFILE_END` tags.
-
 ### WebAssembly Backend
 - **Code Emission** ([`backends/wasm/src/kvm2wasm.mjs`](../backends/wasm/src/kvm2wasm.mjs)): Emits mutable 64-bit Wasm globals:
   ```wat

package/DOCS/REPL.md

@@ -58,7 +58,7 @@ Examples:
 ```
 
 ```k
-> bool = ?<{} true, {} false>;
+> bool? = ?<{} true, {} false>;
 ```
 
 ```k
@@ -147,7 +147,7 @@ aliases, and metadata into the session. Aliases are recovered from
 
 In `k`, there are no primitive numbers or built-in numerical literals.
 Values such as integers are represented as algebraic bit trees (e.g.
-`bits = ?< {} _, B 0, B 1 > = B;`).
+`bits? = ?< {} _, B 0, B 1 > = B;`).
 
 A codec translates between external text and enveloped *k* values:
 - `parse(text)`: parses an external string into an enveloped *k* value.
@@ -309,7 +309,7 @@ Evaluated values print in k syntax together with the inferred envelope:
 ## Example Session
 
 ```text
-> nat = ?< {} 0, N +1 > = N;
+> nat? = ?< {} 0, N +1 > = N;
 > inc = | +1;
 > {} | 0
 {}|0 ?<{} 0, ...>

package/DOCS/book/03-types-as-finite-automata.md

@@ -7,8 +7,8 @@ A schema in `k` describes a set of finite labeled trees, which can be recognized
 For example, the recursive schema of a `list`:
 
 ```k-lang
-bool = ?< {} true, {} false >;
-list = ?< {} nil, { < {} true, {} false > head, L tail } cons > = L;
+bool? = ?< {} true, {} false >;
+list? = ?< {} nil, { < {} true, {} false > head, L tail } cons > = L;
 ```
 
 corresponds to the following 4-rule grammar:
@@ -44,7 +44,7 @@ Each schema structure introduces one or more *states* in the automaton. A union
 For example, consider the `bool` schema:
 
 ```k-lang
-bool = ?< {} true, {} false >;
+bool? = ?< {} true, {} false >;
 ```
 
 This schema translates to an automaton with two states:
@@ -88,7 +88,7 @@ This traversal produces a unique and deterministic numbering for any finite dire
 For a schema representing binary natural numbers:
 
 ```k-lang
-bnat = ?< Bnat 0, Bnat 1, {} _ > = Bnat;
+bnat? = ?< Bnat 0, Bnat 1, {} _ > = Bnat;
 ```
 
 the canonical automaton form is:

package/DOCS/book/06-values-in-memory.md

@@ -111,11 +111,11 @@ Each node in the value tree is encoded based on its automaton state:
 
 #### **Example: Natural numbers**
 
-For type `bnat`, intuitively binary natural numbers defined by `bnat = ?< Bnat 0, Bnat 1, {} _ > = Bnat;`, we get
+For type `bnat?`, intuitively binary natural numbers defined by `bnat? = ?< Bnat 0, Bnat 1, {} _ > = Bnat;`, we get
 
 ```text
-> :rel bnat
-bnat = ?< Bnat 0, Bnat 1, {} _ > = Bnat;  -- @...
+> :rel bnat?
+bnat? = ?< Bnat 0, Bnat 1, {} _ > = Bnat;  -- @...
 ```
 
 The corresponding Context-Free grammar is:
@@ -191,7 +191,7 @@ Subtrees that happen to produce the same local payload bits under different type
 Consider a binary tree with repeated leaf patterns:
 
 ```k-lang
-tree = ?< { T left, T right } branch, int leaf > = T;
+tree? = ?< { T left, T right } branch, int? leaf > = T;
 ```
 
 Value: A tree corresponding to the structure:
@@ -293,8 +293,8 @@ These are encoder-side construction choices for reaching the same canonical resu
 Consider a list of similar records:
 
 ```k-lang
-record = ?{ string name, int age, string department };
-company = ?< { record head, C tail } cons, {} nil > = C;
+record? = ?{ string? name, int? age, string? department };
+company? = ?< { record? head, C tail } cons, {} nil > = C;
 ```
 
 Value representing 1000 employees where 80% work in "Engineering":
@@ -712,9 +712,9 @@ const Arena = struct {
 Consider processing a large JSON-like structure where we only need one field:
 
 ```k-lang
-metadata = ?{ timestamp created, string author };
-list = ?< { nat value, L next } cons, {} nil > = L;
-record = ?{ string name, list data, metadata meta };
+metadata? = ?{ timestamp created, string? author };
+list? = ?< { nat? value, L next } cons, {} nil > = L;
+record? = ?{ string? name, list? data, metadata? meta };
 ```
 
 For the input program `\x.x.name` (extract name field):

package/DOCS/book/08-operational-semantics-and-execution.md

@@ -153,7 +153,7 @@ for any given input, at most one result tree can be produced.
 Given:
 
 ```k-lang
-bool = ?< {} true, {} false >;
+bool? = ?< {} true, {} false >;
 neg = ?< {} true, {} false > < /true | false, /false | true >;
 ```
 

package/DOCS/book/09-compiler-architecture.md

@@ -73,8 +73,8 @@ These tables ensure that generated code can find fields and variants by number r
 Consider a simple k program:
 
 ```k-lang
-bool = ?< {} true, {} false >;
-neg = bool < /true | false, /false | true > bool;
+bool? = ?< {} true, {} false >;
+neg = bool? < /true | false, /false | true > bool?;
 ```
 
 1. **Parsing:**

package/DOCS/book/10-from-ast-to-intermediate-representation.md

@@ -42,7 +42,7 @@ Each function in the program becomes a small list or tree of such IR instruction
 Source program:
 
 ```k-lang
-bool = ?< {} true, {} false >;
+bool? = ?< {} true, {} false >;
 neg = ?< {} true, {} false > < /true | false, /false | true >;
 ```
 
@@ -50,7 +50,7 @@ The IR for `neg` can be written informally as:
 
 ```text
 neg:
-  CHECK_FILTER bool
+  CHECK_FILTER bool?
   UNION [
     SEQ [ PROJECT true, CONST false ],
     SEQ [ PROJECT false, CONST true ]

package/DOCS/book/14-canonical-serialization.md

@@ -68,7 +68,7 @@ This rule allows the decoder to know, from the type alone, how many bits to read
 For the type
 
 ```k-lang
-bnat = ?< Bnat 0, Bnat 1, {} _ > = Bnat;
+bnat? = ?< Bnat 0, Bnat 1, {} _ > = Bnat;
 ```
 
 the canonical form has three transitions from state C0.

package/Examples/arithmetics.k

@@ -3,7 +3,7 @@ swap_yes_no = < /yes |no, /no |yes >;
 yes = {}|yes;
 no = yes swap_yes_no;
 
-bits = ?< {} _, bits 0, bits 1 > = bits;
+bits? = ?< {} _, bits? 0, bits? 1 > = bits?;
 
 0b = {} | _;
 -- |1 = | 1;
@@ -64,7 +64,7 @@ GT = {inOrder /no if, () then} . then;
 EQ = {inOrder /yes if, {.x y, .y x} inOrder /yes and, () then} .then;
 
 --------------------------------------
-int = ?< <bits 0, bits 1, {} _>=bits "+", bits "-" >;
+int? = ?< <bits 0, bits 1, {} _>=bits "+", bits "-" >;
 
 remove_leading_zeros = <
   /0 remove_leading_zeros, 

package/Examples/bnat.k

@@ -1,6 +1,6 @@
 -- Standard binary encoding of natural numbers
 
-bnat = ?< {} _, bnat 0, bnat 1 > = bnat;
+bnat? = ?< {} _, bnat? 0, bnat? 1 > = bnat?;
 
 _ = {}|_;
 _1 = |1;

package/Examples/karatsuba-mult.k

@@ -5,12 +5,12 @@
 yes = {} | yes;
 no = {} | no;
 
-bits = ?< {} _, bits 0, bits 1 > = bits;
+bits? = ?< {} _, bits? 0, bits? 1 > = bits?;
 0b = {} | _;
 0 = 0b |0;
 1 = 0b |1;
 
-unat = ?< {} _, unat 1 > = unat;
+unat? = ?< {} _, unat? 1 > = unat?;
 0u = {} | _;
 
 empty = < /_ yes, no >;