@fraczak/k 6.0.1 → 6.0.2

package/DOCS/REPL.md

@@ -1,189 +1,189 @@
 # k Interpreter
 
-## Overview
+`repl2.mjs` is the interactive k interpreter. `k-repl` and `k-repl2` both
+start it.
 
-`repl2.mjs` is the interactive k interpreter. It uses the `.klib` format as
-its internal state: definitions accumulate incrementally, expressions compile
-in the context of the current library state, and the session can be exported as
-either a reusable `.klib` library or an executable `.ko` object.
+The interpreter keeps a live `.klib`-style state in memory:
 
-`k-repl` and `k-repl2` both start this interpreter. The primary interface is
-command-based: commands start with `:`, and raw k input remains available as a
-short form for quick interactive work.
+- registered codes
+- compiled relations
+- human aliases for both
+- the current value flowing through the session
 
-## State Model
+Raw k snippets compile on top of that state. You can also export the current
+session as a `.klib` library or compile an executable `.ko` object from an
+expression in the session context.
 
-```
-┌─────────────────────────────────────────────────┐
-│  codes:   { hash → code definition }            │  ← registered types
-│  rels:    { @hash → typed relation }            │  ← compiled relations
-│  aliases: { name → @hash }                      │  ← human names
-│  value:   current value (with .pattern)         │  ← last result
-│  lastMain: last relation/expression             │  ← default .ko main
-└─────────────────────────────────────────────────┘
-```
+## Prompt Model
 
-- `codes` and `rels` are the live .klib content.
-- `aliases` maps human names to canonical hashes. Redefining a name updates
-  the alias; the old definition remains in `rels` (content-addressed, no conflict).
-- `value` is the current pipeline value, initially `{}`.
+There are two kinds of input:
 
-## Commands
+- commands, starting with `:`
+- raw k source
+
+Commands execute immediately, but only when there is no open raw snippet in the
+buffer.
 
