@fraczak/k 6.1.2 → 6.2.0

package/AGENTS.md

@@ -5,12 +5,12 @@
 - `k_compiler/` contains the Python prototype compiler and supporting modules.
 - `type_registry/` houses registry experiments and grammar artifacts.
 - `Examples/` and `DOCS/` provide sample programs and design notes.
-- Tests live in top-level `test*.mjs`, `Code-derivation-tests/`, and `tests.sh`.
+- Tests live in `tests/`, with type-derivation cases in `tests/code-derivation/`.
 
 ## Build, Test, and Development Commands
 - `npm install` installs dev dependencies and runs `prepare` to generate parsers.
 - `npm run prepare` regenerates `parser.mjs` and `valueParser.mjs` from `.jison` grammars.
-- `npm test` runs the full suite (`test.mjs`, `Code-derivation-tests/*.mjs`, `test-fingerprint.mjs`, `tests.sh`).
+- `npm test` runs the full suite through `scripts/run-tests.mjs`.
 - `node repl.mjs` (or `k-repl`) starts the interactive REPL.
 - `./k.mjs -k <file.k>` executes a k script on binary pattern+value stream input from stdin or a file; use `k-parse` and `k-print` at the boundaries.
 
@@ -21,8 +21,8 @@
 - Grammar sources are `parser.jison` and `valueParser.jison`; generated files should not be hand-edited.
 
 ## Testing Guidelines
-- Add runtime tests alongside `test.mjs` or new `test-*.mjs` files.
-- Add type-derivation coverage in `Code-derivation-tests/` (one case per file is typical).
+- Add runtime tests alongside `tests/test.mjs` or new `tests/test-*.mjs` files.
+- Add type-derivation coverage in `tests/code-derivation/` (one case per file is typical).
 - Verify locally with `npm test` before opening a PR.
 
 ## Commit & Pull Request Guidelines

package/CLAUDE.md

@@ -60,5 +60,5 @@ npm test  # Run comprehensive test suite (unit tests, derivation tests, shell te
 
 - No external runtime dependencies (only jiwson for parser generation)
 - Uses ES6 modules (.mjs files) throughout
-- Extensive test suite in `Code-derivation-tests/` for type system validation
+- Extensive test suite in `tests/code-derivation/` for type system validation
 - REPL supports commands like `:C name` (show canonical type), `:t name` (show relation type), and `:d name` (show relation definition)

package/DOCS/BIG_PICTURE.md

@@ -12,7 +12,7 @@ with that tree.
 
 ### Types (codes)
 
