@fraczak/k 5.1.2 → 6.0.1

package/DOCS/REPL.md

@@ -0,0 +1,191 @@
+# k Interpreter
+
+## Overview
+
+`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.
+
+`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.
+
+## State Model
+
+```
+┌─────────────────────────────────────────────────┐
+│  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
+└─────────────────────────────────────────────────┘
+```
+
+- `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 `{}`.
+
+## Commands
+
+Each line is a command. Multiline commands can be continued with a trailing
+`\`.
+
+Tab completion is available for command names, file paths in file-taking
+commands such as `:load` and `:export`, and canonical names that start with
+`@`.
+
+| Command | Description |
+|---------|-------------|
+| `:type name = <...>` | Define a type |
+| `:rel name = expr` | Define a relation |
+| `: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 |
+| `: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.
+
+## Shorthand Input
+
+Raw k input is still accepted:
+
+- `$ 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`.
+
+## Input Handling
+
+### Type Definition: `:type name = <...>`
+
+- Parse and register the code via `codes.register`.
+- Store canonical hash in `aliases[name]`.
+- Print: `$ name = @hash`
+
+### Relation Definition: `:rel name = expr`
+
+- 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`
+
+### Expression Evaluation: `:run expr`
+
+- 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).
+
+## Alias Preamble
+
+Before compiling any user input, the REPL prepends alias definitions so that
+human names resolve to library relations:
+
+```k
+add = @mKEA...; succ = @Swjz...; nat = @w8iS...;
+<user input>
+```
+
+For type aliases, the preamble uses `$ name = @hash;` syntax (referencing
+an existing canonical code by hash).
+
+This reuses the existing parser and compiler without modification.
+
+## Output Format
+
+Values are printed as:
+
+```
+<value-in-k-syntax> ?<pattern-as-filter>
+```
+
+Examples:
+
+```
+> {}|zero|succ|succ
+{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+
+> {{}|1 car, {}|nil cdr}|cons
+{{{}|1 car, {}|nil cdr}|cons} ?<{} nil, {<{} 0, {} 1> car, X cdr} cons>=X
+```
+
+Uses `valueToK` and `propertyListToFilter` from
+`codecs/runtime/show-value.mjs`.
+
+When the result is `undefined`, print:
+
+```
+... undefined
+```
+
+## Loading Files
+
+### `: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).
+
+### `:load file.klib`
+
+- Decode the .klib file.
+- Merge codes and rels into state.
+- Update aliases from `meta` (recover source names from origins).
+
+## Exporting
+
+### `:save file.klib`
+
+- Serialize current `{codes, rels, meta, main: null}` as a .klib.
+- `meta` is built from the alias table (each alias → origin entry).
+
+### `:klib file.klib`
+
+- Alias for saving the current state as a `.klib`.
+
+### `:ko file.ko [expr]`
+
+- 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.
+
+### `:export file [expr]`
+
+- 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.
+
+## Example
+
+```
+> :type nat = <{} zero, nat succ>
+$ nat = @...
+> :rel succ = |succ
+succ = @...
+> :run succ
+{}|succ ?<{} succ, ...>
+> :klib nat.klib
+saved nat.klib
+> :ko succ.ko succ
+saved succ.ko (succ)
+```

package/DOCS/a.html