-Each line is a command. Multiline commands can be continued with a trailing
-`\`.
+Raw k source is accumulated until the interpreter can decide the snippet is
+complete.
 
-Tab completion is available for command names, file paths in file-taking
-commands such as `:load` and `:export`, and canonical names that start with
-`@`.
+## Commands
 
-| Command | Description |
-|---------|-------------|
-| `:type name = <...>` | Define a type |
-| `:rel name = expr` | Define a relation |
+| Command | Meaning |
+| --- | --- |
+| `:help` | Show command summary |
+| `:type name = <...>` | Define a type alias |
+| `:type name` | Show the canonical definition of a type |
+| `:code name` | Alias for `:C name` |
+| `:rel name = expr` | Define a relation alias |
 | `:def name = expr` | Alias for `:rel` |
-| `:run expr` | Run an expression on the current value |
-| `:t name` | Show type signature of a relation |
-| `:d name` | Show definition of a relation |
-| `:type name` | Show definition of a type |
+| `:run expr` | Evaluate `expr` on the current value |
+| `:eval expr` | Alias for `:run` |
+| `:t name` | Show relation input/output filters |
+| `:d name` | Show relation definition |
+| `:C name` | Show canonical code definition |
 | `:codes` | List type aliases |
 | `:rels` | List relation aliases |
-| `:save file` | Save current state as `.klib` |
-| `:klib file` | Export current state as `.klib` |
-| `:ko file [expr]` | Export executable `.ko`; uses `expr` or the last relation/expression as main |
-| `:export file [expr]` | Export by extension: `.klib` or `.ko` |
-| `:load file` | Load `.k` source or `.klib` into state |
-| `:val` | Print current value with full detail |
-| `:reset` | Clear all state |
-| `:help` | Show available commands |
-| `:quit` | Exit |
-
-The `/` character is never treated as a command prefix, because it is part of
-k expression syntax.
+| `:load file` | Load `.k` source or `.klib` into the current state |
+| `:klib file` | Export current state as a `.klib` library |
+| `:ko file expr` | Export a `.ko` executable with `expr` as main |
+| `:val` | Print current value and JSON form |
+| `:reset` | Reset interpreter state |
+| `:quit` / `:exit` | Exit |
 
-## Shorthand Input
+## Raw Snippets
 
-Raw k input is still accepted:
+Raw input is compiled as k source on top of the current state.
 
-- `$ name = <...>;` is treated like `:type name = <...>`.
-- `name = expr;` is treated like `:rel name = expr`.
-- Any other non-command input is treated like `:run expr`.
-
-For command-based use, semicolons are optional in `:type` and `:rel`.
+Examples:
 
-## Input Handling
+```k
+> {} |succ
+```
 
-### Type Definition: `:type name = <...>`
+```k
+> $ bool = <{} true, {} false>;
+```
 
-- Parse and register the code via `codes.register`.
-- Store canonical hash in `aliases[name]`.
-- Print: `$ name = @hash`
+```k
+> $ bool = <{} true, {} false>
+  ; not = $bool </true | false, {} | true >
+  ; {} |true not
+```
 
-### Relation Definition: `:rel name = expr`
+The interpreter uses these rules, in order:
 
-- Build source: alias preamble + definition + `name` as main expression.
-- Compile with current `{codes, rels}` as library context.
-- Store compiled rel in `rels[@hash]`.
-- Update `aliases[name] → @hash`.
-- Print: `name = @hash`
+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.
+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
+   - otherwise report the parse error immediately
 
-### Expression Evaluation: `:run expr`
+After a snippet is accepted:
 
-- Build source: alias preamble + expression as main.
-- Compile with current library context.
-- Run on current `value`.
-- Update `value` with result.
-- Print result with envelope (see Output Format).
+- 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
 
-## Alias Preamble
+This makes raw snippets useful both for interactive evaluation and for growing
+the live library context.
 
-Before compiling any user input, the REPL prepends alias definitions so that
-human names resolve to library relations:
+## State
 
-```k
-add = @mKEA...; succ = @Swjz...; nat = @w8iS...;
-<user input>
-```
+The interpreter keeps:
 
-For type aliases, the preamble uses `$ name = @hash;` syntax (referencing
-an existing canonical code by hash).
+- `codes`: canonical code definitions
+- `rels`: canonical compiled relations
+- `typeAliases`: human type names to canonical hashes
+- `relAliases`: human relation names to canonical hashes
+- `value`: current value, initially `{}`
 
-This reuses the existing parser and compiler without modification.
+Definitions are content-addressed. Rebinding an alias changes the name-to-hash
+mapping, but older canonical definitions remain available by hash.
 
-## Output Format
+## Alias Resolution
 
-Values are printed as:
+Before compiling user input, the interpreter injects an alias preamble so human
+names can be reused naturally:
 
-```
-<value-in-k-syntax> ?<pattern-as-filter>
+```k
+$ nat = @...;
+succ = @...;
+<user snippet>
 ```
 
-Examples:
+Type aliases use `$ name = @hash;`. Relation aliases use `name = @hash;`.
 
-```
-> {}|zero|succ|succ
-{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+Diagnostic locations are remapped back to the visible user snippet, so error
+line numbers do not count the hidden preamble.
 
-> {{}|1 car, {}|nil cdr}|cons
-{{{}|1 car, {}|nil cdr}|cons} ?<{} nil, {<{} 0, {} 1> car, X cdr} cons>=X
-```
+## Completion
 
-Uses `valueToK` and `propertyListToFilter` from
-`codecs/runtime/show-value.mjs`.
+Tab completion covers:
 
-When the result is `undefined`, print:
+- command names after `:`
+- file paths for `:load`, `:klib`, and `:ko`
+- type aliases
+- relation aliases
+- canonical names beginning with `@`
 
-```
-... undefined
-```
+Type aliases also complete in `$name` position inside raw k input.
 
-## Loading Files
+## Loading
 
 ### `:load file.k`
 