-Formally, a _type_ is a (subclass of finite tree automata. The type defines a set of its values,
+Formally, a _type_ is a finite tree automaton. The type defines a set of values,
 which corresponds to the set of trees accepted by the automaton.
 Therefore, every type admits a unique normal form in terms of its minimal deterministic tree automaton.
 
@@ -38,7 +38,7 @@ Given a finite (possibly empty) set of types `t1, t2, ..., tn` and a set of pair
   Each projection function maps a value of type `{t1 l1, t2 l2, ..., tn ln}`
   into a value of type `t1`, `t2`, `...`, `tn`, respectively.
 - by `< t1 l1, t2 l2, ..., tn ln >`, we define a _union type_ with exactly `n` projection functions `/l1`, `/l2`, `...`, `/ln`,
-  maps a value of type `<t1 l1, t2 l2, ..., tn ln>` into a value of type `t1`, `t2`, `...`, `tn`, respectively.
+  mapping a value of type `<t1 l1, t2 l2, ..., tn ln>` into a value of type `t1`, `t2`, `...`, `tn`, respectively.
 
 Intuitively, the projection functions on a product type are all total (meaning, they are defined for every value of the
 input product type), whereas in the case of a union type, exactly one projection function is defined
@@ -68,7 +68,7 @@ Two (possibly recursive) codes are equivalent iff they are bisimilar over their
 
 ### Filters (patterns)
 
-A _filter_ is a way of representing a _pattern_, i.e, a set of types sharing some structure.
+A _filter_ is a way of representing a _pattern_, i.e., a set of types sharing some structure.
 For example, if I wanted to refer to all product types that have a field `f` of type `T`,
 I would write: `?{ T f, ... }`. In general, a filter is defined by:
 
@@ -158,14 +158,14 @@ registry of types (schemas) and functions.
 
 ## Typing and Polymorphism (codes and patterns)
 
-Abstract Syntax Tree of a program consists of a dictionary of _type definitions_,
-a dictionary  of _function definitions_, and the final _main expression_.
+The abstract syntax tree of a program consists of a dictionary of _type definitions_,
+a dictionary of _function definitions_, and the final _main expression_.
 
 In principle, the initial form of the Abstract Syntax Tree, _raw_ AST, is enough to evaluate
 the program on an input.
 
-Our objective however is to compute canonical representations for types and normalized
-representations for functions, so they could be reused.
+Our objective, however, is to compute canonical representations for types and normalized
+representations for functions so they can be reused.
 
 The normalization steps are:
 
@@ -225,7 +225,7 @@ Functions `inc` and `inc3` are (non-polymorphic) functions of types
 `${ bit overflown, byte byte } -> ${ bit overflown, byte byte }`, respectively.
 
 Function `inc_o` is a polymorphic function of type patterns: `?X -> ${ byte byte, bit overflown }`
-with following constraints:
+with the following constraints:
 
 - `?X` is a product type with at least two fields: `byte` and `overflown`, denoted by:
    > `?{ $byte byte, Z overflown, ...}`;
@@ -269,7 +269,7 @@ The registry will be a key-value store, where the key is the hash of the normali
 and the value is the normalized type itself.
 
 All functions (non-polymorphic and polymorphic) will be renamed by the hash of their normalized
-definition and stored in the similar key-value store.
+definition and stored in a similar key-value store.
 
 Non-polymorphic functions can be easily indexed by the hashes of their input and output types
 so that we can quickly find the function we need.
@@ -280,7 +280,7 @@ Indexing polymorphic functions seems complicated (TODO).
 The language is designed to transform _codes_, i.e., serialized typed values, i.e., trees
 accepted by a tree automaton, into other _codes_.
 The transformation is done by partial functions as defined in the language.
-The non-recursive and tail-recursive (and even some non-tail recursive) functions can
+The non-recursive and tail-recursive (and even some non-tail-recursive) functions can
 be compiled into deterministic finite (pushdown) transducers.
 
 ### AND-OR graphs for encoding and decoding codes

package/DOCS/DIVERGENCE_DETECTION.md

@@ -19,6 +19,6 @@ HEAD(?F E) = HEAD(E)
 HEAD($T E) = HEAD(E)
 HEAD((E1 E2 ...)) = HEAD(E1)
 HEAD({ E1 f1, E2 f2, ... }) = HEAD(E1) union HEAD(E2) union ...
-HEAD(<E1, E2, ...>) = {}   -- heads of a union is empty set
+HEAD(<E1, E2, ...>) = {}   -- the head of a union is the empty set
 HEAD(/ tag) = HEAD(. lab) = HEAD(| tag) = {}
 ```

package/DOCS/OBJECT_FILE_AND_PATTERN.md

@@ -305,3 +305,9 @@ shape is the same object payload shape with `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.
+
+The REPL `:klib` command uses active relation aliases as roots. It stores their
+transitive relation closure and omits historical content-addressed relations
+that remain in the live session after alias rebinding but are no longer
+reachable from an active alias. Its `codes` field remains the registered code
+snapshot needed to reload the library.

package/DOCS/REPL.md

@@ -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 current
-session as a `.klib` library 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
 
@@ -49,7 +49,7 @@ complete.
 | `:codec list` | List loaded REPL codecs |
 | `:input type [codec]` | Read the next line as codec input for a singleton type |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
-| `:klib file` | Export current state as a `.klib` library |
+| `:klib file` | Export the active relation closure 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 |
@@ -62,7 +62,7 @@ Raw input is compiled as k source on top of the current state.
 Examples:
 
 ```k
-> {} |succ
+> {} |ok
 ```
 
 ```k
@@ -107,6 +107,8 @@ The interpreter keeps:
 
 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
 
@@ -184,8 +186,11 @@ against that code before becoming the current value.
 
 ### `:klib file`
 
-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.
+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.
 
 ### `:ko file expr`
 
@@ -197,7 +202,7 @@ writes the resulting executable `.ko` object.
 Evaluated values print in k syntax together with the inferred envelope:
 
 ```text
-{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+{}|0|+1 ?<<{} 0, ...> +1, ...>
 ```
 
 `undefined` prints as:
@@ -212,16 +217,16 @@ Evaluated values print in k syntax together with the inferred envelope:
 ## Example Session
 
 ```text
-> :type nat = <{} zero, nat succ>
+> :type nat = <{} 0, nat +1>
 $ nat = @...
-> :rel succ = |succ
-succ = @...
-> {} |zero
-{zero: {}} ?<{} zero, X succ>=X
-> :t succ
-succ : ?X  -->  ?<{} zero, X succ>=X  (@...)
+> :rel inc = |+1
+inc = @...
+> {} |0
+{}|0 ?<{} 0, ...>
+> :t inc
+inc : ?X0  -->  ?<X0 +1, ...>  (@...)
 > :klib nat.klib
 saved nat.klib
-> :ko succ.ko succ
-saved succ.ko (succ)
+> :ko inc.ko inc
+saved inc.ko (inc)
 ```

package/DOCS/TYPE_DERIVATION.md

@@ -4,7 +4,7 @@
 
 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.
+**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.
@@ -22,12 +22,12 @@ 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. 
+**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
+## 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
@@ -42,13 +42,13 @@ A type pattern is a singleton pattern, i.e., only one type is captured by such a
 
 ## 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
+`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:**
 
 - **Open + Open:** Merge field sets, stay open
-- **Open + Closed:** Check fields ⊆, become closed
-- **Closed + Closed:** Check fields =, stay closed
+- **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)
 
@@ -75,7 +75,7 @@ out(eᵢ) = in(eᵢ₊₁)  for i = 1..n-1
 out((e₁ e₂ ... eₙ)) = out(eₙ)
 ```
 
-In case when `n=0`, identity, `()`
+When `n=0`, the composition is the identity, `()`.
 
 ```text
 in(()) = out(())
@@ -136,7 +136,7 @@ in(T) = out(T) = pattern(T)
 see patterns.filterToPattern(F)
 ```
 
-Filter expression is a syntax for describing pattern graphs.
+A filter expression is syntax for describing pattern graphs.
 
 ## 6. Global Algorithm
 
@@ -166,13 +166,13 @@ For each SCC (in topological order):
     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.
+**Purpose:** Replace all pattern nodes with their reps and replace all singleton patterns with types.
 
 **Algorithm:**
 
@@ -186,7 +186,7 @@ For each SCC (in topological order):
 
 **Criterion:** Pattern graph structure unchanged between iterations
 
-**Measured by:** 
+**Measured by:**
 1. Representative forest structure (parent pointers)
 2. Edge sets for each representative
 3. Pattern descriptors for each representative
@@ -206,7 +206,7 @@ Converged = (current_state == previous_state)
 
 ## 9. Error Handling
 
-**Unification errors:**
+**Unification errors include:**
 
 - Product vs Union
 - Closed pattern field mismatch

package/DOCS/book/01-introduction.md

@@ -44,8 +44,8 @@ computation in a concise and understandable way.
 
 There is another concept in the language, called **filters**.
 Filters play a role in the process of reasoning about types of partial functions.
-Filters have been added to the syntax of the language as they allow explicit annotations
-of "polymorphic" expressions, i.e., expressions which make sense in different contexts.
+Filters have been added to the syntax of the language because they allow explicit annotations
+of "polymorphic" expressions, i.e., expressions that make sense in different contexts.
 Filters are similar to *type classes* in other languages.
 
 ---

package/DOCS/book/02-syntax-and-values.md

@@ -10,7 +10,7 @@ $ type_name = ...type_expression... ;
 function_name = ...expression... ;
 ```
 
-The definitions are followed in the file by the *main expression*; it represents the partial function defined by the program as a whole.
+The definitions are followed in the file by the *main expression*, which represents the partial function defined by the program as a whole.
 
 There is no syntax for values.
 Every syntactic form in an expression describes a **function** -- possibly a constant function that always returns the same value.
@@ -48,22 +48,22 @@ Every type denotes a finite tree automaton whose accepted trees are the possible
 
 ## **2.4 Projections**
 
-**Dot** notation, e.g., 
+**Dot** notation, e.g.,
 
 ```k
  . field_name
 ```
 
 is used for extracting the value of a field from a record (product type value).
-**Div** notation, e.g., 
+**Div** notation, e.g.,
 
 ```k
  / variant_name
 ```
 
 is used for asserting a particular variant of a union and extracting its value.
-Product type `{ T₁ l₁, T₂ l₂, … , Tₙ lₙ }` naturally defines `n` partial functions: `.l₁, .l₂, … , .lₙ`,  
-and union type `< T₁ l₁, T₂ l₂, … , Tₙ lₙ >` naturally defines `n` partial functions `/l₁, /l₂, … , /lₙ`.
+A product type `{ T₁ l₁, T₂ l₂, … , Tₙ lₙ }` naturally defines `n` partial functions: `.l₁, .l₂, … , .lₙ`,
+and a union type `< T₁ l₁, T₂ l₂, … , Tₙ lₙ >` naturally defines `n` partial functions `/l₁, /l₂, … , /lₙ`.
 Those partial functions are called **projections** and they constitute the basis for the definition
 of all other partial functions in the `k` language.
 
@@ -81,10 +81,10 @@ Expressions combine partial functions using the following operators:
 Parentheses around a composition may be omitted except for the empty composition `()` — the identity function.
 Empty product, `{ }`, defines a constant function (ignoring its input) returning *unit*.
 
-It is important to notice that after the three markers: `dot (.)`, `div (/)`, or `pipe (|)`, there must be a constant label literal. For that reason, it is possible and advised not to leave any blanks after the marker, e.g.:
+It is important to notice that after the three markers `dot (.)`, `div (/)`, or `pipe (|)`, there must be a constant label literal. For that reason, it is possible and recommended not to leave any blanks after the marker, e.g.:
 
 ```k-lang
-  .field /'a-tag' |"strange and long tag name ✅" 
+  .field /'a-tag' |"strange and long tag name ✅"
 ```
 
 ---
@@ -105,7 +105,7 @@ This defines a "two-variant" union type and three functions: two constants and o
 ## **2.7 Summary**
 
 * All types describe tree shapes.
-* As type expression, `{}` is the empty product type (with one value, called *unit*).
+* As a type expression, `{}` is the empty product type (with one value, called *unit*).
 * Functions, not values, are the only expressions in `k`.
 
 ---

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

@@ -2,7 +2,7 @@
 
 ## **3.1 Motivation**
 
-A type in `k` describes a set of finite labeled trees, which can be recognized by a finite tree automaton (FTA). Equivalently, a type definition can be seen as a Context-Free Grammar (CFG), where the values of the type are the derivation trees of the grammar.
+A type in `k` describes a set of finite labeled trees, which can be recognized by a finite tree automaton (FTA). Equivalently, a type definition can be seen as a context-free grammar (CFG), where the values of the type are the derivation trees of the grammar.
 
 For example, the recursive type definition of a `list`:
 
@@ -31,7 +31,7 @@ A value of type `list` is a derivation tree of this grammar. For instance, a lis
                      -- (rule 1) --> {} |true
 ```
 
-This derivation tree corresponds to the value generated by constant function: `{ {} |true head, {} |nil tail } |cons`.
+This derivation tree corresponds to the value generated by the constant function `{ {} |true head, {} |nil tail } |cons`.
 
 Representing types as automata (or CFGs) provides each type with a well-defined structure, independent of the names used in the source code. This allows for canonical normal forms and for comparing types for equality by structure alone.
 

package/DOCS/book/04-partial-functions-and-composition.md

@@ -91,7 +91,7 @@ Here, `true_bool` and `false_bool` are constant functions. They are also **total
 
 ---
 
-## **4.6  Projection and Variant Value constructor**
+## **4.6  Projection and variant value constructors**
 
 Projection selects a field or a variant from a product or union.
 It is written with a leading dot `.` or a leading slash `/`, respectively:
@@ -141,6 +141,6 @@ The empty product `{}` is the constant function returning the unit value.
 * **Product composition** `{...}` runs functions in parallel and gathers their results.
 * **Union composition** `<...>` tries functions in order, returning the first successful result.
 * **Projections** (`.x`, `/x`) are fundamental building blocks for accessing data structures.
-* **Variant constructor** (`|tag`) allows lifting a value into a variant type value.
+* **Variant constructors** (`|tag`) allow lifting a value into a variant type value.
 
 ---

package/DOCS/book/05-typing-filters-and-normalization.md

@@ -87,13 +87,13 @@ Here:
 
 ## **5.6 Type inference and normalization**
 
-Every `k` program can be analyzed to assign an input and an output filter to every sub-expression. This process is called type inference abd normalization.
+Every `k` program can be analyzed to assign an input and an output filter to every sub-expression. This process is called type inference and normalization.
 
-Type inference and normalization proceeds as follows:
+Type inference and normalization proceed as follows:
 
 1. Build a graph of all type references appearing explicitly and implicitly in the program.
 2. Annotate each expression node with a pair of (input filter, output filter).
-3. Replace filters that match a single, concrete type with that type expression, adding any newly-discovered types to the graph.
+3. Replace filters that match a single, concrete type with that type expression, adding any newly discovered types to the graph.
 4. Repeat until a fixed point is reached and no more changes occur.
 5. Compute canonical forms for all newly introduced types.
 

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

@@ -138,7 +138,7 @@ The value `{}|_|0|1` or in JSON-like notation `{1:{0:{_:{}}}}` (binary 10₂ = d
 01 00 10
 ```
 
-This represents the left-most derivation of  `{}|_|0|1` from `C0`.
+This represents the leftmost derivation of `{}|_|0|1` from `C0`.
 
 #### **Prefix-free property**
 
@@ -304,7 +304,7 @@ Without DAG: Each "Engineering" string encoded separately
 - 1000 records × 30 bytes/record = 30KB
 
 With DAG: "Engineering" string shared via back-references  
-- 1 × "Engineering" (11 bytes) + 800 × back-reference (3 bytes) = 2.4KB
+- 1 × "Engineering" (11 bytes) + 800 × back-reference (3 bytes) = 2.4 KB
 - Compression ratio: ~12.5×
 ```
 
@@ -1061,7 +1061,7 @@ The final encoding strategy balances theoretical optimality with practical hardw
 - **Decode performance**: 5-10× faster than bit-level encoding  
 - **Cache behavior**: Excellent (word-aligned, sequential access)
 - **SIMD compatibility**: Yes (bulk discriminator processing)
-- **Architecture agnostic**: Optimized for x86-64 and ARM64
+- **Architecture-agnostic**: Optimized for x86-64 and ARM64
 
 **Performance characteristics**:
 

package/DOCS/book/07-the-partial-function-abi.md

@@ -3,7 +3,7 @@
 ## **7.1  Purpose**
 
 The **application binary interface (ABI)** defines how partial functions in `k` are represented and invoked at runtime.
-Its goal is to make all functions - whether user-defined or compiled - compatible with the same calling convention and data layout.
+Its goal is to make all functions, whether user-defined or compiled, compatible with the same calling convention and data layout.
 
 Every compiled `k` function receives a single argument (a runtime value) and may either produce a result or remain undefined.
 The ABI provides a uniform way to express both outcomes.

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

@@ -133,7 +133,7 @@ otherwise it is an identity
 ⟨ ?F , v ⟩ ⇓ v
 ```
 
-Filters therefore act as compile time annotations for type checking only.
+Filters therefore act as compile-time annotations for type checking only.
 As operations they are identities at run time, unless they lead to fully typed
 expressions (i.e., can be replaced by a type). Their pattern information may
 still be present on the runtime value because values can carry codec patterns.

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

@@ -44,7 +44,7 @@ Each stage transforms one representation of the program into another, simpler on
 
 A minimal compiler can be viewed as three connected modules:
 
-* **Front end** — reads source code, builds the AST, performs type analysis.
+* **Front end** — reads source code, builds the AST, and performs type analysis.
 * **Middle** — resolves all references, normalizes types, and simplifies expressions.
 * **Back end** — produces the executable form.
 
@@ -107,7 +107,7 @@ For `k`, the IR mirrors the structure of partial functions:
 
 | Concept in k          | IR operation                     |
 | --------------------- | -------------------------------- |
-| Projection `.x` '/x'  | `PROJECT label_id`               |
+| Projection `.x` `/x`  | `PROJECT label_id`               |
 | Composition `(f g)`   | `CALL f; CALL g`                 |
 | Union `<f,g>`         | `TRY f; IF undefined THEN TRY g` |
 | Product `{.x f, .y g}` | `PRODUCT_CALL (f, g); COMBINE`   |

package/DOCS/book/appendix-b-incorporating-external-predefined-types-and-functions.md

@@ -1,4 +1,5 @@
 # Appendix B — Incorporating External Predefined Types and Functions
+
 ## **B.1  Purpose**
 
 The k language is intentionally minimal.

package/README.md

@@ -40,13 +40,12 @@ numbers are either `0` or one more than another natural number:
 
 ```k
 $ nat = < {} 0, nat +1 >;
-
-zero = {} |0;
-inc = |+1;
-
-add = ?X <
-  { .x /+1 x, .y inc y } ?X add,
-  .y
+0 = {} | 0 $ nat ;
+inc = | +1 $ nat ;
+dec = $ nat / +1 ;       # undefined for '0'
+add = $ { nat x, nat y } <
+  { . x dec x, . y inc y } add,    # defined if 'x > 0'
+  . y                              # else, return 'y'
 >;
 ```
 
@@ -56,8 +55,8 @@ from `x` to `y` and recurses. When that no longer applies, it returns `y`.
 In the REPL:
 
 ```text
-> { {} |0 inc inc x, {} |0 inc y } add
-{}|0|+1|+1|+1 ?<X0 +1, {} 0, ...>=X0
+> { 0 inc inc x, 0 inc y } add
+{}|0|+1|+1|+1 ?<X0 +1, {} 0>=X0
 ```
 
 That evaluates `2 + 1` to `3`: a value starts at `0`, and each `+1` tag adds
@@ -240,7 +239,7 @@ Still evolving:
 - optimization and backend experiments
 - larger real-world examples
 
-## Good Areas For Contributors
+## Good Areas for Contributors
 
 k is small enough to study, but there are several useful directions:
 
@@ -278,13 +277,14 @@ compose with `.result` when only the floating-point value is needed.
 
 ```bash
 npm run prepare   # regenerate parsers from .jison grammars
-npm test          # run the full suite
+npm test          # run the fail-fast full suite with per-test timings
 ```
 
-The test suite covers:
+The test runner prints each test before execution and reports its elapsed time
+afterward. It stops immediately when a test fails. The suite covers:
 
 - core runtime and parser behavior
-- type derivation cases in `Code-derivation-tests/`
+- type derivation cases in `tests/code-derivation/`
 - hash/fingerprint stability
 - object file round-trips
 - REPL scripted interaction

package/codecs/BINARY_FORMAT.md

@@ -9,7 +9,7 @@ in [`POLYMORPHIC_BINARY_FORMAT.md`](./POLYMORPHIC_BINARY_FORMAT.md):
 encode($pattern_value : $pattern) encode(value : decoded_pattern)
 ```
 
-## Purpose Of This File
+## Purpose of This File
 
 This file records constraints for any future optimized container layered above
 the canonical stream.

package/codecs/POLYMORPHIC_BINARY_FORMAT.md

@@ -288,7 +288,7 @@ Decoding the stream yields `Value(pattern, tree)`. Encoding a runtime `Value`
 uses its carried pattern by default, or an explicit caller-supplied pattern when
 one is provided.
 
-## Out Of Scope For The Base Codec
+## Out of Scope for the Base Codec
 
 The following are intentionally outside the primitive codec:
 

package/codes.mjs

@@ -248,43 +248,24 @@ function finalizeIncremental(newCodes) {
     }
   }
 
-  const representatives = minimize(resolvedCodes).representatives;
-  for (const name in refResolution) {
-    if (refResolution[name] !== name) {
-      const target = refResolution[name];
-      representatives[name] = representatives[target] || target;
-    }
-  }
+  const reachableCodes = {};
+  const queue = Object.keys(resolvedCodes);
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (reachableCodes[name]) continue;
 
-  const normalizedCodes = normalizeAll(resolvedCodes, representatives);
-  const allReadableCodes = { ...theRepository.codes, ...normalizedCodes };
-  const globalNames = {};
+    const code = resolvedCodes[name] || theRepository.codes[name];
+    if (code == null) {
+      throw new Error(`Type references undefined type: ${name}`);
+    }
+    reachableCodes[name] = code;
 
-  for (const name in normalizedCodes) {
-    const globalDef = encodeCodeToString(name, allReadableCodes);
-    normalizedCodes[name].def = globalDef;
-    globalNames[name] = hash(globalDef);
+    for (const dest of Object.values(code[code.code] || {})) {
+      if (!reachableCodes[dest]) queue.push(dest);
+    }
   }
 
-  const globalCodes = Object.keys(normalizedCodes).reduce((result, name) => {
-    result[globalNames[name]] = normalizedCodes[name];
-    return result;
-  }, {});
-
-  const extendedRepresentatives = Object.keys(representatives).reduce((result, name) => {
-    result[name] = globalNames[representatives[name]] || representatives[name] || name;
-    return result;
-  }, {});
-
-  Object.values(globalNames).forEach((name) => {
-    extendedRepresentatives[name] = name;
-  });
-
-  const normalizedGlobalCodes = normalizeAll(globalCodes, extendedRepresentatives);
-  return {
-    codes: normalizedGlobalCodes,
-    representatives: extendedRepresentatives
-  };
+  return finalize(reachableCodes);
 }
 
 function register(newCodes) {