@fraczak/k 6.0.3 → 6.1.0

package/DOCS/OBJECT_FILE_AND_PATTERN.md

@@ -82,34 +82,58 @@ type still needs design work because the concrete input value is typed by the
 decoded pattern. The important boundary is that object files should carry
 ordinary k values and patterns, not a JSON codec object.
 
-Later versions can add relation IR, constant tables, symbol dictionaries,
-relocation/linking records, optimization metadata, and optional indexes.
+The format can add relation IR, constant tables, symbol dictionaries,
+relocation/linking records, optimization metadata, and optional indexes as the
+implementation changes.
 
-## Executable Object Container v1
+## Object And Library Containers
 
-The current executable object format is a small binary container:
+The current executable `.ko` format is a small binary container:
 
 ```text
-"KOBJ" 0x00 0x01 0x0a
+"KOBJ" 0x0a
 uint32-be payload-byte-length
 utf8-json-payload
 ```
 
+Library files (`.klib`) are plain UTF-8 JSON with no binary header.
+
+Both containers use the same JSON payload shape. Executable `.ko` files set
+`main` to the entry relation name. Library `.klib` files set `main` to `null`.
+There is no payload version field.
+
 The payload stores:
 
 - the normalized code repository needed by the object,
-- the compiled relation IR,
+- the compiled relation IR without generated boundary filters,
 - each relation's type-pattern graph state,
+- each relation's `typeDerivation.status`,
+- relation aliases in `relAlias`,
+- compiler convergence details in top-level `compileStats`,
+- metadata, including aliases and origin source locations,
 - the main relation name.
 
+Relation `def` values do not store source `start` / `end` markers. Source
+locations live on `meta[hash].origins[]` entries. Each metadata entry has
+`type: "code"` or `type: "rel"`. Origin entries hold `source`, `name`,
+`compiledAt`, and optional `start` / `end`; origin entries do not have `kind`.
+
+Relation `def` values also do not store the generated input/output filters.
+Those filters are derived from `def.patterns` and `typePatternGraph` when
+printing or enforcing relation boundaries.
+
+Codes/types do not carry `typeDerivation`. Type derivation is a relation
+property, and the persisted `typeDerivation` object currently contains only
+`status`.
+
 Loading an object hydrates the type-pattern graphs back into runtime
-`TypePatternGraph` instances and executes them through `run.mjs`. This avoids
-source parsing and type derivation on the execution path.
+`TypePatternGraph` instances and executes relation boundaries through
+`run.mjs`. This avoids source parsing and type derivation on the execution path.
 
 Object execution through `k.mjs`:
 
 ```sh
-echo "..." | ./some-codec --parse | ./k.mjs -k path/to/program.ko | ./some-codec --print
+echo "..." | some-codec --parse | k -k path/to/program.ko | some-codec --print
 ```
 
 The `-k` option accepts either an object file or a source `.k` file. `k.mjs`
@@ -119,15 +143,17 @@ compilation.
 Standalone helpers live in `objects/`:
 
 ```sh
-./objects/compile.mjs path/to/program.k path/to/program.ko
-./objects/decompile.mjs path/to/program.ko path/to/program.decompiled.k
+k-compile path/to/program.k path/to/program.ko
+k-compile-lib path/to/library.k path/to/library.klib
+k-decompile path/to/program.ko path/to/program.decompiled.k
+k-extract-aliases path/to/library.klib path/to/aliases.k
 ```
 
-With no arguments, both helpers read from stdin and write to stdout:
+With no arguments, the helpers read from stdin and write to stdout:
 
 ```sh
-cat path/to/program.k | ./objects/compile.mjs > path/to/program.ko
-cat path/to/program.ko | ./objects/decompile.mjs > path/to/program.decompiled.k
+cat path/to/program.k | k-compile > path/to/program.ko
+cat path/to/program.ko | k-decompile > path/to/program.decompiled.k
 ```
 
 The decompiled source is canonical source regenerated from object IR. It uses
@@ -147,14 +173,14 @@ For a tiny source file:
 compile it with:
 
 ```sh
-./objects/compile.mjs id.k id.ko
+k-compile id.k id.ko
 ```
 
 The first bytes of `id.ko` are the binary container header:
 
 ```text
-4b 4f 42 4a 00 01 0a 00 00 03 0b ...
-K  O  B  J  \0 v1 \n payload-length
+4b 4f 42 4a 0a 00 00 03 0b ...
+K  O  B  J  \n payload-length
 ```
 
 After the header, the payload is UTF-8 JSON. Pretty-printed and shortened, the