-- Parse and compile the source as a library in the current context.
-- Merge resulting codes and rels into state.
-- Update aliases from `relAlias` (source name → hash).
+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.
 
 ### `:load file.klib`
 
-- Decode the .klib file.
-- Merge codes and rels into state.
-- Update aliases from `meta` (recover source names from origins).
-
-## Exporting
+Decodes the library file and merges its codes, relations, and metadata into the
+session.
 
-### `:save file.klib`
+## Export
 
-- Serialize current `{codes, rels, meta, main: null}` as a .klib.
-- `meta` is built from the alias table (each alias → origin entry).
+### `:klib file`
 
-### `:klib file.klib`
+Writes the current interpreter state as a `.klib` library.
 
-- Alias for saving the current state as a `.klib`.
+### `:ko file expr`
 
-### `:ko file.ko [expr]`
+Compiles `expr` as the main expression in the current interpreter context and
+writes the resulting executable `.ko` object.
 
-- Compile `expr` as the executable object's main expression.
-- If `expr` is omitted, reuse the last relation definition or expression that
-  was evaluated in the interpreter.
-- The current `.klib` state is passed as the compilation library context.
+## Output
 
-### `:export file [expr]`
+Evaluated values print in k syntax together with the inferred envelope:
 
-- If `file` ends in `.klib`, save the current library state.
-- If `file` ends in `.ko`, compile an executable object using `expr` or the
-  last main expression.
+```text
+{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+```
 
-## Example
+`undefined` prints as:
 
+```text
+... undefined
 ```
