@fraczak/k 5.1.2 → 6.0.1

package/Code-derivation-tests/blowup.mjs

@@ -2,7 +2,7 @@ import { t, in_out } from './index.mjs';
 import fs from 'node:fs';
 import assert from 'assert';
 
-// t(fs.readFileSync("./Examples/blowup.k").toString("utf8"), (annotated) => {
+// t(fs.readFileSync("./Examples/blowup.k", "utf8"), (annotated) => {
 //     // console.log(JSON.stringify(annotated,null,2));
 //     const {input,output} = in_out(annotated);
 //     console.log(input);
@@ -13,8 +13,8 @@ import assert from 'assert';
 // });
 
 t(`
-  B = {{} u} A;
-  A = < .a, .b A, .c {() z} A, B  >;
+  B = {}|u A;
+  A = ?X < /a, /b ?X A, /c |z ?X A, B  >;
   A
 `, (annotated) => {
     // console.log(JSON.stringify(annotated,null,2));

package/Code-derivation-tests/bnat.mjs

@@ -2,10 +2,10 @@ import { t, in_out } from './index.mjs';
 import fs from 'node:fs';
 import assert from 'assert';
 
-t(fs.readFileSync("./Examples/bnat-patterns.k").toString("utf8"), (annotated) => {
+t(fs.readFileSync("./Examples/bnat.k", "utf8"), (annotated) => {
     // console.log(JSON.stringify(annotated,null,2));
     const {input,output} = in_out(annotated);
-    console.log(output);
+    // console.log(output);
     assert.equal(output.type, annotated.representatives["bnat"]);
     assert.equal(input.type, annotated.representatives["pair"]);
     console.log("OK");

package/Code-derivation-tests/codec-witness-pattern.mjs

@@ -0,0 +1,50 @@
+import assert from 'assert';
+import { parseValue } from '../valueIO.mjs';
+import { encodeToWire, decodeWire } from '../codecs/runtime/prefix-codec.mjs';
+import { Product, Variant } from '../Value.mjs';
+
+const value = parseValue('{a:{b:x,c:{}}}');
+const repeatedClosedValue = parseValue('{a:{m:{},n:{}},b:{m:{},n:{}}}');
+const repeatedOpenValue = parseValue('{a:x,b:x}');
+
+const defaultWire = decodeWire(encodeToWire(value, null));
+assert.deepEqual(defaultWire.pattern, [
+  ["open-union", [["a", 1]]],
+  ["closed-product", [["b", 2], ["c", 3]]],
+  ["open-union", [["x", 3]]],
+  ["closed-product", []]
+]);
+
+const explicitProductWire = decodeWire(encodeToWire(value, [
+  ["open-product", [["a", 1]]],
+  ["any", []]
+]));
+assert.deepEqual(explicitProductWire.pattern, [
+  ["open-product", [["a", 1]]],
+  ["closed-product", [["b", 2], ["c", 3]]],
+  ["open-union", [["x", 3]]],
+  ["closed-product", []]
+]);
+
+const decoded = explicitProductWire.value;
+assert(decoded instanceof Product);
+assert(decoded.product.a instanceof Product);
+assert(decoded.product.a.product.b instanceof Variant);
+assert.equal(decoded.product.a.product.b.tag, "x");
+
+const repeatedClosedWire = decodeWire(encodeToWire(repeatedClosedValue, null));
+assert.deepEqual(repeatedClosedWire.pattern, [
+  ["closed-product", [["a", 1], ["b", 1]]],
+  ["closed-product", [["m", 2], ["n", 2]]],
+  ["closed-product", []]
+]);
+
+const repeatedOpenWire = decodeWire(encodeToWire(repeatedOpenValue, null));
+assert.deepEqual(repeatedOpenWire.pattern, [
+  ["closed-product", [["a", 1], ["b", 3]]],
+  ["open-union", [["x", 2]]],
+  ["closed-product", []],
+  ["open-union", [["x", 2]]]
+]);
+
+console.log("OK");

package/Code-derivation-tests/convergence-strategy.mjs

@@ -0,0 +1,24 @@
+import assert from "assert";
+import { annotate } from "../index.mjs";
+
+const script = `
+  f = .x;
+  g = f;
+  g
+`;
+
+const autoAnnotated = annotate(script);
+assert.deepEqual(
+  autoAnnotated.compileStats.sccs.map(({ strategy }) => strategy),
+  ["single_pass", "single_pass", "single_pass"]
+);
+
+const fixedPointAnnotated = annotate(script, {
+  convergence: { strategy: "fixed_point" }
+});
+assert.deepEqual(
+  fixedPointAnnotated.compileStats.sccs.map(({ strategy }) => strategy),
+  ["fixed_point", "fixed_point", "fixed_point"]
+);
+
+console.log("OK");

package/Code-derivation-tests/dot.mjs

@@ -1,40 +1,43 @@
 import { t, in_out } from './index.mjs';
+import { hash } from '../hash.mjs';
 import assert from 'assert';
 
 t(`
 $b = < {} true, {} false > ; 
 $pair = { b one, b two } ;
-
+$bit = <{} 0, {} 1> ;
+1 = {} |1 $bit;
 $b {1 one, () two, () c} .one
 
 `, (annotated) => {
     const {input,output} = in_out(annotated);
     // console.log({input,output});
     assert.equal(input.type, annotated.representatives["b"]);
-    assert.equal(output.type, "@int");
+    assert.equal(output.type, annotated.representatives["bit"]);
     console.log("OK");
 });
 
 t(`
-    $a = < @int true, @bool false > ;
-    $a .true
+    $bit = <{} 0, {} 1> ;
+    $a = < bit true, bit false > ;
+    $a /true
   `, (annotated) => {
   const {input,output} = in_out(annotated);
   console.log({input,output});
 });
 
 t(`
-  x = .x;
-  xy = x.y;
+  x = /x;
+  xy = x/y;
   f = { 
-    { {5    y} x} xy i, 
-    { {true y} x} xy b 
+    {} | y | x xy i, 
+    {} | y | x xy b 
   };
   f .b
 `, (annotated) => {
   const {input,output} = in_out(annotated);
   console.log({input,output});
   assert.equal(input.pattern, '(...)');
-    assert.equal(output.type, "@bool");
+    assert.equal(output.type, hash("$C0={};"));
     console.log("OK");
 });

package/Code-derivation-tests/filter-syntax.mjs

@@ -0,0 +1,21 @@
+import assert from 'assert';
+import { annotate } from '../index.mjs';
+
+function succeeds(script) {
+  assert.doesNotThrow(() => annotate(script));
+}
+
+function fails(script) {
+  assert.throws(() => annotate(script));
+}
+
+succeeds('?(...)');
+succeeds('?{...}');
+succeeds('?<...>');
+succeeds('?{}');
+succeeds('?<>');
+
+fails('?()');
+fails('?(X x, ...)');
+
+console.log("OK");

package/Code-derivation-tests/loop.mjs

@@ -1,11 +1,17 @@
 import { t, in_out } from './index.mjs';
 import assert from 'assert';
 
+t(` < /a, () > `, (annotated) => {
+    const {input,output} = in_out(annotated);
+    assert.equal(input.pattern, "<...>");
+    assert.equal(output, input); 
+    console.log("OK");
+}); 
 t(` < .a, () > `, (annotated) => {
     const {input,output} = in_out(annotated);
-    assert.equal(input.pattern, "(...)");
+    assert.equal(input.pattern, "{...}");
     assert.equal(output, input); 
     console.log("OK");
 }); 
 
-// Notice that the following are equivalent: '<(), .a>', '<()>', and '()';
+// Notice that the following are equivalent: '<(), /a>', '<()>', and '()';

package/Code-derivation-tests/nat.mjs

@@ -2,7 +2,7 @@ import { t, in_out } from './index.mjs';
 import fs from 'node:fs';
 import assert from 'assert';
 
-t(fs.readFileSync("./Examples/nat.k").toString("utf8"), (annotated) => {
+t(fs.readFileSync("./Examples/nat.k", "utf8"), (annotated) => {
     const {input,output} = in_out(annotated);
     assert.equal(output.type, annotated.representatives["nat"]);
     assert.equal(input.type, annotated.representatives["nat"]);

package/Code-derivation-tests/not-not.mjs

@@ -2,9 +2,9 @@ import { t, in_out } from './index.mjs';
 import assert from 'assert';
 
 t(`$b = < {} true, {} false > ;
-   true = {{} true} $b;
-   false = {{} false} $b; 
-   not = $b < .true false, .false true >;
+   true = {} |true $b;
+   false = {} |false $b; 
+   not = $b < /true false, /false true >;
    not not
 `, (annotated) => {
    const {input,output} = in_out(annotated);

package/Code-derivation-tests/pattern-envelope.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import k from "../index.mjs";
+import { Product, Variant, mergePatterns, withPattern } from "../Value.mjs";
+import { decodeWire, encodeToWire } from "../codecs/runtime/prefix-codec.mjs";
+import run from "../run.mjs";
+import codes from "../codes.mjs";
+
+const INT_PATTERN = [
+  ["closed-union", [["+", 1], ["-", 1]]],
+  ["closed-union", [["0", 1], ["1", 1], ["_", 2]]],
+  ["closed-product", []]
+];
+
+const script = `
+  $ bits = < {} _, bits 0, bits 1 >;
+  $ int = < bits +, bits - >;
+  {}|_|0|1|+ $int
+`;
+
+const result = k.compile(script)(new Product({}));
+assert.deepEqual(result.pattern, INT_PATTERN);
+
+const decoded = decodeWire(encodeToWire(result, result.pattern));
+assert.deepEqual(decoded.pattern, INT_PATTERN);
+
+const two = new Variant("+",
+  new Variant("1",
+    new Variant("0",
+      new Variant("_", new Product({}))
+    )
+  )
+);
+const witnessPattern = [
+  ["closed-union", [["+", 1]]],
+  ["closed-union", [["1", 2]]],
+  ["closed-union", [["0", 3]]],
+  ["closed-union", [["_", 4]]],
+  ["closed-product", []]
+];
+const overExpandedSingleton = mergePatterns(INT_PATTERN, witnessPattern);
+const decodedMerged = decodeWire(encodeToWire(two, overExpandedSingleton));
+assert.deepEqual(decodedMerged.pattern, INT_PATTERN);
+
+const identityResult = k.compile("()")(withPattern(two, INT_PATTERN));
+assert.deepEqual(identityResult.pattern, INT_PATTERN);
+
+assert.throws(
+  () => k.compile(".x")(withPattern(two, INT_PATTERN)),
+  /Type Error in 'comp'.*Value envelope does not intersect expression input pattern/s
+);
+
+const projectionScript = `
+  $ bits = < {} _, bits 0, bits 1 >;
+  $ int = < bits +, bits - >;
+  $int /+
+`;
+const annotated = k.annotate(projectionScript);
+run.defs = annotated;
+const projected = run(
+  codes.find,
+  annotated.rels.__main__.def,
+  two,
+  annotated.rels.__main__.typePatternGraph
+);
+assert.deepEqual(projected.pattern, [
+  ["closed-union", [["0", 0], ["1", 0], ["_", 1]]],
+  ["closed-product", []]
+]);

package/Code-derivation-tests/rlz.mjs

@@ -3,8 +3,8 @@ import assert from 'assert';
 
 t(`
  $nat = < {} _, nat 0, nat 1>;
- zero = {{{} _} 0} $nat;
- rlz =  <.0._ zero, .0 rlz, ()>;
+ zero = {}|_|0 $nat;
+ rlz =  </0/_ zero, /0 rlz, ()>;
  rlz
  `, (annotated) => {
     const {input,output} = in_out(annotated);

package/{BIG_PICTURE.md → DOCS/BIG_PICTURE.md}

@@ -6,11 +6,13 @@
 
 The language describes "partial first-order functions" on "printable" values.
 The printable values can be seen as rooted, edge-labeled trees, intuitively similar to an
-XML or a JSON document. The values are always typed.
+XML or a JSON document. The values are always typed; in the current codec-aware
+runtime, a value may carry a pattern describing the family of types compatible
+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 (subclass of finite tree automata. The type defines a set of its 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.
 
@@ -19,6 +21,9 @@ Types are defined by two constructs:
 1. Product
 2. Union (also called tagged or disjoint union)
 
+> Notation: We use native k-like notation as canonical — products `{ T l, ... }` and unions `< T t, ... >`.
+> For convenience, JSON-like forms `{ l: T, ... }` and `< t: T, ... >` are also supported and equivalent in meaning.
+
 ```bnf
 type ::= name | '{' type_label_list '}' | '<' type_label_list '>'
 type_label_list ::= /* empty */ | ( type label ',' )* type label 
@@ -30,10 +35,10 @@ Given a finite (possibly empty) set of types `t1, t2, ..., tn` and a set of pair
 
 - by `{ t1 l1, t2 l2, ..., tn ln }`, we define a _product type_ with exactly `n`
   _projection_ functions: `.l1`, `.l2`, `...`, `.ln`.
-  Each projection function is mapping a value of type `{t1 l1, t2 l2, ..., tn ln}`
+  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`,
-  mapping 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.
 
 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
@@ -41,20 +46,31 @@ for a given value of the union type.
 
 Some properties of these types:
 
-1. Singleton product and singleton union types, `{ t label }` and `< t label >`, are equivalent as they have
-   the same set of values (and the same projection function `.label`). That's why, we not allow singleton product nor
-   singleton union types in the syntax of the language. The other benefit is that we will be able to use the same syntax
-   for writing out values of both product and union types, interpretting every singleton product-like value, e.g., `{ a_value label }`,
-   as a union type value (a variant).  
-2. The empty product type, `{}`, has a single value, called the _unit_
-   and also denoted by `{}`, which has no fields.
-3. The empty union type, `<>`, has no values.
+1. The empty product type, `{}`, has a single value, called the _unit_.
+2. The empty union type, `<>`, has no values.
+
+#### Variant (union) value literal convention
+
+- Variant values are written using "|" (pipe) followed by the variant tag.
+  - Unit variant `` `{}` `` | tag (e.g., `{} | nil`, `{} | zero`)
+  - Variant with payload `v` at label `tag`: ` v | tag `
+- Example (list): with `$list = < {} nil, {X car, list cdr} cons >`:
+  - Empty list []: `{}|nil`
+  - Singleton `[v]`: `{ v car, {}|nil cdr } | cons`
+- Angle brackets are for type definitions and merge expressions; use "`| tag`" for a variant construction.
+
+#### Equivalence of types (bisimilarity)
+
+Two (possibly recursive) codes are equivalent iff they are bisimilar over their definition graphs. Concretely, there exists a relation B such that `(t1, t2) ∈ B` if and only if:
+- t1 and t2 have exactly the same set of labels/tags;
+- t1 and t2 are simultaneously products or simultaneously unions;
+- for each label/tag `ℓ` in the set, the subcodes under `ℓ` are again related by B.
 
 ### Filters (patterns)
 
-A _filter_ is a way of representing a _type class_, i.e, a set of types sharing some struture.
+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 a pattern: `?{ T f, ... }`. In general, a filter is defined by:
+I would write: `?{ T f, ... }`. In general, a filter is defined by:
 
 ```bnf
 filter ::= name | '$' type_expr | '{' filter_label_list '}'
@@ -71,8 +87,7 @@ Examples:
   ( ... )           -- any type
   { ... }           -- any product type
   ( X x, X y )      -- any type with two fields of the same type
-  < X x, ... > = X  -- a (recursive) type, 'X', with variant 'x'
-                    -- of the same type 'X' 
+  < X x, ... > = X  -- a (recursive) variant type, 'X', with variant 'x' of the same type 'X' 
 ```
 
 ### Partial functions
@@ -86,7 +101,7 @@ There are three ways of combining partial functions:
    and `g` is defined on value `y` producing `z`, then `(f g)` is defined on value `x` producing `z`.
 2. __Union__: we write `< f1, f2 >` for a union of two functions `f1` and `f2`, meaning that
    if `f1` is defined on value `x` producing `y`, then `< f1, f2 >`
-   is defined on value `x` producing `y`. Otherwise, i.e., when `f1` is not defined for `x`, `< f1 f2 >` acts as `f2`.
+   is defined on value `x` producing `y`. Otherwise, i.e., when `f1` is not defined for `x`, `< f1, f2 >` acts as `f2`.
 3. __Product__: we write `{f1 lab1, f2 lab2 }` for a product of two functions `f1` and `f2`,
    meaning that if `f1` and `f2` are both defined on value `x` producing `y1` and `y2`,
    respectively, then `{f1 lab1, f2 lab2 }` is defined on value `x` producing
@@ -109,7 +124,7 @@ type_definition ::= '$' type_name '=' type ';'
 function_definition ::= name '=' expression ';'
 expression ::= name | '$' type | '?' filter 
    | projection | composition | union | product 
-projection ::= '.' label
+projection ::= '.' label | '/' label
 composition ::= '(' expression * ')'  
 union ::= '<' (expression ',') + expression '>' 
 product ::= '{' expr_label_list '}'
@@ -123,7 +138,7 @@ We assume that in a `kernel-core` program the names (for types, functions, and l
 2. All defined function names are distinct.
 3. All label names within a type definition or a `product` expression are locally distinct.
 
-`Filter` or `type` expressions act as a type annotation, i.e., an identity
+Filters and type expressions act as a type annotation, i.e., an identity
 function defined only for the values of the corresponding types.
 
 That's it.
@@ -141,7 +156,7 @@ Obviously, a function may have many different definitions so the hash-based name
 This approach solves the problem of modules, imports, etc., and opens the door to a universal
 registry of types (schemas) and functions.
 
-## Typing and Polymorphism (codes and filters/patterns)
+## 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_.
@@ -154,7 +169,7 @@ representations for functions, so they could be reused.
 
 The normalization steps are:
 
-1. Build the _type graph_ from all types used by the program, i.e., used in _type definitions_ 
+1. Build the _type graph_ from all types used by the program, i.e., used in _type definitions_
    as well as type expressions used in _function definitions_ and the _main expression_.
 2. Annotate the expressions with filters; every node of the AST is annotated with a pair of filters.
 3. Turn the _singleton_ filters into types and add them to the _type graph_. Go to (2) unless no change.
@@ -165,23 +180,23 @@ The normalization steps are:
 
 ```k-repl
 $ bit = < {} o, {} i >;
-bit0 = {{} o} $bit;
-bit1 = {{} i} $bit;
+bit0 = | o $bit;
+bit1 = | i $bit;
 
 $ byte = { bit b0, bit b1, bit b2, bit b3 };
 zero = bit0 { () b0, () b1, () b2, () b3 } $byte;
 
-inc = $byte
+inc = $ byte
    <
-      { .b0.o bit0  overflown,  {bit1 b0, .b1  b1,  .b2 b2,  .b3 b3 } byte }, 
-      { .b1.o bit0  overflown,  {bit0 b0, bit1 b1,  .b2 b2,  .b3 b3 } byte },
-      { .b2.o bit0  overflown,  {bit0 b0, bit0 b1, bit1 b2,  .b3 b3 } byte },
-      { .b3.o bit0  overflown,  {bit0 b0, bit0 b1, bit0 b2, bit1 b3 } byte },
-      { bit1        overflown,  zero                                  byte }
+      { bit0 overflown,  { .b0/o bit1 b0, .b1  b1,  .b2 b2,  .b3 b3 } byte }, 
+      { bit0 overflown,  { bit0 b0, .b1/o bit1 b1,  .b2 b2,  .b3 b3 } byte },
+      { bit0 overflown,  { bit0 b0, bit0 b1, .b2/o bit1 b2,  .b3 b3 } byte },
+      { bit0 overflown,  { bit0 b0, bit0 b1, bit0 b2, ,b3/o bit1 b3 } byte },
+      { bit1 overflown,  zero                                         byte }
    >  
 ;
 
--- inc with overflown flag (polymorphism)
+-- inc with overflown flag
 inc_o = 
   { .byte inc inc, .overflown overflown }  
   {
@@ -195,8 +210,8 @@ inc3 = inc inc_o inc_o;
 inc3
 ```
 
-In the above program, we define a type `bit` a union of two unit types, 
-and a type `byte` as a product, for simplicity, of four `bit`s. 
+In the above program, we define type `bit` as union of two unit types,
+and type `byte` as product, for simplicity, of four `bit`s.
 
 Functions `bit0`, `bit1`, and `zero` are "constant polymorphic functions", meaning:
 
@@ -209,18 +224,18 @@ Functions `inc` and `inc3` are (non-polymorphic) functions of types
 `$byte -> ${ bit overflown, byte byte }` and
 `${ bit overflown, byte byte } -> ${ bit overflown, byte byte }`, respectively.
 
-Function `inc_o` is a polymorphic function of type patterns: `?X -> ${ byte byte, bit overflown }` 
+Function `inc_o` is a polymorphic function of type patterns: `?X -> ${ byte byte, bit overflown }`
 with following constraints:
 
-- `?X` is a product or union type with at least two fields: `byte` and `overflown`, denoted by:
-   > `?( $byte byte, Z overflown, ...)`;
-- `?Z` is a type (union or product) with field `i` denoted by:
-   > `?( V i, ...)`;
+- `?X` is a product type with at least two fields: `byte` and `overflown`, denoted by:
+   > `?{ $byte byte, Z overflown, ...}`;
+- `?Z` is a union type with field `i` denoted by:
+   > `?< V i, ...>`;
 - `V` is unconstrained, denoted by `(...)`;
 
-We can write it as: `?($byte byte, ((...) i, ...) overflown, ...)`.
+We can write it as: `?{$byte byte, <(...) i, ...> overflown, ...}`.
 
-The target type `${ byte byte, bit overflown }` was derived from pattern `?{ $byte byte, $bit overflown }`.
+The target type `${ byte byte, bit overflown }` corresponds to pattern `?{ $byte byte, $bit overflown }`.
 Such a pattern is called _singleton pattern_, as only one type fits the pattern.
 
 #### Example 2
@@ -229,12 +244,12 @@ Polymorphic list functions:
 
 ```k-repl
 list? = ?< {} nil, {X car, Y cdr} cons > = Y;
-nil = {{} nil} list?;
-singleton = {{() car, nil cdr} cons} list?;
-cons = {{.car car, .cdr cdr} cons} list?;
-nil? = list? .nil nil;
-car = list? .cons .car;
-cdr = list? .cons .cdr;
+nil = {} |nil list?;
+singleton = {() car, nil cdr} |cons list?;
+cons = {.car car, .cdr cdr} | cons list?;
+nil? = list? /nil nil;
+car = list? /cons .car;
+cdr = list? /cons .cdr;
 ```
 
 For example, the filter annotation for `car` is:
@@ -272,16 +287,54 @@ 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
 be compiled into deterministic finite (pushdown) transducers.
 
-### AND-OR graphs for enconding and decoding codes
+### AND-OR graphs for encoding and decoding codes
 
-This could be generic and compact way to encode and decode typed values.
+This could be a generic and compact way to encode and decode typed values.
 The idea is to use _prefix codes_ (a class of languages such that no word is a prefix of
 another word) to encode the values.
 
-### RUST data structures
+### Rust data structures
 
 A type can be translated into a Rust data structure, and a function can be translated into a Rust function.
 
 ## Linking with Other Languages
 
-## Streams and Arrays (Map-Reduce)
+## Streams and Arrays (Map-Reduce)
+
+## Bits
+
+Extending `@string` into `@bits`. 
+
+```k-repl
+$ bits = < {} _, bits 0, bits 1 >;
+```
+
+### Literals for `@bits` are:
+
+- `0b` for 0 bits
+- `0b10` for 2 bits
+- `0xF` for 4 bits
+- `0xF0` for 8 bits
+- `0o1` for 3 bits
+- `0o7` for 3 bits
+- "" for 0 bits
+- "ala" for 24 bits
+
+### Two operations on `@bits`:
+
+#### Eat `/`
+
+- `$@bits / @bits` --- division, e.g., `0b1011 / 0b10` = `0b11`, `"abc" / "a"` = `"bc"`
+
+#### Prepend `\`
+
+- `$@bits \ @bits` --- multiplication, e.g., `0b11 \ 0b10` = `0b1011`, `"bc" \ "a"` = `"abc"`
+
+Empty `bits` can be checked by
+
+```k
+
+kind = $@bits 
+  < {/ 0b0 \ 0b0 starts_with_0}, {/ 0b1 \ 0b1 starts_with_1}, {() empty} > 
+  $< @bits starts_with_0, @bits starts_with_1, @bits empty >;
+```