@@ -163,59 +189,119 @@ payload has this shape:
 ```json
 {
   "format": "k-object",
-  "version": 1,
-  "codes": {
-    "@NiDZqYggx3VZ6b8quBZKTfkgJztWctkesuX4CrhTxM5c": {
-      "code": "product",
-      "product": {},
-      "def": "$C0={};"
+  "codes": {},
+  "main": "__main__",
+  "rels": {
+    "__main__": {
+      "def": { "op": "identity", "patterns": [0, 0] },
+      "typeDerivation": {
+        "status": "converged"
+      },
+      "typePatternGraph": {
+        "patterns": {
+          "nodes": [{ "pattern": "(...)", "fields": [] }],
+          "parent": []
+        },
+        "edges": [{}],
+        "codeId": {}
+      }
     }
   },
-  "main": "__main__",
-  "defs": {
-    "rels": {
-      "__main__": {
-        "def": {
-          "op": "filter",
-          "filter": { "type": null, "open": true, "fields": {}, "name": "X0" },
-          "patterns": [0, 0],
+  "relAlias": { "__main__": "@QfyLpmn56wuppuGvrrUJz8LKtgaXfbMtad7RnzBcFk2S" },
+  "compileStats": { "sccs": [...], "sccCount": 1 },
+  "meta": {
+    "@QfyLpmn56wuppuGvrrUJz8LKtgaXfbMtad7RnzBcFk2S": {
+      "type": "rel",
+      "origins": [
+        {
+          "source": "id.k",
+          "name": "__main__",
+          "compiledAt": "2026-05-20T00:00:00.000Z",
           "start": { "line": 1, "column": 1 },
           "end": { "line": 1, "column": 3 }
-        },
-        "typePatternGraph": {
-          "patterns": {
-            "nodes": [{ "pattern": "(...)", "fields": [] }],
-            "parent": []
-          },
-          "edges": [{}],
-          "codeId": {}
         }
-      }
-    },
-    "representatives": {},
-    "relAlias": { "__main__": "..." },
-    "compileStats": { "sccs": [...], "sccCount": 1 }
+      ]
+    }
   }
 }
 ```
 
 The `codes` field is the type repository snapshot needed by this object. The
-`defs.rels.__main__.def` field is the executable relation IR. The
+`rels.__main__.def` field is the executable relation body. The
 `typePatternGraph` field is the compiled pattern graph used by `run.mjs` for
-input-envelope refinement. Loading the object reconstructs live
+relation-boundary refinement. Loading the object reconstructs live
 `TypePatternGraph` instances from this JSON state and then evaluates the input
-value directly against the compiled IR.
+value against the compiled IR.
 
 Decompiling this object produces canonical source with generated prefix names:
 
 ```k
 ----- codes -----
-$ NiDZ = {};
 ----- rels -----
-QfyL = ?X0;
+QfyL = ?(...) () ?(...);
 ----- main -----
 ?(...) QfyL ?(...)
 ```
 
 In the `rels` section, relation definitions are printed in the same SCC order
 recorded during compilation. Non-empty SCC groups are separated by a blank line.
+
+## Small Library Example
+
+For a definitions-only source file:
+
+```k
+-- defs.k
+$ nat = <{} zero, nat succ>;
+succ = |succ;
+```
+
+compile it with:
+
+```sh
+k-compile-lib defs.k defs.klib
+```
+
+The output file is plain JSON and starts with `{`, not a binary prefix. Its
+shape is the same object payload shape with `main: null`:
+
+```json
+{
+  "format": "k-object",
+  "codes": {
+    "@...": {
+      "code": "union",
+      "union": { "zero": "@...", "succ": "@..." },
+      "def": "$C0=<C1\"succ\",C2\"zero\">;..."
+    }
+  },
+  "rels": {
+    "@...": {
+      "def": { "op": "vid", "vid": "succ", "patterns": [0, 1] },
+      "typeDerivation": { "status": "converged" },
+      "typePatternGraph": { "patterns": "...", "edges": "...", "codeId": "..." }
+    }
+  },
+  "relAlias": { "succ": "@..." },
+  "compileStats": { "sccs": [...], "sccCount": 1 },
+  "meta": {
+    "@...": {
+      "type": "rel",
+      "origins": [
+        {
+          "source": "defs.k",
+          "name": "succ",
+          "compiledAt": "2026-05-20T00:00:00.000Z",
+          "start": { "line": 3, "column": 8 },
+          "end": { "line": 3, "column": 13 }
+        }
+      ]
+    }
+  },
+  "main": null
+}
+```
+
+When a library is compiled with `--lib`, the output is the merged library
+closure. Imported codes, relations, aliases, and metadata are preserved, and the
+new source adds its own origins.

package/DOCS/PATTERNS.md

@@ -66,9 +66,10 @@ list
 
 In both cases, the compiler derives a root pattern from `__main__`.
 
-## `k-pattern`
+## Pattern Export Helper
 
-`k-pattern` extracts that root pattern from a k script.
+`patterns/from-k.mjs` extracts that root pattern from a k script. It is a
+repository helper, not an installed `package.json` binary.
 
 It:
 
@@ -84,7 +85,7 @@ It:
 Example:
 
 ```bash
-echo '?< {} nil, { $bits car, X cdr } cons > = X' | k-pattern
+echo '?< {} nil, { $bits car, X cdr } cons > = X' | node ./patterns/from-k.mjs
 ```
 
 Typical output:
