@fraczak/k 5.1.2 → 6.0.1

package/README.md

@@ -1,625 +1,321 @@
 # k-language
 
-```sh
-npm i '@fraczak/k'
-```
-
-From javascript:
-
-```javascript
-import k from "@fraczak/k"
-    
-const fn = k.compile(`   -- complete "pure" k-program
-  $ nat = < {} o, nat i >;     -- unary natural number encoding
-  succ = {() i} $nat;          -- increment relation definition
-  succ succ succ               -- +3 (in the above encoding)
-`);
-const three = {i:{i:{i:{o:{}}}}};
-const six = fn(three);
-console.log(JSON.stringify( six ));
-// {"i":{"i":{"i":{"i":{"i":{"i":{"o":{}}}}}}}}
-```
-
-Working with REPL:
+> **k** is a language for composing first-order partial functions over algebraic data types.
 
-[![asciicast](https://asciinema.org/a/UZuFpX4a5CQ47JTQngv253EVv.svg)](https://asciinema.org/a/UZuFpX4a5CQ47JTQngv253EVv)
+Values are tree-shaped and built solely from **products** (records) and **tagged unions** (variants).
+There are no built-in primitive types — the only leaf in a non-recursive definition is the empty product `{}`.
+Types (called *codes*) are finite tree automata; equivalence is bisimilarity.
 
 ---
 
-## k - the way of building and manipulating JSON-like data
+## Quick Start
 
-Technically, `k` is a notation for defining **first-order partial functions**.
+**Prerequisites:** Node.js 18+
 
-An example of a _partial function_ is the _projection_, e.g., "`.toto`",
-which maps an object to its property named `toto`, or it is not defined if
-the property doesn't exist. E.g.,
-
-```text
-1   .toto :
-2        {"toto": 5, "titi": 10}  --> 5
-3        {"titi": 10}             ... undefined // it is not a value!
+```bash
+npm install          # install dev deps and generate parsers
+npm test             # run the full test suite
+k-repl               # start the interactive REPL  (or: node repl2.mjs)
+./k.mjs <file.k>     # execute a k script
 ```
 
-> Note: The above 3 lines should be read as follows. A `k`-expression
-> is printed in the first line (before "`:`").  The following lines
-> are examples of the function defined by the `k`-expression applayed
-> to JSON values (first part of each line).  If the function for the
-> value is defined, then the result is printed after "`-->`" (line 2 in
-> the above example).  If the function is not defined for the value,
-> then "`... undefined`" is printed (line 3).
+> After `npm link` (or `npm install -g .`) the binaries `k`, `k-repl`, `k-parse`, `k-print`, etc. are available globally.
 
 ---
 
-### Combining "partial functions"
+## CLI Binaries
 
-There are three ways of combining functions:
-
-1. **Composition**: `(f1 f2 ...)`, e.g. `(.toto .titi)` extracts
-    nested field.
-
-    ```text
-        (.toto .titi) :
-            {"toto": {"titi": 10}}   --> 10
-            {"toto": {"other": 8}}   ... undefined
-            {"other": {}}            ... undefined
-    ```
-
-2. **Merge**: `< f1, f2,... >`, e.g., `<.toto, .titi>` extracts field
-    `toto` if present; otherwise extracts `titi`.
-
-    ```text
-        < .x.y, .z.y > :
-            {"x":{"y": 5}, "z": {"y":10}}  --> 5
-            {"x":{"o":{}}, "z": {"y":10}}  --> 10
-            {"x":{"o":{}}, "z": {"o":{}}}  ... undefined
-    ```
-
-3. **Product**: `{ f1 label1, f2 label2, ...}`, e.g., `{.toto TOTO,
-    .titi TITI}` extracts two fields and builds a record out of them.
-
-    ```text
-        {.toto TOTO, .titi TITI} :
-            {"toto": 5, "titi": 10, "x": 3}  --> {"TOTO": 5, "TITI": 10}
-    ```
+| Binary | Source | Purpose |
+|--------|--------|---------|
+| `k` | `k.mjs` | Execute a `.k` script; reads binary pattern+value stream from stdin |
+| `k-repl` / `k-repl2` | `repl2.mjs` | Interactive REPL |
+| `k-parse` | `codecs/k-parse.mjs` | Encode a JSON value to the binary pattern+value wire format |
+| `k-print` | `codecs/k-print.mjs` | Decode binary pattern+value stream back to JSON |
+| `k-pattern` | `codecs/k-pattern.mjs` | Print the pattern of a binary-encoded value |
+| `k-compile-object` | `objects/compile.mjs` | Compile a `.k` source to a `.kobj` object file |
+| `k-decompile-object` | `objects/decompile.mjs` | Decompile a `.kobj` file back to k source |
 
 ---
 
-**QUIZ**: What is:
+## Data Model: Codes = ADTs
 
-- Empty composition: `()` ?
-- Empty merge: `<>` ?
-- Empty product: `{}` ?
-- `{{{{} s} s} s}` ?
-- `({{{() a} b} c} .c .b .a)` ?
+Codes are algebraic data types built from two constructors:
 
----
+| Constructor | Native k notation | JSON-like notation |
+|-------------|------------------|--------------------|
+| **Product** (record) | `{ A label1, B label2 }` | `{ label1: A, label2: B }` |
+| **Tagged union** (variant) | `< A tag1, B tag2 >` | `< tag1: A, tag2: B >` |
 
-### Syntactic sugar
+Native k-like notation is canonical; JSON-like is supported as syntactic sugar.
 
-- Parenthesis can be omitted, except for the empty composition `()`,
-- dot (`.`) in "projection" acts as a separator, so the surrounding
-  space can be omitted.
+### Defining codes (`$`)
 
-For example, `(.toto .titi (.0 .1))` can be written as `.toto.titi.0.1`.
+```k
+$ nat   = < {} zero, nat succ >;          -- Peano naturals
+$ bit   = < {} 0, {} 1 >;
+$ byte  = { bit 0, bit 1, bit 2, bit 3, bit 4, bit 5, bit 6, bit 7 };
+$ list  = < {} nil, { bit car, list cdr } cons >;
+```
 
-Comments can be introduced by `//`, `--`, `%`, or `#` and extends to
-the end of line.  Multiline `C`-like comments, `/* ... */`, are also
-supported.
+Two codes are equal iff they are bisimilar: same label/tag sets, same constructor kind (product vs. union), and subcodes relate pointwise under each label/tag.
 
-### Basic extensions
+---
 
-#### Constants, i.e., literals for `string`, `int`, `bool`, and `null`
+## Partial Functions
 
-A constant defines a function which ignores its argument and produces
-the constant value. E.g.:
+A partial function may be undefined on some inputs. Core primitives:
 
-```text
-{123 int, "kScript" str, true bool, null null} :
-    "any"  --> {"int":123,"str":"kScript","bool":true,"null":null}
-```
+| Syntax | Name | Meaning |
+|--------|------|---------|
+| `.field` | product projection | extract `field` from a product value |
+| `/tag` | union projection | assert value has tag `tag`, extract payload |
+| `\|tag` | variant introduction | wrap value in tag `tag` |
+| `()` | identity | pass value through unchanged |
+| `<>` | always-undefined | undefined for all inputs |
+| `{}` | empty product | map any input to `{}` |
 
-Those values, i.e., _strings_, _integers_, _booleans_, and _null_, admit the
-projection, via (`.`), to the canonical string representation of the value, e.g.:
+**Examples:**
 
 ```text
-."a string" :
-    "a string" --> {}
-    "other"    ... undefined
-    11         ... undefined
-    null       ... undefined
-.2 :
-    2          --> {}
-    "2"        --> {}
-    4          ... undefined
-    true       ... undefined
-
-.true :
-    true   --> {}
-    "true" --> {}
-    4      ... undefined
-    "toto" ... undefined
-
-.null :
-    null   --> {}
-    "null" --> {}
-    4      ... undefined
-    false  ... undefined
-```
-
-#### Vector product
+.toto :
+    { "toto": {"5":{}}, "titi": {"10":{}} }  -->  {"5":{}}
+    { "titi": {"10":{}} }                         ... undefined
 
-The vector product can be seen as a shorthand for a product in which all fields
-have the same type, and the field names are integers starting from zero.
-E.g., `{.toto 0, .titi 1, 123 2}` can be written as  
-`[.toto, .titi, 123]`.
+/toto :
+    {"toto": {}}  -->  {}
+    {"other": {}} ... undefined
 
-```text
-[.toto, .titi, 12] :
-    {"toto": 5, "titi": 10 }  --> [5, 10, 12] 
-
-. 2 :
-    ["A","B","C"]  --> "C"
-    ["a"]          ... undefined
+|toto :
+    {"5":{}}  -->  { "toto": {"5":{}} }
 ```
 
 ---
 
-### Pragmatic extensions, aka "standard library"
+## Combining Functions
 
-- `GT` -- identity for lists of decreasing elements; undefined otherwise
+### 1. Composition — sequential application
 
-      GT:
-        [4,3]     --> [4,3]
-        [3,4]     ... undefined
-        []        --> []
-        [4,3,0]   --> [4,3,0]
+`(f g h)` applies `f`, then `g`, then `h`. Parentheses can be omitted.
 
-- `EQ` -- identity for lists of equal elements; undefined otherwise
+```text
+(.toto .titi) :
+    { "toto": { "titi": {} } }    -->  {}
+    { "toto": { "other": {} } }   ...  undefined
+```
 
-      EQ:     
-        [4,4]     --> [4,4]
-        [4,5]     ... undefined
-        [4,4,4]   --> [4,4,4]
-        []        --> []
+### 2. Merge — first-defined wins
 
-- `PLUS` and `TIMES` -- sum and product of lists of numbers
+`<f, g>` tries `f` first; if undefined, tries `g`.
 
-      {PLUS plus, TIMES times} :
-        [1,2]     --> {"plus":3,"times":2}
-        [2,2,2]   --> {"plus":6,"times":8}
-        []        --> {"plus":0,"times":1}
+```text
+< .x .y, .z .y > :
+    { "x": {"y": {"5":{}}}, "z": {"y": {"10":{}}} }   -->  {"5":{}}
+    { "x": {"o": {}},        "z": {"y": {"10":{}}} }   -->  {"10":{}}
+    { "x": {"o": {}},        "z": {"o": {}} }          ...  undefined
+```
 
-- `CONCAT` -- concatenation of lists of strings
+### 3. Product — parallel, labelled collection
 
-      CONCAT:
-        ["a","bc","d"] --> "abcd"
-        []             --> ""
+`{f label1, g label2}` applies `f` and `g` in parallel and builds a record.
 
-- `toJSON` and `fromJSON` -- conversion to and from JSON strings
+```text
+{ .toto TOTO, .titi TITI } :
+    { "toto": {"5":{}}, "titi": {"10":{}}, "x":{} }
+         -->  { "TOTO": {"5":{}}, "TITI": {"10":{}} }
+```
 
-      toJSON:
-        {"a": 12} --> "{\"a\":12}"
+---
 
-      fromJSON:   
-        "{\"a\":12}"       --> {"a":12}
+## Syntactic Sugar
 
-- other predefined parial functions are: `DIV`, `FDIV`, `CONS`,
-  `SNOC`, `toVEC`, `toDateMsec`, `toDateStr`, and `_log!`.
+- Parentheses may be omitted (except for empty composition `()`).
+- `.a .b /c` is equivalent to `(.a (.b /c))`.
+- Comments: `//`, `--`, `%`, `#` (single-line) or `/* ... */` (multi-line).
+- Both notation forms work in the same file.
 
 ---
 
-### Function and code (i.e., _type_) definitions
-
-```k-repl
-  dec = [(),-1] PLUS;
-  max = <SNOC [.car, .cdr max] <GT.0, .1>, .0> ;
-  factorial = < [(),0] GT .0 [dec factorial, ()] TIMES, 1 >;
-  6 factorial
---> 720
-```
+## REPL
 
-### Codes (schemas, i.e., _types_)
+Start with `k-repl` (or `node repl2.mjs`). The prompt is `> `.
 
-_Codes_ can be defined by tagged union and product. E.g.:
+### Defining names and codes
 
-```k-repl
-  $ nat = < nat 1, {} 0 >;
-  $ pair = { nat x, nat y };
-
-  suc = { $ nat 1 };
-  add = $ pair <{.x.1 x, .y suc y} add, .y>;
 ```
-
-Code definition statement starts with `$`. 
-Also, any code expression occurrig within a `k`-expression is prefixed by `$`.
-
-Two codes are considered equal when they are isomorphic (preserving
-union/product and field names). E.g., `$pair`, `${nat y, nat x}`, and
-`${<nat 1, {} 0> x, nat y}` are all equivalent and corresponds its cannonical form
-`$C0={C1"x",C1"y"};$C1=<C2"0",C1"1">;$C2={};`.
-
-Try in `k-repl`:
-
-```k-repl
-> $ nat = < nat 1, {} 0 >; \
-  $ pair = { nat x, nat y };
---> {}
-> --C pair
- $ IxLVRLECv = {BADJOX x, BADJOX y}; -- $C0={C1"x",C1"y"};$C1=<C2"0",C1"1">;$C2={};
-$ myCode = {<nat 1, {} 0> x, nat y};
---> {}
-> --C myCode
- $ IxLVRLECv = {BADJOX x, BADJOX y}; -- $C0={C1"x",C1"y"};$C1=<C2"0",C1"1">;$C2={};
+> $ nat = < {} zero, nat succ >;
+> succ = |succ;
+> zero = {} |zero $nat;
 ```
 
-#### Basic extension codes
+### REPL commands
 
-Since _basic extension_ introduces integers, booleans, and strings,
-there are three predefined types: `int`, `bool`, and `string`. A
-vector product code can also be defined by `[ codeExp ]`. All members
-of the vector are the same code. E.g.,
+| Command | Effect |
+|---------|--------|
+| `--C name` | Show canonical (hash-addressed) form of a code |
+| `--R name` | Show the type derivation (pattern graph) for a function |
+| `--help` | List available commands |
 
-```k-repl
-  $ intVector = [ int ];
-  $ boolVector = [ bool ];
-  $ tree = [ tree ];
-```
+**Example session:**
 
-### Code derivation and Patterns
-
-Intuitively, a _pattern_ represents some set of contraints on
-codes. For example, expression `.toto` is a projection from a value of
-a product or a union code with field `toto`.  Therefore, expression `.toto`
-introduces two patterns `p_i` and `p_o` (for input and output codes,
-respectively); `p_o` imposes no constraint on code, however `p_i` is a
-product or union code with field `toto` leading to a code fulfilling
-`p_o`, which will be denoted by:
-
-```k-repl
+```
+> $ nat = < {} zero, nat succ >;
+> $ pair = { nat x, nat y };
+> --C pair
+ $ @wq9VvJgYt8sASQfevD23... = { @w8iSHe... x, @w8iSHe... y };
 > toto = .toto;
---> {}
 > --R toto
-  toto : ?(X0 toto, ...)  -->  ?X0
-  toto = .toto;
-```
-
-In a more complex expression each (occurrence of) subexpression will
-introduce some new patterns.  
-For example, concider ` rel = <.toto, ()>; `.
-
-        <    .toto    ,    ()    >
-     p1   p2       p3   p4    p5   p6
-
-where `p1` is the pattern for the input code of the whole expression,
-and `p6` is the pattern for the output.  We can deduce that patterns
-(`p1`, `p2`, `p4`) defines the same code, as well as (`p6`, `p5`, `p3`),
-because union combines partial functions with the same input and output codes.
-Identity, `()`, implies that (`p4`, `p5`) define the
-same code. In `k-repl`:
-
-```k-repl
-> rel = < .toto, () >;
---> {}
-> --R rel
-  rel : ?(X0 toto, ...)=X0  -->  ?X0
-  rel = <.toto, ()>;
-```
-
-For a given `kScript`, code derivation (as any static analysis) can
-fail, indicating that the script is invalid.  In some other cases the
-code derivation can succeed even to the point of reducig every pattern
-to a single code making the program fully annotated by codes.
-
-The language `k` supports _type patterns_, which is used for code
-derivation, however the patterns are not concidered in the
-evaluation of the program.
-
-```k-repl
-    treePattern = ?<(...) leaf, {T left, T right} tree> = T;
+  toto : ?{ X0 toto, ... }  -->  ?X0
 ```
 
 ---
 
-### List comprehension
+## Code Derivation and Patterns
 
-A vector can be "open" by PIPE (`|`) operator so the following partial function is applied to
-each element of the vector, yielding another open value. An open value can be "closed", 
-i.e., turn into a regular vector using `CARET` (`^`) operator. E.g.:
+A **pattern** (or *filter*) is a constraint on the type of values flowing through a function.
+The type derivation engine infers patterns automatically and can optionally be guided with filter expressions:
 
 ```k
-    | .x  ^ :
-       [{x:12}, {x:8}, {y:98}]       -->  [12,8]
-       ["a","x","b","x"]             -->  [{},{}]
+treeFilter = ?< (...) leaf, { T left, T right } tree > = T;
 ```
 
-The PIPE operator can be used for defining the Cartesian product:
-
-```k
-    [.0 |, .1 |] ^ :
-        [[1,2], [3,4]]    -->  [[1,3],[1,4],[2,3],[2,4]]
-```
-
-or
-
-```k
-    { | x, | y } ^ :
-        [1,2]             --> [{"x":1,"y":1},{"x":2,"y":1},{"x":1,"y":2},{"x":2,"y":2}]
-```
-
-**QUIZ**: Write a function which will take a list of integers and an integer `x`, and count how many
-times value `x` appears in the list. (see `Examples/list-comprehension.k` for a solution)
-  
-```k
-    count_occurrences =
-    $ { [int] list, int x } 
-      -- ???
-    $ int;        
-```
-
-**WARNING**: When using `CARET` operator paranthesis may be required, e.g., like in:
-
-```k
-    | ( [|,|] ^ ) ^ :
-        [[1,2],[3,4]]     -->  [[[1,1],[1,2],[2,1],[2,2]],[[3,3],[3,4],[4,3],[4,4]]]             
-```
+This tells the derivation engine that `treeFilter` operates on values that are either a `leaf` or a `tree` with matched left/right subtypes.
 
 ---
 
-## Examples
-
-1. projection:
-
-        .x
-        . "field name"
-        (. 4)
-
-   The function is defined if its argument "has" the field.
-
-2. _constants_, literals for Strings, Booleans, and
-   Integers. Examples:
-
-        "a string"
-        'another "String"'
-        123
-        false
-        null
-
-3. "built-in" functions:
+## Using k as a Library (Node.js)
 
-        [1, 2, 3] PLUS       -- integer constant function 6
-        [4, 4] TIMES toJSON  -- string constant function "16"
-        [3, 2] GT            -- vector constant function [3, 2]
-        [3, 4] GT            -- ... undefined
+```js
+import k from "@fraczak/k";  // or "./index.mjs"
 
-    A more interesting example could be:
-
-        < GT .0, .1>
-
-    which selects the maximum element in two element vector, i.e.,
-
-        [3,8] < GT .0, .1 >    --> 8
-
-### User defined functions
-
-`k`-expression can be prefixed by function definitions. E.g.:
-
-        dec = [(),-1] PLUS;
-        zero? = [(),0] EQ 0;
-        factorial = <
-          zero? 1, 
-          [dec factorial, ()] TIMES
-        >;
-        { () x, factorial "x!" }
-
-Another example could be finding the biggest (max) value in a vector:
-
-    max = < 
-      SNOC             #  [x0, x1, x2, ...] --> {x0 car, [x1, x2, ...] cdr}
-      [.car, .cdr max] #  {car:x0, cdr:[x1, x2, ...]} --> [x0, max(x1,x2,...)], recursive call 
-      <GT .0, .1>      #  if x0 > max(x1,x2,...) then x0 else max(x1,x2,...)
-    ,                  # when SNOC is not defined, i.e., if the input vector has one element:
-      .0               #  [x0] --> x0
-    >; 
-    max
-
-### Value encodings (_codes_)
-
-There are three predefined value encodings: `int`, `string`, and
-`bool`. The language supports `code`-expressions:
-
-- product, e.g., `{int x, int y, bool flag}`
-- disjoint union, e.g., `<{} true, {} false>`
-- vector, e.g., `[ int ]` (all elements of the vector use the same
-  encoding)
-
-One can define recursive codes. E.g.:
+// compile + run
+const fn = k.compile(`
+  $ bool = < {} true, {} false >;
+  not = < /true {} |false $bool, /false {} |true $bool >
+`);
 
-    $tree = <string leaf, {tree left, tree right} tree>;
+console.log(fn({ "true": {} }));   // { false: {} }
 
-Each _code_ definition starts with a `$`.
-The above example defines new code called _tree_.
+// annotate only (type-check without running)
+const annotated = k.annotate(source, {
+  convergence: { strategy: "auto" }  // "auto" | "single_pass" | "fixed_point"
+});
+console.log(annotated.compileStats);  // per-SCC strategy and iteration counts
+```
 
-The code can be then used in a `k`-expression as a filter. A `code`-expression
-within `k`-expression is again prefixed by `$`.
+### Convergence strategies
 
-    $ tree = <string leaf, {tree left, tree right} tree>;
-    inc = [(),1] PLUS;
-    max = <GT .0, .1>;
-    height = $ tree <
-        .leaf 0,
-        .tree [.left height, .right height] max inc
-    > $ int;
-    height
+| Strategy | Behaviour |
+|----------|-----------|
+| `auto` *(default)* | Single-pass for non-recursive SCCs; fixed-point for recursive ones |
+| `single_pass` | Force single-pass (fast, use for acyclic modules) |
+| `fixed_point` | Force the full convergence loop (useful for debugging) |
 
 ---
 
-## `k` (a command-line JSON processor using `k` syntax)
+## Standard Library — `core.k`
 
-There is a wrapper, `k` (`./node_modules/.bin/k`), which makes it easy to
-run the language from command line.
+`core.k` is the k standard core library. It is loaded automatically by the codec pipeline and
+is available as a reference for any k program that needs canonical types.
+It defines four things, in order:
 
-    > k
-       ... errors ...
-    Usage: ./node_modules/.bin/k ( k-expr | -k k-file) [ -1 ] [ json-file ]
-    E.g., cat '{"a": 10}' | ./node_modules/.bin/k '[(),()]'
+### §1 & §2 — `$bits` and arithmetic
 
-For example:
+`$bits` is the canonical binary number type (LSB-first trie: empty `_`, extend with `0` or `1`).
+It is also used as node-index encoding inside pattern graphs.
 
-1. One `k`-expression with one `json`-object:
-
-        > echo '{"x": 12, "y": 13}' | k '{ <.x, "no x"> x, () input}' 
-         {"x":12,"input":{"x":12,"y":13}}
-
-2. By providing only `k`-expression, the script will compile the
-   `k`-expression and apply the generated function to the `stdin`,
-   line by line:
-
-        > k '<["x=",.x," & y=",.y],["only x=",.x],["only y=",.y],["no x nor y"]>{CONCAT "x&y"}' 
-        
-         {"y": 123, "x": 432,"others": "..."}  --> {"x&y":"x=432 & y=123"} 
-         {"x": 987}                            --> {"x&y":"only x=987"} 
-         {"z": 123}                            --> {"x&y":"no x nor y"}
-         ^D - to interrupt
-
-   If the input is a multiline json object, we need to add `-1` to the command-line options.
+```k
+$ bits = < {} _, bits 0, bits 1 >;
+```
 
-3. If the `k`-expression is long, it can be put in a file, e.g.:
+Built-in functions: `inv`, `concat`, `succ`, `plus`, `times`, and integer constants `0`–`10`.
 
-        > cat test.k
-         ---------  comments start by #, --, or // ----------------------------------
-         <                          -- merge of 4 partial functions...
-           ["x=", .x, " & y=", .y], -- produces a vector of 4 values, if fields 'x' and 'y' are present
-           ["only x=", .x],         -- produces a pair '["only x=", "value-of-x"]', for input like {"x":"value-of-x"}
-                                    -- it is defined only if field 'x' is present
-           ["only y=", .y],
-           ["no x nor y"]           -- defined for all input, returns always the same one element vector
-         > 
-         -- one of the string vectors is passed to the following partial function, 
-         -- which produces a record (map) with one field "x&y", whose value is the
-         -- result of concatenating elements of the passed in vector
-         { CONCAT "x&y" } 
-         ------------------------------------------------------------------------------
+### §3 — `$unicode` and `$string`
 
-    We can use it by:
+Full Unicode scalar-value type, partitioned by plane and BMP range, built up from `$bit` and `$byte`.
+`$string` is a linked-list of `$unicode` values — used for field/tag label names in pattern graphs.
 
-        > k -k test.k
+```k
+$ string = < {} nil, { unicode car, string cdr } cons >;
+```
 
-    If we want to read `json` objects from a file, e.g., `my-objects.jsonl`, we do
+### §4 — `$pattern`
 
-        > k -k test.k my-objects.jsonl
-         {"x&y":"x=432 & y=123"} 
-         {"x&y":"only x=987"} 
-         {"x&y":"no x nor y"}
+The self-describing type of k pattern graphs. A pattern is a cons-list of `$pattern-node` values;
+node 0 is the root; edges carry `$string` labels and `$bits` target indices.
 
-    where:
+```k
+$ pattern-node = < {} any, edges open-product, edges open-union,
+                         edges closed-product, edges closed-union >;
+$ pattern       = < {} nil, { pattern-node car, pattern cdr } cons >;
+```
 
-        > cat my-objects.jsonl 
-         ####################################################
-         # empty lines and lines starting with # are ignored
-         {"y": 123, "x": 432,"others": "..."}
-         {"x": 987}
-         {"z": 123}
-         ####################################################
+The singleton pattern of `$pattern` itself is the fixed framing constant for the wire format:
+every k binary stream starts with a `$pattern` encoded under that constant,
+followed by the value encoded under the pattern just decoded.
+This is why `core.k` ends with a bare `$pattern` expression — it pins that canonical hash.
 
 ---
 
-### Short comparaison with `jq` tutorial examples: <https://stedolan.github.io/jq/tutorial/>
+## Binary Codec Pipeline
 
-[![asciicast](https://asciinema.org/a/ItH7nkc5CwFOopH8Fsr23oCWj.svg)](https://asciinema.org/a/ItH7nkc5CwFOopH8Fsr23oCWj)
+The `k` CLI reads and writes a binary stream: a serialised pattern followed by the value encoded under that pattern.
 
----
-
-## k-REPL (Read-Evaluate-Print Loop)
-
-Also, there is a REPL, `k-repl` (`./node_modules/.bin/k-repl`),
-which acts like a toy shell for the language.
-
-```k-repl
-$ k-repl
-Very! experimental repl shell for 'k-language'...
-  --c            print aliased codes
-  --C code       print 'code' definition
-  --r            print relations
-  --R rel        print 'rel' definition with type patterns
-  --p (--pp)     pretty-print last value
-  --s (--g) reg  store (get) the current value in (from) register 'reg'
-  --regs         print register names
-  --l file.k     load 'file.k'
-> 
+```bash
+echo '{"cons":{"car":{"1":{}},"cdr":{"nil":{}}}}' \
+  | k-parse \
+  | k ./Examples/nat.k \
+  | k-print
 ```
 
----
-
-## Using `k` from `javascript`
+See [`codecs/README.md`](codecs/README.md) for codec internals and format details.
 
-```javascript
-import k from "@fraczak/k";
-
-let k_expression = '()';
-k.run(k_expression,"ANYTHING...");
-// RETURNS: "ANYTHING..."
-
-k_expression = '{"ala" name, 23 age}';
-k.run(k_expression,"ANYTHING...");
-// RETURNS: {"name":"ala","age":23}
-
-k_expression = '[.year, .age]';
-k.run(k_expression,{"year":2002,"age":19});
-// RETURNS: [2002,19]
-
-k_expression = '[(), ()]';
-k.run(k_expression,"duplicate me");
-// RETURNS: ["duplicate me","duplicate me"]
-
-k_expression = '[[[()]]]';
-k.run(k_expression,"nesting");
-// RETURNS: [[["nesting"]]]
-
-k_expression = '[[()]] {() nested, .0.0 val}';
-k.run(k_expression,"nesting and accessing");
-// RETURNS: {"nested":[["nesting and accessing"]],"val":"nesting and accessing"}
-
-k_expression = '0000';
-k.run(k_expression,{"test":"parse integer"});
-// RETURNS: 0
+---
 
-k_expression = '[.y,.x] PLUS';
-k.run(k_expression,{"x":3,"y":4});
-// RETURNS: 7
+## Examples
 
-var k_fn = k.compile('{.name nom, <[.age, 18] GT .0, [.age, 12] GT "ado", "enfant"> age}');
+The [`Examples/`](Examples/) directory contains ready-to-run `.k` scripts:
 
-k_fn({"age":23,"name":"Emily"});
-// RETURNS: {"nom":"Emily","age":23}
+| File | Contents |
+|------|----------|
+| `nat.k` | Peano natural numbers |
+| `list.k` | Polymorphic lists |
+| `byte.k` | Byte type (8 bits) |
+| `ieee.k` | IEEE 754 floating-point layout |
+| `bnat.k` | Binary natural numbers |
+| `arithmetics.k` | Integer and rational arithmetic (binary encoding) |
 
-k_fn({"age":16,"name":"Katrina"});
-// RETURNS: {"nom":"Katrina","age":"ado"}
+---
 
-k_fn({"age":2,"name":"Mark"});
-// RETURNS: {"nom":"Mark","age":"enfant"}
+## Development
 
-k_fn = k.compile('$t = < i: int, t: [ t ] > ; <$t, $int>');
+```bash
+npm run prepare   # regenerate parsers from .jison grammars (after editing them)
+npm test          # run full test suite
+```
 
-k_fn(1);
-// RETURNS: 1
+The test suite covers:
 
-k_fn({"i":1});
-// RETURNS: {"i":1}
+- `test.mjs` — core runtime and parser unit tests
+- `Code-derivation-tests/*.mjs` — type derivation suite
+- `test-fingerprint.mjs` — hash/fingerprint stability
+- `test-k-object.mjs` — object file round-trip
+- `test-repl2.mjs` — REPL scripted interaction
+- `tests.sh` — shell integration tests
 
-k_fn([{"i":2},{"i":3},{"t":[]}]);
-// RETURNS: undefined
+---
 
-k_fn({"t":[{"i":2},{"i":3},{"t":[]}]});
-// RETURNS: {"t":[{"i":2},{"i":3},{"t":[]}]}
+## Quiz
 
-k_fn = k.compile('$ < < [ int ] ints, [ bool ] bools > list, string None>');
+What does each of the following evaluate to?
 
-k_fn({"None":"None"});
-// RETURNS: {"None":"None"}
+| Expression | Hint |
+|------------|------|
+| `()` | Empty composition |
+| `<>` | Empty merge |
+| `{}` | Empty product |
+| `\|s\|s\|s/s/s/s` | Tag and untag three times |
+| `({{{() a} b} c} .c .b .a)` | Nest and project |
 
-k_fn({"list":{"ints":[]}});
-// RETURNS: {"list":{"ints":[]}}
+---
 
-k_fn({"list":{"ints":[1,2,3]}});
-// RETURNS: {"list":{"ints":[1,2,3]}}
-```
+For more details see the [`DOCS/`](DOCS/) folder, and especially [`DOCS/book.md`](DOCS/book.md) for the language reference.