@fraczak/k 6.10.2 → 6.10.3

package/DOCS/REPL.md

@@ -1,7 +1,7 @@
 # k Interpreter
 
-`repl.mjs` is the interactive k interpreter. After linking or installing the
-package, start it with `k-repl`.
+`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:
 
@@ -11,9 +11,9 @@ The interpreter keeps a live `.klib`-style state in memory:
 - 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 active
-library closure as a `.klib` file or compile an executable `.ko` object from
-an expression in the session context.
+Raw k snippets compile on top of that state. You can also export the
+active library closure as a `.klib` file or compile an executable `.ko`
+object from an expression in the session context.
 
 ## Prompt Model
 
@@ -22,11 +22,11 @@ There are two kinds of input:
 - commands, starting with `:`
 - raw k source
 
-Commands execute immediately, but only when there is no open raw snippet in the
-buffer.
+Commands execute immediately, but only when there is no open raw snippet
+in the buffer.
 
-Raw k source is accumulated until the interpreter can decide the snippet is
-complete.
+Raw k source is accumulated until the interpreter can decide the snippet
+is complete.
 
 ## Commands
 
@@ -74,8 +74,8 @@ Examples:
 The interpreter uses these rules, in order:
 
 1. If the line ends with `\` followed only by spaces, keep buffering.
-2. If the line ends with `;` followed only by spaces, that line definitively
-   closes the snippet.
+2. If the line ends with `;` followed only by spaces, that line
+   definitively closes the snippet.
 3. Otherwise, try to parse the buffered snippet:
    - if it is a complete k program, compile it now
    - if it is a valid prefix, wait for more input
@@ -83,13 +83,13 @@ The interpreter uses these rules, in order:
 
 After a snippet is accepted:
 
-- if it has a terminal expression, compile it and evaluate it on the current
-  value
+- if it has a terminal expression, compile it and evaluate it on the
+  current value
 - if it is definitions only, compile it into the current state and print
   nothing on success
 
-This makes raw snippets useful both for interactive evaluation and for growing
-the live library context.
+This makes raw snippets useful both for interactive evaluation and for
+growing the live library context.
 
 ## State
 
@@ -101,15 +101,16 @@ The interpreter keeps:
 - `relAliases`: human relation names to canonical hashes
 - `value`: current value, initially `{}`
 
-Definitions are content-addressed. Rebinding an alias changes the name-to-hash
-mapping, but older canonical definitions remain available by hash.
-They stay available in the live session, but `:klib` omits historical
-relations that are no longer reachable from an active relation alias.
+Definitions are content-addressed. Rebinding an alias changes the
+name-to-hash mapping, but older canonical definitions remain available
+by hash. They stay available in the live session, but `:klib` omits
+historical relations that are no longer reachable from an active
+relation alias.
 
 ## Alias Resolution
 
-Before compiling user input, the interpreter injects an alias preamble so human
-names can be reused naturally:
+Before compiling user input, the interpreter injects an alias preamble
+so human names can be reused naturally:
 
 ```k
 $ nat = @...;
@@ -119,8 +120,8 @@ succ = @...;
 
 Type aliases use `$ name = @hash;`. Relation aliases use `name = @hash;`.
 
-Diagnostic locations are remapped back to the visible user snippet, so error
-line numbers do not count the hidden preamble.
+Diagnostic locations are remapped back to the visible user snippet, so
+error line numbers do not count the hidden preamble.
 
 ## Completion
 
@@ -134,36 +135,46 @@ Tab completion covers:
 
 Type aliases also complete in `$name` position inside raw k input.
 
-For codec commands, completion covers `:codec load`, `:codec unload`, `:codec list`,
-file paths after `:codec load`, and codec names after `:input`.
+For codec commands, completion covers `:codec load`, `:codec unload`,
+`:codec list`, file paths after `:codec load`, and codec names after
+`:input`.
 
 ## Loading
 
 ### `:load [--no-alias] file.k`
 