@@ -101,8 +102,8 @@ The active wire format is:
 encode($pattern_value : $pattern) encode(value : decoded_pattern)
 ```
 
-So the property-list array printed by `k-pattern` is a readable externalization
-of the same pattern information carried in the wire stream.
+So the property-list array printed by `patterns/from-k.mjs` is a readable
+externalization of the same pattern information carried in the wire stream.
 
 `k-parse --input-pattern ...` and `k-parse --input-type ...` both ultimately
 produce the same kind of root pattern used to interpret textual values.

package/DOCS/REPL.md

@@ -1,13 +1,14 @@
 # k Interpreter
 
-`repl2.mjs` is the interactive k interpreter. `k-repl` and `k-repl2` both
-start it.
+`repl.mjs` is the interactive k interpreter. After linking or installing the
+package, start it with `k-repl`.
 
 The interpreter keeps a live `.klib`-style state in memory:
 
 - registered codes
 - compiled relations
 - human aliases for both
+- metadata origins used to recover aliases
 - the current value flowing through the session
 
 Raw k snippets compile on top of that state. You can also export the current
@@ -142,15 +143,16 @@ the file unless `--no-alias` is used.
 
 ### `:load [--no-alias] file.klib`
 
-Decodes the library file and merges its codes, relations, and metadata into the
-session. Aliases are recovered from library metadata unless `--no-alias` is
-used.
+Reads the plain-JSON library file and merges its codes, relations, aliases, and
+metadata into the session. Aliases are recovered from `meta[hash].origins[]`
+unless `--no-alias` is used.
 
 ## Export
 
 ### `:klib file`
 
-Writes the current interpreter state as a `.klib` library.
+Writes the current interpreter state as a plain-JSON `.klib` library. The
+library has `main: null`; it has no binary header and no object payload version.
 
 ### `:ko file expr`
 

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

@@ -113,7 +113,7 @@ Each node in the value tree is encoded based on its automaton state:
 
 For type `bnat`, intuitively binary natural numbers defined by `$bnat = < bnat 0, bnat 1, {} _ >`, we get
 
-```k-repl
+```text
 > :C bnat
 $ bnat = < @... 0, @... 1, {} _ >;  -- @...
 ```

package/DOCS/book.md

@@ -1,5 +1,5 @@
 ---
-title: "k-language"
+title: "k"
 author: "W. Fraczak"
 ---
 
@@ -15,32 +15,28 @@ author: "W. Fraczak"
 
 </div>
 
-# The k-language Book
-
-This book describes the k programming language - a minimal functional language for transforming tree-structured data using partial functions and algebraic data types.
-
-## Table of Contents
-
-1. [Introduction](book/01-introduction.md)
-2. [Syntax and Values](book/02-syntax-and-values.md)  
-3. [Types as Finite Automata](book/03-types-as-finite-automata.md)
-4. [Partial Functions and Composition](book/04-partial-functions-and-composition.md)
-5. [Typing, Filters, and Normalization](book/05-typing-filters-and-normalization.md)
-6. [Values in Memory](book/06-values-in-memory.md)
-7. [The Partial Function ABI](book/07-the-partial-function-abi.md)
-8. [Operational Semantics and Execution](book/08-operational-semantics-and-execution.md)
-9. [Compiler Architecture](book/09-compiler-architecture.md)
-10. [From AST to Intermediate Representation](book/10-from-ast-to-intermediate-representation.md)
-11. [LLVM Basics](book/11-llvm-basics.md)
-12. [Code Generation](book/12-code-generation.md)
-13. [Linking and Execution](book/13-linking-and-execution.md)
-14. [Canonical Serialization](book/14-canonical-serialization.md)
-15. [Optimization and Folding](book/15-optimization-and-folding.md)
-16. [Toward a Universal Schema Registry](book/16-toward-a-universal-schema-registry.md)
+# The k Book
+
+This book describes the k programming language: a minimal functional language
+for transforming tree-structured data using partial functions and algebraic
+data types.
+
+## Available Chapters
+
+- [Introduction](book/01-introduction.md)
+- [Syntax and Values](book/02-syntax-and-values.md)
+- [Types as Finite Automata](book/03-types-as-finite-automata.md)
+- [Partial Functions and Composition](book/04-partial-functions-and-composition.md)
+- [Typing, Filters, and Normalization](book/05-typing-filters-and-normalization.md)
+- [Values in Memory](book/06-values-in-memory.md)
+- [The Partial Function ABI](book/07-the-partial-function-abi.md)
+- [Operational Semantics and Execution](book/08-operational-semantics-and-execution.md)
+- [Compiler Architecture](book/09-compiler-architecture.md)
+- [From AST to Intermediate Representation](book/10-from-ast-to-intermediate-representation.md)
+- [Canonical Serialization](book/14-canonical-serialization.md)
 
 ## Appendices
 
-- [Appendix A: Implementing a Prototype Compiler in Python](book/appendix-a-implementing-a-prototype-compiler-in-python.md)
 - [Appendix B: Incorporating External Predefined Types and Functions](book/appendix-b-incorporating-external-predefined-types-and-functions.md)
 
 ---