+
+`valueToK`, `propertyListToFilter`, and `valueWithEnvelopeToK` from
+`codecs/runtime/show-value.mjs` are used for rendering.
+
+## Example Session
+
+```text
 > :type nat = <{} zero, nat succ>
 $ nat = @...
 > :rel succ = |succ
 succ = @...
-> :run succ
-{}|succ ?<{} succ, ...>
+> {} |zero
+{zero: {}} ?<{} zero, X succ>=X
+> :t succ
+succ : ?X  -->  ?<{} zero, X succ>=X  (@...)
 > :klib nat.klib
 saved nat.klib
 > :ko succ.ko succ

package/DOCS/TEXTUAL_VALUES.md

@@ -0,0 +1,108 @@
+# Textual k Values
+
+`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:
+
+- product
+- tagged union
+
+## The Value Model
+
+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:
+
+```text
+{}
+```
+
+## Textual Notation
+
+The textual notation used by `k-parse` and `k-print` is:
+
+- `{}` for the empty product
+- `{"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.
+
+Examples:
+
+```text
+{}
+```
+
+```text
+{"point":{"x":{},"y":{}}}
+```
+
+```text
+{"succ":{"succ":{"zero":{}}}}
+```
+
+The last example is the k value usually written in native notation as:
+
+```k
+{}|zero|succ|succ
+```
+
+## Relation to Native k Notation
+
+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-parse`
+
+`k-parse`:
+
+1. reads textual k values
+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.
+
+## `k-print`
+
+`k-print`:
+
+1. reads the binary `pattern + value` stream
+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.
+
+## 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.
+
+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.
+
+## See Also
+
+- [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

@@ -0,0 +1,230 @@
+# Type Derivation Algorithm
+
+## 1. Overview
+
+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) - 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.
+
+## 2. Patterns
+
+A **pattern** represents a set of types:
+
+| Notation | Meaning | Fields |
+|----------|---------|--------|
+| `(...)` | Open unknown | Any |
+| `{...}` | Open product | At least specified |
+| `<...>` | Open union | At least specified |
+| `{}` | Closed product | Exactly specified |
+| `<>` | 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 `<...>`/`<>`.
+
+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
+
+**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"
+
+## 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; the operation does not modify any existing pattern node
+
+**Rules:**
+
+- **Open + Open:** Merge field sets, stay open
+- **Open + Closed:** Check fields ⊆, become closed
+- **Closed + Closed:** Check fields =, stay closed
+- **Product ⊥ Union:** Error (incompatible)
+- **Type T:** Unique (canonical name)
+
+**Algorithm:**
+
+```text
+1. Find representatives of all patterns
+2. If the set of reps is a singleton, return it as the result
+3. Compute merged pattern descriptor
+4. Create new representative node
+5. Migrate edges from old representatives
+6. Recursively unify edge destinations for each field name
+```
+
+## 5. Local Typing Rules
+
+For each expression type, define input/output pattern constraints:
+
+### Composition `(e₁ e₂ ... eₙ)`
+
+```text
+in((e₁ e₂ ... eₙ)) = in(e₁)
+out(eᵢ) = in(eᵢ₊₁)  for i = 1..n-1
+out((e₁ e₂ ... eₙ)) = out(eₙ)
+```
+
+In case when `n=0`, identity, `()`
+
+```text
+in(()) = out(())
+```
+
+### Product `{e₁ l₁, ..., eₙ lₙ}`
+
+```text
+in(e₁) = ... = in(eₙ) = in({e₁ l₁, ..., eₙ lₙ})
+out({e₁ l₁, ..., eₙ lₙ}) = {} with edges lᵢ → out(eᵢ)
+```
+
+### Variant constructor `|l`
+
+```text
+out(|l) = <...> with edge l → in(|l)
+```
+
+### Union `<e₁, ..., eₙ>`
+
+```text
+in(e₁) = ... = in(eₙ) = in(<e₁, ..., eₙ>)
+out(e₁) = ... = out(eₙ) = out(<e₁, ..., eₙ>)
+```
+
+### Projection
+
+#### Dot `.l`
+
+```text
+in(.l) = {...} with edge l → out(.l)
+```
+
+#### Div `/t`
+
+```text
+in(/t) = <...> with edge t → out(/t)
+```
+
+### Function reference `f`
+
+```text
+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.
+
+### Type `$ T`
+
+```text
+in(T) = out(T) = pattern(T)
+```
+
+### Filter `? F`
+
+```text
+see patterns.filterToPattern(F)
+```
+
+Filter expression is a syntax for describing pattern graphs.
+
+## 6. Global Algorithm
+
+### Phase 1: Initialization
+
+```text
+For each function definition:
+  1. Create empty pattern graph
+  2. Traverse expression AST
+  3. Create [input, output] pattern pair per node of the AST
+  4. Apply local typing rules
+```
+
+### Phase 2: Dependency Analysis
+
+```text
+1. Build dependency graph (function → referenced functions)
+2. Compute strongly connected components (SCCs)
+3. Topologically sort SCCs (bottom-up)
+```
+
+### Phase 3: Fixed-Point Iteration
+
+```text
+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
+      
+    If pattern graphs unchanged: break
+```
+
+## 7. Compaction
+
+**Purpose:** Replace all pattern nodes by their reps and replace all singleton patterns by types.
+
+**Algorithm:**
+
+```text
+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
+```
+
+## 8. Convergence
+
+**Criterion:** Pattern graph structure unchanged between iterations
+
+**Measured by:** 
+1. Representative forest structure (parent pointers)
+2. Edge sets for each representative
+3. Pattern descriptors for each representative
+
+**Algorithm:**
+```text
+For each function f in SCC:
+  1. Serialize reps forest: {nodeId → parentId}
+  2. Serialize edge structure: {repId → {label → [targetReps]}}
+  3. Serialize pattern info: {repId → {pattern, fields, type}}
+  4. Combine into canonical form
+
+Converged = (current_state == previous_state)
+```
+
+**Guarantee:** Monotonic refinement + iteration bound ensures termination
+
+## 9. Error Handling
+
+**Unification errors:**
+
+- Product vs Union
+- Closed pattern field mismatch
+- Two distinct type patterns (types with different canonical names) are always incompatible
+
+**Other errors:**
+
+- Undefined function reference
+- Iteration limit exceeded
+
+**Error reporting should include:**
+
+- Source location
+- Expression type
+- Conflicting patterns
+- Unification trace
+
+## 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