-Compiles the source in the current library context, merges the resulting codes
-and relations into the session, and recovers aliases from user-defined names in
-the file unless `--no-alias` is used.
+Compiles the source in the current library context, merges the resulting
+codes and relations into the session, and recovers aliases from
+user-defined names in the file unless `--no-alias` is used.
 
 ### `:load [--no-alias] file.klib`
 
-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.
+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.
 
-## Codecs
+## Codecs and Numerical Values
 
-A codec is a recipe for translating between external text and enveloped *k* values:
+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 = < {} _, bits 0, bits 1 >`).
+
+A codec translates between external text and enveloped *k* values:
 - `parse(text)`: parses an external string into an enveloped *k* value.
-- `print(value)`: serializes an enveloped *k* value to external string, throwing an `Error` if the value is not representable.
+- `print(value)`: serializes an enveloped *k* value to external string,
+  throwing an `Error` if the value is not representable.
+
+Codecs can define a family of target patterns (e.g. `int` parses/prints
+single integers as well as lists like `[0,1,2]`).
 
-Codecs can define a family of target patterns (e.g. `int` parses/prints single integers as well as lists like `[0,1,2]`).
+For printing in the REPL, every value is printed with the standard *k*
+envelope representation, followed by lines for all loaded codecs that can
+format it:
 
-For printing in the REPL, every value is printed with the standard *k* envelope representation, followed by lines for all loaded codecs that can format it:
 ```text