@@ -0,0 +1,398 @@
+<h1 id="patterns-and-typed-values">Patterns And Typed Values</h1>
+<h2 id="abstract">Abstract</h2>
+<p>This note proposes a semantic foundation for <code>k</code> patterns,
+types, typed values, and polymorphic values. The central point is that a
+value in <code>k</code> is not a bare tree: it exists only in the
+context of a type. Accordingly, a pattern denotes a set of types, and
+therefore also a set of <strong>typed</strong> values, not a set of raw
+trees. This distinction is essential for reasoning about equality,
+polymorphism, and binary serialization with DAG compression.</p>
+<h2 id="introduction">1. Introduction</h2>
+<p>The <code>k</code> language manipulates algebraic values built from
+products and unions. At first sight one may be tempted to define a value
+simply as a rooted labeled tree and then define types as sets of such
+trees. For <code>k</code>, this is not the right semantic level.</p>
+<p>Two trees with the same shape but belonging to different types are
+different values. Type is part of value identity.</p>
+<p>This leads to the following semantic ladder:</p>
+<ul>
+<li>a <strong>type</strong> denotes a set of typed values,</li>
+<li>a <strong>pattern</strong> denotes a set of types,</li>
+<li>therefore a <strong>pattern</strong> also denotes a set of typed
+values,</li>
+<li>a <strong>polymorphic value</strong> is a pattern together with a
+typed value compatible with that pattern.</li>
+</ul>
+<p>The rest of this note makes these notions precise.</p>
+<h2 id="types">2. Types</h2>
+<p>A <strong>type graph</strong> is a finite rooted directed graph with
+labeled edges. Each node is one of:</p>
+<ul>
+<li><code>product</code>,</li>
+<li><code>union</code>.</li>
+</ul>
+<p>For a product node, outgoing edge labels are field names. For a union
+node, outgoing edge labels are tags. Edges are locally unique by
+label.</p>
+<p>The graph may be cyclic, which allows recursive types.</p>
+<p>Two type graphs that are equivalent as regular tree languages may be
+identified. For types, minimization by bisimulation is appropriate.</p>
+<h3 id="trees-accepted-by-a-type">2.1. Trees accepted by a type</h3>
+<p>Let <code>Tree(T)</code> denote the set of rooted value trees
+accepted by a type graph <code>T</code>. Acceptance is defined in the
+standard way:</p>
+<ul>
+<li>a product tree is accepted by a product node when its fields match
+the outgoing labels of that node and each child tree is accepted by the
+corresponding target node,</li>
+<li>a union tree is accepted by a union node when it chooses exactly one
+outgoing tag and the child tree is accepted by the corresponding target
+node.</li>
+</ul>
+<h2 id="typed-values">3. Typed Values</h2>
+<p>A <strong>typed value</strong> is a pair</p>
+<pre class="text"><code>(T, t)</code></pre>
+<p>where:</p>
+<ul>
+<li><code>T</code> is a type graph,</li>
+<li><code>t ∈ Tree(T)</code>.</li>
+</ul>
+<p>Thus a value is intrinsically typed. The tree <code>t</code> is only
+a representation of the value; it is not, by itself, a semantic value of
+the language.</p>
+<p>We write:</p>
+<pre class="text"><code>Val(T) = { (T, t) : t ∈ Tree(T) }.</code></pre>
+<h3 id="identity-of-typed-values">3.1. Identity of typed values</h3>
+<p>Typed values are intensional with respect to the type:</p>
+<pre class="text"><code>(T, t) ≠ (U, t)    whenever T ≠ U.</code></pre>
+<p>Even when the same raw tree <code>t</code> is accepted by both
+<code>T</code> and <code>U</code>, the two typed values are
+different.</p>
+<p>This point is essential for serialization: the identity of a value
+cannot be recovered from the raw tree alone.</p>
+<h2 id="patterns">4. Patterns</h2>
+<p>A <strong>pattern graph</strong> is a finite rooted directed graph
+with labeled edges. Each node carries:</p>
+<ul>
+<li>a node kind:
+<ul>
+<li><code>unknown</code>,</li>
+<li><code>product</code>,</li>
+<li><code>union</code>,</li>
+</ul></li>
+<li>an openness flag:
+<ul>
+<li><code>open</code>,</li>
+<li><code>closed</code>.</li>
+</ul></li>
+</ul>
+<p>For product and union nodes, outgoing edges are labeled by field
+names or tags. Edges are locally unique by label.</p>
+<p>Unlike the case of types, <strong>node identity in a pattern graph is
+semantic</strong>. If two edges point to the same pattern node, this
+means that the corresponding positions must be inhabited by the very
+same type.</p>
+<p>Therefore patterns are not quotiented by bisimulation in general.</p>
+<h2 id="filters-as-syntax">5. Filters As Syntax</h2>
+<p>A filter expression is a textual way of describing a pattern
+graph.</p>
+<p>Variables appearing in filters are not the semantic object itself.
+They are a device for serializing and reusing pattern graph nodes in
+syntax.</p>
+<p>For example, the two filters</p>
+<pre class="k"><code>{ (...) x, (...) y, ... }
+{ X x, X y, ... }</code></pre>
+<p>describe different pattern graphs:</p>
+<ul>
+<li>the first has two distinct target nodes for <code>x</code> and
+<code>y</code>,</li>
+<li>the second has one shared target node reached from both
+<code>x</code> and <code>y</code>.</li>
+</ul>
+<p>These two patterns are semantically different.</p>
+<h2 id="matching-a-type-against-a-pattern">6. Matching A Type Against A
+Pattern</h2>
+<p>Let <code>P</code> be a pattern graph and <code>T</code> a type
+graph. We say that <code>T</code> <strong>matches</strong>
+<code>P</code>, written</p>
+<pre class="text"><code>T ⊨ P,</code></pre>
+<p>if there exists a root-preserving graph morphism</p>
+<pre class="text"><code>h : nodes(P) → nodes(T)</code></pre>
+<p>such that:</p>
+<ol type="1">
+<li><p>if <code>p</code> is <code>unknown</code>, then <code>h(p)</code>
+may be any type node,</p></li>
+<li><p>if <code>p</code> is <code>product</code>, then <code>h(p)</code>
+is a product node,</p></li>
+<li><p>if <code>p</code> is <code>union</code>, then <code>h(p)</code>
+is a union node,</p></li>
+<li><p>if <code>p</code> is <code>closed</code>, then the outgoing
+labels of <code>h(p)</code> are exactly the outgoing labels of
+<code>p</code>,</p></li>
+<li><p>if <code>p</code> is <code>open</code>, then the outgoing labels
+of <code>h(p)</code> contain at least the outgoing labels of
+<code>p</code>,</p></li>
+<li><p>for every pattern edge</p>
+<pre class="text"><code>p --l--&gt; q</code></pre>
+<p>there is a corresponding type edge</p>
+<pre class="text"><code>h(p) --l--&gt; h(q).</code></pre></li>
+</ol>
+<p>Condition 6 is the crucial one: if two edges of <code>P</code> point
+to the same node <code>q</code>, then the corresponding edges of
+<code>T</code> must point to the same type node <code>h(q)</code>. This
+is how the graph structure of the pattern expresses “the same type”.</p>
+<p>We define:</p>
+<pre class="text"><code>Types(P) = { T : T ⊨ P }.</code></pre>
+<h3 id="proposition-0">Proposition 0</h3>
+<p>If <code>T ⊨ P</code>, then:</p>
+<ul>
+<li>the root kind of <code>T</code> is compatible with the root kind of
+<code>P</code>,</li>
+<li>every label explicitly present at the root of <code>P</code> is
+present at the root of <code>T</code>,</li>
+<li>if the root of <code>P</code> is closed, then <code>T</code> has no
+additional root labels.</li>
+</ul>
+<h4 id="proof">Proof</h4>
+<p>All three statements are immediate from the definition of the
+root-preserving morphism <code>h</code> and conditions 1-5 above,
+applied at the root node of <code>P</code>.</p>
+<h2 id="singleton-patterns-and-types">7. Singleton Patterns And
+Types</h2>
+<p>Every type graph <code>T</code> determines a closed pattern
+<code>Pat(T)</code> obtained by forgetting that it is a type and viewing
+it as a closed pattern graph.</p>
+<p>This gives the following proposition.</p>
+<h3 id="proposition-1">Proposition 1</h3>
+<p>For every type <code>T</code>, the pattern <code>Pat(T)</code> is
+singleton:</p>
+<pre class="text"><code>Types(Pat(T)) = { T }</code></pre>
+<p>up to the chosen notion of type equivalence.</p>
+<h4 id="proof-1">Proof</h4>
+<p>The identity map from <code>nodes(Pat(T))</code> to
+<code>nodes(T)</code> witnesses <code>T ⊨ Pat(T)</code>. Conversely,
+suppose <code>U ⊨ Pat(T)</code> via a root-preserving morphism
+<code>h</code>. Because every node of <code>Pat(T)</code> is either
+product or union, every node kind is preserved. Because every node is
+closed, the outgoing labels at each image node are exactly the outgoing
+labels of the corresponding node of <code>T</code>. Because every
+pattern edge must be respected by <code>h</code>, all target-sharing
+constraints are preserved as well. Therefore <code>h</code> is a graph
+isomorphism modulo the chosen equivalence on type graphs, and hence
+<code>U</code> is equivalent to <code>T</code>.</p>
+<h3 id="proposition-2">Proposition 2</h3>
+<p>Conversely, every singleton pattern determines a unique type up to
+type equivalence.</p>
+<h4 id="proof-2">Proof</h4>
+<p>Let <code>P</code> be singleton. By definition, <code>Types(P)</code>
+contains exactly one type up to equivalence. Choose any representative
+<code>T ∈ Types(P)</code>. Then <code>T</code> is the unique type
+determined by <code>P</code>, again up to the chosen equivalence
+relation.</p>
+<p>Thus types can be regarded as a special case of patterns.</p>
+<h2 id="polymorphic-values">8. Polymorphic Values</h2>
+<p>A <strong>polymorphic value</strong> is a pair</p>
+<pre class="text"><code>(P, v)</code></pre>
+<p>where:</p>
+<ul>
+<li><code>P</code> is a pattern graph,</li>
+<li><code>v</code> is a typed value <code>(T, t)</code>,</li>
+<li><code>T ⊨ P</code>.</li>
+</ul>
+<p>Equivalently:</p>
+<pre class="text"><code>PolyVal(P) = { (P, (T, t)) : T ⊨ P and t ∈ Tree(T) }.</code></pre>
+<p>So a pattern does not denote a set of raw trees. It denotes a set of
+typed values:</p>
+<pre class="text"><code>Val(P) = { (T, t) : T ⊨ P and t ∈ Tree(T) }.</code></pre>
+<p>This is a disjoint union over matching types, not an ordinary union
+of raw tree sets.</p>
+<h3 id="proposition-3">Proposition 3</h3>
+<p>For every type <code>T</code>,</p>
+<pre class="text"><code>Val(Pat(T)) = Val(T).</code></pre>
+<h4 id="proof-3">Proof</h4>
+<p>By Proposition 1, <code>Types(Pat(T)) = { T }</code> up to
+equivalence. Substituting this into the definition of
+<code>Val(P)</code> yields exactly the set of typed values whose type is
+<code>T</code>.</p>
+<h2 id="examples">9. Examples</h2>
+<h3 id="distinct-pattern-graphs">9.1. Distinct pattern graphs</h3>
+<p>Consider:</p>
+<pre class="k"><code>P1 = { (...) x, (...) y, ... }
+P2 = { X x, X y, ... }</code></pre>
+<p>Then <code>P1</code> and <code>P2</code> are different patterns.</p>
+<ul>
+<li><code>P1</code> allows the types at <code>x</code> and
+<code>y</code> to differ.</li>
+<li><code>P2</code> requires the types at <code>x</code> and
+<code>y</code> to be the same.</li>
+</ul>
+<p>Hence:</p>
+<pre class="text"><code>Types(P2) ⊊ Types(P1).</code></pre>
+<h4 id="proof-sketch">Proof sketch</h4>
+<p>Every type matching <code>P2</code> also matches <code>P1</code>,
+because identifying the target types of <code>x</code> and
+<code>y</code> is stronger than leaving them unrelated. The inclusion is
+strict because a product type with distinct types at <code>x</code> and
+<code>y</code> matches <code>P1</code> but not <code>P2</code>.</p>
+<h3 id="same-tree-different-typed-values">9.2. Same tree, different
+typed values</h3>
+<p>Let <code>t = {}|x</code>. Suppose <code>t</code> is accepted both
+by</p>
+<pre class="k"><code>T1 = &lt; {} x &gt;
+T2 = &lt; {} x, {} y &gt;</code></pre>
+<p>Then <code>(T1, t)</code> and <code>(T2, t)</code> are different
+typed values.</p>
+<p>The raw tree is the same, but the type is different.</p>
+<h3 id="proposition-4">Proposition 4</h3>
+<p>If <code>T ≠ U</code>, then:</p>
+<pre class="text"><code>Val(T) ∩ Val(U) = ∅.</code></pre>
+<h4 id="proof-4">Proof</h4>
+<p>An element of <code>Val(T)</code> has the form <code>(T, t)</code>.
+An element of <code>Val(U)</code> has the form <code>(U, u)</code>. If
+<code>(T, t) = (U, u)</code>, then necessarily <code>T = U</code>.
+Hence, when <code>T ≠ U</code>, the two sets are disjoint.</p>
+<h2 id="consequences-for-equality-and-compression">10. Consequences For
+Equality And Compression</h2>
+<p>Since values are intrinsically typed, raw tree equality is not
+sufficient for semantic equality.</p>
+<p>This has an immediate consequence for DAG compression. Suppose we
+have the raw tree</p>
+<pre class="k"><code>{{}|x a, {}|x b, {}|x c}</code></pre>
+<p>and consider two patterns:</p>
+<pre class="k"><code>P1 = { (...) a, (...) b, (...) c, ... }
+P2 = { X a, X b, X c, ... }</code></pre>
+<p>If only the raw tree is considered, the three occurrences of
+<code>{}|x</code> appear identical and a naive compressor may merge
+them. But semantically this is not always justified.</p>
+<ul>
+<li>Under <code>P1</code>, the three occurrences need not belong to the
+same type.</li>
+<li>Under <code>P2</code>, they must belong to the same type.</li>
+</ul>
+<p>Therefore canonical value sharing, when used as an optimization, must
+be relative to the typing information supplied by the pattern and the
+witness type. One must not collapse raw subtrees merely because they
+look the same as trees.</p>
+<h3 id="proposition-5">Proposition 5</h3>
+<p>There is, in general, no canonical DAG compression procedure that
+depends only on the raw value tree and is correct for all polymorphic
+values.</p>
+<h4 id="proof-5">Proof</h4>
+<p>Consider the raw tree</p>
+<pre class="text"><code>{{}|x a, {}|x b, {}|x c}.</code></pre>
+<p>As a raw tree, the three subtrees under <code>a</code>,
+<code>b</code>, and <code>c</code> are isomorphic. Hence any tree-only
+compressor cannot distinguish their occurrences by local tree structure
+alone. Now compare the two valid pattern contexts:</p>
+<pre class="text"><code>P1 = { (...) a, (...) b, (...) c, ... }
+P2 = { X a, X b, X c, ... }.</code></pre>
+<p>Under <code>P1</code>, the three occurrences are not forced to have
+the same type. Under <code>P2</code>, they are forced to have the same
+type because all three edges land in the same pattern node. So a
+compressor that always merges these subtrees is unsound for
+<code>P1</code>, while a compressor that never merges them fails to
+capture the canonical sharing justified by <code>P2</code>. Therefore no
+canonical sharing rule can be defined from the raw tree alone; typing
+information from the pattern and witness type is required.</p>
+<h3 id="proposition-6">Proposition 6</h3>
+<p>For a fixed polymorphic value <code>(P, (T, t))</code>, any canonical
+DAG compression of <code>t</code> must be invariant under equality of
+<strong>typed occurrences</strong>, not merely equality of raw
+subtrees.</p>
+<h4 id="proof-sketch-1">Proof sketch</h4>
+<p>By Proposition 4, typed values of different types are distinct even
+when represented by the same raw tree. Within a fixed witness type
+<code>T</code>, the pattern graph still matters because distinct
+positions of <code>P</code> may or may not be identified. Therefore the
+only semantically defensible sharing criterion is one that respects the
+typing/decorated occurrence information carried by <code>(P, T)</code>,
+not the undecorated tree <code>t</code> alone.</p>
+<h2 id="topological-remark">11. Topological Remark</h2>
+<p>There is a topology-like intuition behind patterns, but only for a
+fragment.</p>
+<p>If one looks only at open positive patterns, they behave like
+observable structural properties of types and suggest a topology or,
+more precisely, an Alexandrov-style structure on the class of types
+ordered by refinement.</p>
+<p>However, the full pattern formalism is richer than topology because
+it includes:</p>
+<ul>
+<li>closedness constraints,</li>
+<li>explicit graph sharing, which expresses sameness of type at
+different positions.</li>
+</ul>
+<p>These two features go beyond ordinary open-set semantics.</p>
+<h3 id="proposition-7">Proposition 7</h3>
+<p>The class of patterns is strictly richer than the open positive
+fragment.</p>
+<h4 id="proof-sketch-2">Proof sketch</h4>
+<p>The open positive fragment can describe only monotone structural
+requirements such as “at least these labels” and “these positions have
+these subpatterns”. It cannot express exact closedness, because
+closedness is not monotone under refinement. It also cannot express
+identification of two positions as “the same type” without preserving
+explicit graph sharing. Since full patterns include both closedness and
+shared-node identity, they strictly extend the open positive
+fragment.</p>
+<h2 id="summary">12. Summary</h2>
+<ul>
+<li>A type is a regular rooted graph denoting a set of accepted
+trees.</li>
+<li>A typed value is a pair <code>(T, t)</code> with
+<code>t ∈ Tree(T)</code>.</li>
+<li>A pattern is a rooted graph with node kind, openness, and semantic
+node identity.</li>
+<li>A filter is only syntax for serializing a pattern graph.</li>
+<li>A type matches a pattern via a root-preserving morphism respecting
+node kind, openness, labels, and shared targets.</li>
+<li>A pattern denotes a set of types, and therefore a set of typed
+values, not a set of raw trees.</li>
+<li>A polymorphic value is a pair <code>(P, (T, t))</code> with
+<code>T ⊨ P</code>.</li>
+<li>Types are exactly the singleton-pattern case.</li>
+<li>DAG compression of values is a representation optimization only and
+must respect typing information.</li>
+</ul>
+<h2 id="corollaries-for-binary-serialization">13. Corollaries For Binary
+Serialization</h2>
+<p>The previous propositions impose strong constraints on any correct
+binary format.</p>
+<h3 id="corollary-1">Corollary 1</h3>
+<p>The semantic payload of a serialized polymorphic value must
+determine:</p>
+<ul>
+<li>a pattern graph <code>P</code>,</li>
+<li>a witness typed value <code>(T, t)</code>,</li>
+</ul>
+<p>with <code>T ⊨ P</code>.</p>
+<p>It is not sufficient to serialize only a raw tree.</p>
+<h4 id="justification">Justification</h4>
+<p>By Proposition 4, type is part of value identity. By Proposition 5,
+the raw tree alone is insufficient to determine correct canonical
+sharing behavior.</p>
+<h3 id="corollary-2">Corollary 2</h3>
+<p>A closed monomorphic typed value is the special case where the
+serialized pattern is singleton.</p>
+<h4 id="justification-1">Justification</h4>
+<p>This is Proposition 1 together with Proposition 3.</p>
+<h3 id="corollary-3">Corollary 3</h3>
+<p>Any canonical DAG representation of the witness value must be
+computed from the decorated object <code>(P, T, t)</code>, not from
+<code>t</code> alone.</p>
+<h4 id="justification-2">Justification</h4>
+<p>This is exactly the content of Propositions 5 and 6.</p>
+<h3 id="corollary-4">Corollary 4</h3>
+<p>Pattern serialization must preserve explicit pattern-node
+identity.</p>
+<h4 id="justification-3">Justification</h4>
+<p>Pattern node sharing expresses sameness of type at different
+positions. Replacing a pattern graph by any representation that forgets
+this identity changes its denotation.</p>
+<h3 id="corollary-5">Corollary 5</h3>
+<p>For singleton patterns, one may replace the explicit serialized
+pattern graph by a canonical type reference as a compact optimization,
+provided that the decoding semantics is unchanged.</p>
+<h4 id="justification-4">Justification</h4>
+<p>By Proposition 2, a singleton pattern determines a unique type up to
+equivalence. Therefore the explicit graph may be recoverable from a
+canonical type identifier.</p>

package/DOCS/book/01-introduction.md

@@ -0,0 +1,51 @@
+# Chapter 1 — Introduction
+
+## **1.1  The purpose of this book**
+
+This book describes a small programming language called **k**.
+It is meant to show how data can be represented and transformed in a uniform, precise way.
+
+---
+
+## **1.2 Data as trees**
+
+All information in `k` is treated as a **tree**.
+A tree has:
+
+* a single root,
+* labeled edges (field names or tags),
+* and possibly subtrees.
+
+Both JSON objects and XML documents are trees in this sense.
+Every `k` value is such a finite labeled tree.
+
+---
+
+## **1.3 Functions that may fail**
+
+In ordinary mathematics a function always returns a result.
+In `k`, a function may be **undefined** for some inputs.
+For example, asking for the field `age` in a record that has no `age` is undefined.
+
+We call such mappings **partial functions**.
+
+---
+
+## **1.4 Simplicity over features**
+
+`k` avoids most language constructs: no *variables* and no *control statements*.
+It has only:
+
+1. **types** (which describe tree shapes), and
+2. **partial functions** (which transform one tree into another).
+
+These two ingredients are sufficient and powerful enough to express structured
+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 are similar to *type classes* in other languages.
+
+---