@fraczak/k 5.1.2 → 6.0.1

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

@@ -0,0 +1,111 @@
+# Chapter 2 — Syntax and Values
+
+## **2.1 Language fragments**
+
+The `k` language has only one kind of program element: a **definition**.
+A program is a sequence of definitions of two kinds:
+
+```k-lang
+$ 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.
+
+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.
+
+---
+
+## **2.2 Types**
+
+A type describes the possible **tree shapes** of values.
+Types are formed from two constructors:
+
+1. **Product**  – written `{ T₁ l₁, T₂ l₂, … }`
+   represents records with fixed labeled fields.
+
+2. **Union**  – written `< T₁ l₁, T₂ l₂, … >`
+   represents a choice between labeled alternatives.
+
+Both are finite and fully explicit.
+Every type denotes a finite tree automaton whose accepted trees are the possible values of that type.
+
+---
+
+## **2.3 Special and limiting cases**
+
+1. **Empty product**
+   `{}` has no fields.
+   It represents the type that admits exactly one value, called *unit*.
+   There is nothing exceptional about the type and its value; it is simply the degenerate case of a product with zero fields.
+
+2. **Empty union**
+   `<>` has no variants.
+   It represents a type with no possible values.
+
+---
+
+## **2.4 Projections**
+
+**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., 
+
+```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ₙ`.
+Those partial functions are called **projections** and they constitute the basis for the definition
+of all other partial functions in the `k` language.
+
+---
+
+## **2.5 Functions**
+
+Expressions combine partial functions using the following operators:
+
+1. **Composition** `(f₁ f₂ …)` — sequential application.
+2. **Union** `< f₁, f₂, … >` — try each in order, first defined wins.
+3. **Product (parallel)** `{ f₁ l₁, f₂ l₂, … }` — apply all to the same input, succeed only if all succeed.
+4. **Variant construction** `| tag` — lift the input as a variant `tag` of a union type.
+
+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.:
+
+```k-lang
+  .field /'a-tag' |"strange and long tag name ✅" 
+```
+
+---
+
+## **2.6 Example**
+
+```k-lang
+$ bool = < {} true, {} false >;
+true  = {} |true $ bool;
+false = {} |false $ bool;
+neg = $ bool < /true false, /false true >;
+```
+
+This defines a "two-variant" union type and three functions: two constants and one transformation exchanging the variants.
+
+---
+
+## **2.7 Summary**
+
+* All types describe tree shapes.
+* As 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

@@ -0,0 +1,156 @@
+# Chapter 3 — Types as Finite Automata
+
+## **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.
+
+For example, the recursive type definition of a `list`:
+
+```k-lang
+$ bool = < {} true, {} false >;
+$ list = < {} nil, { bool head, list tail } cons >;
+```
+
+corresponds to the following 4-rule grammar:
+
+```bnf
+1: <bool> ::= {} |true
+2: <bool> ::= {} |false
+3: <list> ::= {} |nil
+4: <list> ::= { <bool> head, <list> tail } |cons
+```
+
+A value of type `list` is a derivation tree of this grammar. For instance, a list containing a single boolean value `true` can be represented by the following derivation:
+
+```
+<list>
+  -- (rule 4) --> { <bool> head, <list> tail } |cons
+                     |            |
+                     |            -- (rule 3) --> {} |nil
+                     |
+                     -- (rule 1) --> {} |true
+```
+
+This derivation tree corresponds to the value generated by 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.
+
+---
+
+## **3.2 States and Transitions**
+
+Each type definition introduces one or more *states* in the automaton. A union or a product definition corresponds to a state, and the variants or fields correspond to transitions to other states.
+
+For example, consider the `$bool` type:
+
+```k-lang
+$ bool = < {} true, {} false >;
+```
+
+This definition translates to an automaton with two states:
+
+- A root state, let's call it `C0`, representing the `$bool` type itself (a union).
+- A state `C1` representing the empty product `{}`.
+
+From the root state `C0`, there are two transitions:
+
+- A transition labeled `true` to state `C1`.
+- A transition labeled `false` to state `C1`.
+
+`C0` is the root state of the type, and `C1` is a leaf state, representing an empty value.
+
+---
+
+## **3.3 Canonical Form**
+
+Different type expressions can describe the same automaton. For example:
+
+```k-lang
+$ bool = < {} false, {} true >;
+$ pair = { bool x, bool y };
+$ pair2 = { < {} true, {} false > x, bool y };
+```
+
+The types `pair` and `pair2` are structurally equivalent because `$bool` is defined as `< {} true, {} false >`, making the definition of `x` in `pair2` identical to the standalone `$bool` type used in `pair`. Canonicalization is the process of removing these superficial differences by erasing local names and renumbering states to produce a single stable representation for each unique type structure.
+
+The canonical form is generated by traversing the type's graph structure starting from its root state. The process ensures a unique representation by following a consistent ordering:
+
+1. **Start at the Root**: Assign the number `C0` to the root state of the type.
+2. **Explore Neighbors**: Visit all states reachable from `C0`. Sort the transitions alphabetically by their labels (field or variant names) and assign consecutive numbers (`C1`, `C2`, ...) to the destination states in that order.
+3. **Iterate**: Move to the next state in the numbered sequence (`C1`, then `C2`, etc.) and repeat the process for any of its neighbors that have not yet been numbered.
+4. **Complete**: Continue until all reachable states have been assigned a unique number.
+
+This traversal produces a unique and deterministic numbering for any finite directed graph, ensuring that any two structurally identical types will have the exact same canonical representation.
+
+---
+
+## **3.4 Examples**
+
+For a type representing binary natural numbers:
+
+```k-lang
+$ bnat = < bnat 0, bnat 1, {} _ >;
+```
+
+the canonical form is:
+
+```k-lang
+$C0 = < C0 "0", C0 "1", C1 "_" >;
+$C1 = {};
+```
+
+The automaton has two states. `C0` is a recursive state that recognizes sequences of "0"s and "1"s, while `C1` is the terminal state, marked by the "_" transition.
+
+---
+
+## **3.5 Normalization Process**
+
+When compiling a program, the following steps are taken to normalize types:
+
+1. **Collect**: Gather all type definitions from the program.
+2. **Expand**: Recursively replace all named types with their underlying definitions until only products and unions remain.
+3. **Deduplicate**: Eliminate duplicate type structures by comparing them structurally.
+4. **Canonicalize**: Assign stable state numbers to the unique types to produce their canonical text representation.
+
+This process is deterministic, ensuring that the same type structure always produces the exact same canonical form.
+
+---
+
+## **3.6 Hash-Based Naming**
+
+To create a globally unique and stable identifier for each type, the compiler computes a hash of its canonical representation. This hash becomes the official, unambiguous name of the type.
+
+For example:
+
+```text
+Canonical Form: $C0=<C0"0",C0"1",C1"_">;$C1={}
+      ↓
+     Hash
+      ↓
+Identifier: @VtPHxGf5GNMzzyVFxtv7gegFfJRYapBGtCeyV56bs5Zb
+```
+
+Program objects can then refer to types by their hash-based identifiers (prefixed with `@`) without ambiguity.
+
+---
+
+## **3.7 Interpretation**
+
+The canonical representation of a type can be interpreted as:
+
+- A finite set of states, `C0…Cn`.
+- Each state is either a product (a record with named fields) or a union (a set of variants).
+- Transitions between states are labeled with strings (field or variant names).
+
+Every value of a given type is a finite tree that is accepted by this automaton.
+
+---
+
+## **3.8 Summary**
+
+- Types in `k` denote sets of finite, labeled trees.
+- Every type can be expressed as a finite tree automaton or a context-free grammar.
+- The canonical form eliminates naming differences, providing a single representation for structurally identical types.
+- Hash-based naming gives each unique type a stable and globally unique identifier.
+
+---

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

@@ -0,0 +1,146 @@
+# Chapter 4 — Partial Functions and Composition
+
+## **4.1  Partial functions**
+
+A **partial function** is a mapping that may be undefined for some inputs.
+In `k`, every expression denotes such a function.
+If a function is undefined for a given input, the evaluation process halts at that point, producing no result.
+
+There is no notion of error or exception.
+Undefined means simply “no output”.
+
+---
+
+## **4.2  Composition**
+
+Composition combines two or more partial functions sequentially.
+If `f` and `g` are functions, `(f g)` means “apply `f`, then apply `g` to the result”.
+
+A composition `(f g)` is defined on a value `x` if and only if:
+
+* `f` is defined on `x`, and
+* `g` is defined on the result of `f(x)`.
+
+Otherwise, the composition is undefined.
+
+Composition is **associative**:
+
+```math
+(f (g h))  ≡  ((f g) h)
+```
+
+Therefore, parentheses are unnecessary, except for the special case of the **empty composition**, written `()`, which is the identity function:
+
+```math
+() x  =  x () = x
+```
+
+---
+
+## **4.3  Product composition**
+
+Product composition creates a function that applies several subfunctions in parallel to the same input and gathers their results into a product value.
+
+Syntax:
+
+```math
+{ f₁ l₁, f₂ l₂, …, fₙ lₙ }
+```
+
+This expression is defined on an input value if all component functions are defined on that input.
+Its result is a product with fields labeled `l₁ … lₙ`, each containing the result of the corresponding function.
+
+---
+
+## **4.4  Union composition**
+
+Union composition represents concurrent evaluation with fallback:
+
+```k-lang
+< f₁, f₂, …, fₙ >
+```
+
+The result is defined for an input `x` if at least one subfunction is defined.
+Evaluation proceeds left to right; the first defined result is used.
+If none are defined, the result is undefined.
+
+Example:
+
+```k-lang
+< /x, /y >
+```
+
+extracts variant `x` if present; otherwise `y` if present.
+
+---
+
+## **4.5  Constants**
+
+A constant function is one that always returns the same value, regardless of its input.
+Since `k` lacks a direct syntax for literal values, constants are created using functions that produce them.
+
+For example, we can define functions that return `true` and `false`:
+
+```k-lang
+$ bool = < {} true, {} false >;
+true_bool  =  {} |true $bool ;
+false_bool =  {} |false $bool ;
+```
+
+Here, `true_bool` and `false_bool` are constant functions. They are also **total functions**, meaning they are defined for all inputs. Each function ignores its input and produces a fixed boolean value.
+
+---
+
+## **4.6  Projection and Variant Value constructor**
+
+Projection selects a field or a variant from a product or union.
+It is written with a leading dot `.` or a leading slash `/`, respectively:
+
+```k-lang
+.x     // Selects field 'x' from a product: { T x, ... }
+/x     // Extracts the value from a union variant 'x': < T x, ... >
+```
+
+If the input is a product, `.x` returns the value of field `x`. If the input is a union, `/x` returns the value of variant `x`. In all other cases, the projection is undefined.
+
+Variant value constructors for a given union type `T = <T₁ tag₁, T₂ tag₂, … >` are written as `|tag₁`, `|tag₂`, ….
+
+```k-lang
+|tag₁    // lift a value of type T₁ into a value of type T
+```
+
+Projections and variant constructors are the most basic partial functions.
+
+---
+
+## **4.7  Derived combinations**
+
+Complex functions are built by nesting compositions.
+For example:
+
+```k-lang
+{ .x field1, .y |tag field2 }
+```
+
+---
+
+## **4.8  Identity and emptiness**
+
+The empty composition `()` is the identity function.
+The empty union `<>` is the always-undefined function.
+The empty product `{}` is the constant function returning the unit value.
+
+---
+
+## **4.9  Summary**
+
+* In `k`, all expressions denote **partial functions**.
+* An undefined result simply means “no output,” not an error.
+* **Composition** `(f g)` applies functions sequentially and is associative, so parentheses are often optional.
+* The empty composition `()` is the **identity function**.
+* **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.
+
+---

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

@@ -0,0 +1,111 @@
+# Chapter 5 — Typing, Filters, and Normalization
+
+## **5.1 Types as functions**
+
+A type expression in `k` can appear wherever a function is expected.
+When used this way, it is prefixed by `$`.
+It then behaves as a partial **identity** function that is defined only for values of that type.
+For example, `$ bool` is a partial identity: it returns its argument unchanged when the argument is of type `bool`, and it is undefined otherwise.
+
+This convention eliminates any special syntax for annotating sub-expressions with types.
+An expression may be *restricted* to a type simply by composing it with the corresponding type expression.
+
+---
+
+## **5.2 Filters**
+
+A **filter** is a syntactic form that denotes a *class of types* — a set of types that share a common structure.
+
+Filter expressions are introduced by `?` and can be:
+
+- **Type expressions** — `? $bool`, `? $< {} x, bool y >`
+- **Product filters** — `? { Filter1 field1, Filter2 field2 }`  
+- **Union filters** — `? < Filter1 tag1, Filter2 tag2 >`
+- **Any-type filter** — `? ( ... )`
+- **Filter variables** — `? X` (metavariables representing unknown types)
+- **Filter bindings** — `? < X f, (...) = Y g, ... > = X`
+
+Filters may contain `...` to indicate that additional fields or tags are allowed:
+`? { Filter1 field1, ... }` matches any product with at least `field1`.
+
+The filter `? (...)` matches any type.
+The filter `? {...}` matches any product type.
+The filter `? <...>` matches any union type.
+There is no closed unknown filter: use `?{}` for the empty product or `?<>` for the empty union.
+
+---
+
+## **5.3 Examples of filters**
+
+- `?(...)` — represents any type.
+- `?< (...) f, (...) g >` — represents all union types having exactly two variants `f` and `g`.
+- `?{ X f, X g }` — represents all product types with two fields `f` and `g`, both of the same type.
+
+A filter constrains where a partial function is defined; it does not affect the operational behavior of the function once defined.
+
+---
+
+## **5.4 Recursive filters**
+
+Filters may be recursive.
+They can describe families of recursive types by defining a metavariable in terms of a filter that references it.
+
+Example (list definition):
+
+```k-lang
+?< {} nil, {X car, Y cdr} cons > = Y
+```
+
+This filter states that `Y` is a union type with two variants: `nil` and `cons`.
+
+- The `nil` variant holds an empty product `{}`.
+- The `cons` variant is a product with two fields: `car` of some type `X`, and `cdr` of type `Y` itself.
+
+This recursive structure defines a linked list where each element has a `car` (the value) and a `cdr` (the rest of the list).
+It thus denotes lists of elements of type `X`.
+
+---
+
+## **5.5 Type variables and scope**
+
+A type variable (an identifier, typically starting with an uppercase letter) introduced in a filter is visible within the enclosing function definition.
+For example:
+
+```k-lang
+car = ?< {} nil, {X car, Y cdr} cons > = Y /cons .car ?X;
+```
+
+Here:
+
+- `X` and `Y` are type variables.
+- The filter `?<{}nil,{X car,Y cdr}cons>=Y` constrains the function `car` to be defined only on types that match the recursive list structure.
+- The expression `/cons` selects the `cons` variant of the union.
+- The expression `.car` accesses the `car` field of a `cons` variant.
+- The final filter `?X` asserts that the result of the field access is of type `X`, the type of the list's elements.
+
+---
+
+## **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.
+
+Type inference and normalization proceeds 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.
+4. Repeat until a fixed point is reached and no more changes occur.
+5. Compute canonical forms for all newly introduced types.
+
+---
+
+## **5.7 Summary**
+
+- Type expressions act as identity functions defined on values of that type.
+- Filters describe sets of types and can constrain where a function is defined.
+- Filters may be products, unions, or the unconstrained any-type form, and can be recursive.
+- Variables in filters have definition-level scope.
+- Normalization computes explicit input/output filters for every expression.
+- Filters are used in the normalization and type checking process. They are ignored at runtime.
+
+---