-> 42 int
+> :input int.mjs 42
 {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
-int: 42
+int.mjs: 42
 ```
 
 For a complete guide to writing a new codec module, see
@@ -171,7 +182,9 @@ For a complete guide to writing a new codec module, see
 
 ### `:codec load file`
 
-Loads a codec module from an ES module file (e.g. `:codec load codecs/int.mjs`). Codecs are identified by their file name, and export `parse(text)` and `print(value)` functions.
+Loads a codec module from an ES module file (e.g.
+`:codec load codecs/int.mjs`). Codecs are identified by their file name,
+and export `parse(text)` and `print(value)` functions.
 
 ### `:codec unload name`
 
@@ -185,7 +198,8 @@ Lists all currently loaded codecs and their source files.
 
 Parses external input using the specified codec file.
 
-- **Interactive mode**: `:input <codec.mjs>` switches the REPL prompt to `<codec.mjs>> `, and the next input line is parsed using that codec:
+- **Interactive mode**: `:input <codec.mjs>` switches the REPL prompt
+  to `<codec.mjs>> `, and the next input line is parsed using that codec:
   ```text
   > :input json.mjs
   json.mjs> {"hello": "world"}
@@ -193,7 +207,8 @@ Parses external input using the specified codec file.
   json.mjs: {"hello":"world"}
   ```
 
-- **One-line mode**: `:input <codec.mjs> <text>` immediately parses `<text>`:
+- **One-line mode**: `:input <codec.mjs> <text>` immediately parses
+  `<text>`:
   ```text
   > :input int.mjs 42
   {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
@@ -204,20 +219,25 @@ Parses external input using the specified codec file.
   int.mjs: [0,1,2]
   ```
 
-Entering `:input` with no arguments displays usage and a list of loaded codecs.
+Entering `:input` with no arguments displays usage and a list of loaded
+codecs.
 
 ## Evaluation Engines: WASM and JS
 
 The REPL supports two evaluation engines:
 
-- **`wasm`** (default): Compiles k expressions into WebAssembly bytecode via polymorphic kVM lowering. Provides near-native execution speed, tail-call optimization (TCO), and stack safety on deep recursion.
-- **`js`**: The tree-walking JavaScript interpreter. Provides near-zero compilation latency (interprets parsed definitions directly) and convenient runtime inspection.
+- **`wasm`** (default): Compiles k expressions into WebAssembly
+  bytecode via polymorphic kVM lowering. Provides near-native execution
+  speed, tail-call optimization (TCO), and stack safety on deep recursion.
+- **`js`**: The tree-walking JavaScript interpreter. Provides near-zero
+  compilation latency (interprets parsed definitions directly) and
+  convenient runtime inspection.
 
 ### Engine Commands
 
-- `:engine` &mdash; displays active engine (`wasm` or `js`)
-- `:engine wasm` (or `:wasm`) &mdash; switches to the WebAssembly engine
-- `:engine js` (or `:js`) &mdash; switches to the JavaScript engine
+- `:engine` — displays active engine (`wasm` or `js`)
+- `:engine wasm` (or `:wasm`) — switches to the WebAssembly engine
+- `:engine js` (or `:js`) — switches to the JavaScript engine
 
 ### CLI Options
 
@@ -230,8 +250,9 @@ k-repl --engine=wasm  # or k-repl --wasm (default)
 
 ## Timing and Profiling
 
-Timing reporting is enabled by default for all evaluations, reporting elapsed time
-broken down into compilation and runtime execution, annotated with the active engine:
+Timing reporting is enabled by default for all evaluations, reporting
+elapsed time broken down into compilation and runtime execution,
+annotated with the active engine:
 
 ```text
 > {10 int x, 5 int y} plus
@@ -241,30 +262,42 @@ broken down into compilation and runtime execution, annotated with the active en
 
 ## Web REPL (Studio)
 
-The repository provides a standalone, single-file browser REPL: `repl.html`.
+The repository provides a standalone, single-file browser REPL:
+`repl.html`.
 
-- **Zero-install in-browser execution**: Powered by WebAssembly (`wasm-in-process`) and virtual filesystem (VFS).
-- **Interactive UI**: Tab autocompletion, persistent text selection, execution timing badges (`comp: Xms | exec: Yms`), interactive Codecs management modal, and interactive `:input` popup modal.
+- **Zero-install in-browser execution**: Powered by WebAssembly
+  (`wasm-in-process`) and virtual filesystem (VFS).
+- **Interactive UI**: Tab autocompletion, persistent text selection,
+  execution timing badges (`comp: Xms | exec: Yms`), interactive Codecs
+  management modal, and interactive `:input` popup modal.
 - **Build**: Generate `repl.html` locally using:
   ```bash
   npm run build:repl-html
   ```
-- **Live Demo**: Automatically deployed to GitHub Pages via `.github/workflows/pages.yml`.
+- **Live Demo**: Automatically deployed to GitHub Pages via
+  `.github/workflows/pages.yml`.
 
 ## Export
 
+The REPL can export session state to ahead-of-time (AOT) compiled
+artifacts. For full details on all formats, see
+[`DOCS/FILE_FORMATS.md`](./FILE_FORMATS.md).
+
 ### `:klib file`
 
-Writes a plain-JSON `.klib` library rooted at the current relation aliases.
-Relations referenced by those aliases are included transitively. Historical
-relations retained in the live session are omitted when no active alias
-depends on them. The registered code snapshot is still included. The library
-has `main: null`; it has no binary header and no object payload version.
+Writes a plain-JSON `.klib` library rooted at the current relation
+aliases. Relations referenced by those aliases are included
+transitively. Historical relations retained in the live session are
+omitted when no active alias depends on them. The registered code
+snapshot is included. The library has `main: null`; it has no binary
+header and no object payload version.
 
 ### `:ko file expr`
 
-Compiles `expr` as the main expression in the current interpreter context and
-writes the resulting executable `.ko` object.
+Compiles `expr` as the main expression (`main: "__main__"`) in the
+current interpreter context and writes the resulting executable `.ko`
+object container (prefixed by magic header `KOBJ\n`). Running this `.ko`
+skips parsing and type derivation for instant execution.
 
 ## Output
 
@@ -297,3 +330,10 @@ saved nat.klib
 > :ko inc.ko inc
 saved inc.ko (inc)
 ```
+
+## Further Reading
+
+- [DOCS/FILE_FORMATS.md](./FILE_FORMATS.md) —
+  guide to .k, .ko, .klib, and .kvm formats
+- [DOCS/DICTIONARY.md](./DICTIONARY.md) — concept names and terminology
+- [DOCS/CODECS.md](./CODECS.md) — guide to writing codecs

package/DOCS/TEXTUAL_VALUES.md

@@ -2,9 +2,9 @@
 
 `k-parse` and `k-print` work with a textual notation for k values.
 
-It looks like JSON because products print as JSON objects, but semantically it
-is not a generic JSON format. It is a readable notation for values built from
-the two k data constructors:
+It looks like JSON because products print as JSON objects, but
+semantically it is not a generic JSON format. It is a readable
+notation for values built from the two k data constructors:
 
 - product
 - tagged union
@@ -16,7 +16,8 @@ A k value is a tree.
 - A product is a mapping from field labels to child values.
 - A union is a single chosen tag together with its payload value.
 
-There are no primitive leaves. The base leaf is the empty product:
+There are no primitive leaves or built-in numbers. The base leaf is
+the empty product (the unit):
 
 ```text
 {}
@@ -30,9 +31,9 @@ The textual notation used by `k-parse` and `k-print` is:
 - `{"field": value, ...}` for a product
 - `{"tag": value}` for a union
 
-The last form is why the notation only looks like JSON. Syntactically, a
-single-entry object is ambiguous in plain JSON, but in k it is interpreted
-through the inferred or supplied pattern.
+The last form is why the notation only looks like JSON. Syntactically,
+a single-entry object is ambiguous in plain JSON, but in k it is
+interpreted through the inferred or supplied pattern.
 
 Examples:
 
@@ -61,9 +62,9 @@ The native k notation is more explicit for interactive work:
 - product construction: `{ v field, w other }`
 - union introduction: `v |tag`
 
-`k-print` does not emit that native notation. It emits the JSON-like tree
-notation because it is easy to pipe, inspect, and round-trip through standard
-text tooling.
+`k-print` does not emit that native notation. It emits the JSON-like
+tree notation because it is easy to pipe, inspect, and round-trip
+through standard text tooling.
 
 ## `k-parse`
 
@@ -73,8 +74,8 @@ text tooling.
 2. optionally takes an input type or input pattern
 3. produces the binary `pattern + value` stream
 
-When no explicit pattern or type is supplied, `k-parse` derives a witness
-pattern from the textual tree.
+When no explicit pattern or type is supplied, `k-parse` derives a
+witness pattern from the textual tree.
 
 ## `k-print`
 
@@ -84,25 +85,29 @@ pattern from the textual tree.
 2. decodes it to a runtime value with its carried pattern
 3. prints the value tree in JSON-like notation
 
-So `k-print` is not a JSON decoder in the general sense. It is a renderer from
-k runtime values to a JSON-shaped textual notation.
+So `k-print` is not a JSON decoder in the general sense. It is a
+renderer from k runtime values to a JSON-shaped textual notation.
 
 ## Ambiguity and Patterns
 
-The textual tree alone does not always determine whether a single-child node is
-meant as a union or a singleton product. That is why patterns matter.
+The textual tree alone does not always determine whether a single-child
+node is meant as a union or a singleton product. That is why patterns
+matter.
 
-When `k-parse` has no explicit input pattern, it applies the current witness
-rule:
+When `k-parse` has no explicit input pattern, it applies the current
+witness rule:
 
 - empty node => closed product
 - node with multiple children => closed product
 - node with one child => open union by default
 
-An explicit input pattern or input type can force a different interpretation.
+An explicit input pattern or input type can force a different
+interpretation.
 
 ## See Also
 
+- [DOCS/FILE_FORMATS.md](./FILE_FORMATS.md) — guide to
+  .k, .ko, .klib, and .kvm formats
 - [codecs/README.md](../codecs/README.md)
 - [DOCS/PATTERNS.md](./PATTERNS.md)
 - [DOCS/OBJECT_FILE_AND_PATTERN.md](./OBJECT_FILE_AND_PATTERN.md)

package/DOCS/TYPE_DERIVATION.md

@@ -2,12 +2,17 @@
 
 ## 1. Overview
 
-This algorithm infers type constraints for programs consisting of mutually recursive partial functions over algebraic data types (products and unions).
+This algorithm infers type constraints for programs consisting of
+mutually recursive partial functions over algebraic data types
+(products and unions).
 
-**Input:** AST of a `k` program, consisting of function definitions (expressions), which can be seen as a set of recursive equations.
-**Output:** Annotated AST with type patterns (also called filters)
+**Input:** AST of a `k` program, consisting of function definitions
+(expressions), which can be seen as a set of recursive equations.
+**Output:** Annotated AST with type patterns (also called filters).
 
-It is assumed that we have access (through APIs) to a universal "type registry", which provides us with unique (canonical) names for each type.
+All types and relations are canonically identified by immutable
+content-addressed hashes (`@hash`). Human-readable names are local
+aliases.
 
 ## 2. Patterns
 
@@ -22,27 +27,39 @@ A **pattern** represents a set of types:
 | `<>` | Closed union | Exactly specified |
 | `T` | Named type | From type definition |
 
-**Fields:** Each pattern has associated field labels. For open patterns, additional fields may exist. For closed patterns, the field set is exact.
-Unknown-kind patterns have only the open form `(...)`; a closed filter must choose product `{...}`/`{}` or union `<...>`/`<>`.
+**Fields:** Each pattern has associated field labels. For open patterns,
+additional fields may exist. For closed patterns, the field set is exact.
+Unknown-kind patterns have only the open form `(...)`; a closed filter
+must choose product `{...}`/`{}` or union `<...>`/`<>`.
 
-A type pattern is a singleton pattern, i.e., only one type is captured by such a pattern.
+A type pattern is a singleton pattern, i.e., only one type is captured
+by such a pattern.
 
 ## 3. Pattern Graph - A Data Structure Used During Type Derivation
 
-**Nodes:** Patterns organized in a "reps" (representatives) forest, similar to union-find. However, a union of two (or more) different trees always produces a new "rep" (root) node, joining the trees.
-**Edges:** Labeled by field names, pointing to other patterns
-**Representatives:** Root nodes (called reps) represent equivalence classes
+**Nodes:** Patterns organized in a "reps" (representatives) forest,
+similar to union-find. However, a union of two (or more) different trees
+always produces a new "rep" (root) node, joining the trees.
+**Edges:** Labeled by field names, pointing to other patterns.
+**Representatives:** Root nodes (called reps) represent equivalence
+classes.
 
 **Operations:**
 
 - `find(p)` - get representative of pattern `p`
-- `unify(p₁, ..., pₙ)` - merge patterns into equivalence class, potentially adding a new rep (root); the rep gathers all edges of their children
-- `clone(p₁, ..., pₙ)` - generate a copy of the pattern graph connected to the patterns
-- `compact()` - discovers all singleton patterns and replaces them by "Named types"
+- `unify(p₁, ..., pₙ)` - merge patterns into equivalence class,
+  potentially adding a new rep (root); the rep gathers all edges of
+  their children
+- `clone(p₁, ..., pₙ)` - generate a copy of the pattern graph connected
+  to the patterns
+- `compact()` - discovers all singleton patterns and replaces them by
+  named canonical types
 
 ## 4. Unification
 
-`unify(p₁, ..., pₙ)` computes the least upper bound (most specific common pattern); it may add a new node (rep) into the reps forest, but it does not modify any existing pattern node.
+`unify(p₁, ..., pₙ)` computes the least upper bound (most specific
+common pattern); it may add a new node (rep) into the reps forest, but
+it does not modify any existing pattern node.
 
 **Rules:**
 
@@ -50,7 +67,7 @@ A type pattern is a singleton pattern, i.e., only one type is captured by such a
 - **Open + Closed:** Check field inclusion, then become closed
 - **Closed + Closed:** Check field equality, then stay closed
 - **Product ⊥ Union:** Error (incompatible)
-- **Type T:** Unique (canonical name)
+- **Type T:** Unique (canonical `@hash` name)
 
 **Algorithm:**
 
@@ -122,7 +139,8 @@ in(f) = LOOKUP(in(f))
 out(f) = LOOKUP(out(f))
 ```
 
-Once the type derivation for the defining expression for `f` is done, the input and output patterns are stored and will be used.
+Once the type derivation for the defining expression for `f` is done, the
+input and output patterns are stored and will be used.
 
 ### Type `$ T`
 
@@ -165,19 +183,23 @@ For each SCC (in topological order):
   Repeat until convergence (max 10 iterations):
     For each function `f` in SCC:
       1. Compact `f`'s pattern graph
-      2. For each occurrence `o` of `g` in `f`, clone(in(g), out(g)) and unify input and output patterns of `o` with the corresponding cloned patterns
+      2. For each occurrence `o` of `g` in `f`, clone(in(g), out(g))
+         and unify input and output patterns of `o` with the
+         corresponding cloned patterns
 
     If pattern graphs unchanged: break
 ```
 
 ## 7. Compaction
 
-**Purpose:** Replace all pattern nodes with their reps and replace all singleton patterns with types.
+**Purpose:** Replace all pattern nodes with their reps and replace all
+singleton patterns with types.
 
 **Algorithm:**
 
 ```text
-1. Build a new graph only on reps (keep the mappings from pattern node to its rep)
+1. Build a new graph only on reps (keep the mappings from pattern
+   node to its rep)
 2. Identify singleton patterns (closed patterns with no open ancestors)
 3. Register singletons as named types and use them as type pattern nodes
 ```
@@ -202,7 +224,8 @@ For each function f in SCC:
 Converged = (current_state == previous_state)
 ```
 
-**Guarantee:** Monotonic refinement + iteration bound ensures termination
+**Guarantee:** Monotonic refinement + iteration bound ensures
+termination.
 
 ## 9. Error Handling
 
@@ -210,7 +233,8 @@ Converged = (current_state == previous_state)
 
 - Product vs Union
 - Closed pattern field mismatch
-- Two distinct type patterns (types with different canonical names) are always incompatible
+- Two distinct type patterns (types with different canonical `@hash`
+  names) are always incompatible
 
 **Other errors:**
 
@@ -227,4 +251,26 @@ Converged = (current_state == previous_state)
 ## 10. Implementation Notes
 
 - Use reps forest for performing and tracing unification
-- Compact only at the end of an iteration to keep unification reasons for error messages
+- Compact only at the end of an iteration to keep unification reasons
+  for error messages
+
+## 11. Role in Ahead-Of-Time (AOT) Compilation
+
+This type derivation algorithm forms the core of Ahead-Of-Time (AOT)
+type checking in `k`.
+
+When compiling `.k` source code into an executable object (`.ko`),
+a library (`.klib`), or a polymorphic kVM template (`.kvm`), type
+derivation converges all principal type graphs beforehand. The resulting
+artifacts store fully derived principal pattern graphs, allowing
+downstream execution and linking to bypass cold-start type derivation
+entirely.
+
+## Further Reading
+
+- [DOCS/FILE_FORMATS.md](./FILE_FORMATS.md) — guide to
+  .k, .ko, .klib, and .kvm formats
+- [DOCS/CONVERGENCE.md](./CONVERGENCE.md) — convergence strategies
+- [DOCS/OBJECT_FILE_AND_PATTERN.md](./OBJECT_FILE_AND_PATTERN.md) —
+  object format and pattern encoding
+- [DOCS/DICTIONARY.md](./DICTIONARY.md) — concept names and terminology