@fraczak/k 6.10.2 → 6.10.3

package/objects/README.md

@@ -1,29 +1,36 @@
 # objects/
 
-CLI tools for compiling and inspecting k object files (`.ko`) and library files (`.klib`).
+CLI tools for compiling and inspecting k object files (`.ko`), library
+files (`.klib`), and polymorphic kVM template files (`.kvm`).
 
 ## Tools
 
 ### `k-compile`
 
-Compiles `.k` source into an executable object file (`.ko`), library file
-(`.klib`), or polymorphic kVM backend artifact (`.kvm`). Output format is
-inferred from the output extension, or from `--format`.
+Compiles `.k` source into an executable object file (`.ko`), library
+file (`.klib`), or polymorphic kVM backend artifact (`.kvm`). Output
+format is inferred from the output extension, or from `--format`.
 
 ```bash
-k-compile [--lib lib-file] [--export spec]... [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
+k-compile [--lib lib-file] [--export spec]... \
+  [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
 ```
 
-Existing input paths are read as files. A non-existing input with `.k`, `.ko`,
-or `.klib` extension is reported as a missing file; otherwise it is compiled as
-inline k source, in the same style as `k.mjs`.
+Existing input paths are read as files. A non-existing input with `.k`,
+`.ko`, or `.klib` extension is reported as a missing file; otherwise it
+is compiled as inline k source, in the same style as `k.mjs`.
 
-`.kvm` is a polymorphic kVM template artifact (`layer: "KVM-P"`). It carries the
-relational function definitions, their principal input/output pattern graphs, and
-lowered kVM instruction streams ready for runtime specialization when enveloped
-values arrive. Specialization occurs when functions are invoked on concrete values,
-eliminating the need for ahead-of-time input pattern or input type flags. Names from
-a `--lib` dependency can be imported into the entry scope using `--export (oldname:)?newname`.
+`.kvm` is a polymorphic kVM template artifact (`layer: "KVM-P"`). It
+carries relational function definitions, principal pattern graphs,
+and lowered kVM instruction streams ready for runtime specialization
+when enveloped values arrive (`specializeKVM`).
+
+When linking a `--lib` dependency, all relations are loaded under their
+canonical content-addressed hashes (`@hash`). To use human-readable
+alias names in an expression or script, explicitly map them into the
+local scope using `--export <alias>` or
+`--export <libAlias>:<localAlias>`.
+Alternatively, canonical `@hash` names may always be referenced directly.
 
 ### `k-decompile`
 
@@ -35,9 +42,9 @@ k-decompile [object-file [k-file]]
 
 ### `k-extract-aliases`
 
-Extracts metadata aliases from a `.ko` or `.klib` as a valid k definition
-snippet. Output is grouped by metadata type (`code`, then `rel`), then sorted by
-alias name and `compiledAt`.
+Extracts metadata aliases from a `.ko` or `.klib` as a valid k
+definition snippet. Output is grouped by metadata type (`code`, then
+`rel`), then sorted by alias name and `compiledAt`.
 
 ```bash
 k-extract-aliases [object-file [k-file]]
@@ -45,15 +52,16 @@ k-extract-aliases [object-file [k-file]]
 
 ### `k-inspect-object`
 
-Inspects a `.ko` or `.klib`. By default it prints a compact object summary.
-With `--kir`, it prints the current KIR-P export used by backend experiments.
+Inspects a `.ko` or `.klib`. By default it prints a compact object
+summary. With `--kir`, it prints the current KIR-P export used by
+backend experiments.
 
 ```bash
 k-inspect-object [--summary | --kir] [object-file]
 ```
 
-For scripts that only need KIR-P export, `k-kir [object-file]` is the direct
-exporter backed by `kir.mjs`.
+For scripts that only need KIR-P export, `k-kir [object-file]` is the
+direct exporter backed by `kir.mjs`.
 
 ### `k-validate-object`
 
@@ -64,29 +72,41 @@ Validates a `.ko` or `.klib` object and its derived KIR-P export. With
 k-validate-object [--kir] [input-file]
 ```
 
-The installed names are `k-` plus the source basename without `.mjs`. Every
-installed object binary supports `-h` and `--help`.
+The installed names are `k-` plus the source basename without `.mjs`.
+Every installed object binary supports `-h` and `--help`.
 
 ## Current Format Notes
 
-- `.klib` files are plain UTF-8 JSON, not binary containers.
-- `.ko` files use the `KOBJ\n` binary header followed by a JSON payload.
+- For full specifications, see
+  [`DOCS/FILE_FORMATS.md`](../DOCS/FILE_FORMATS.md).
+- Both `.ko` and `.klib` are ahead-of-time (AOT) type-checked artifacts.
+  Parsing, relation expansion, type derivation, and constraint
+  convergence are completed in advance.
+- `.klib` files are plain UTF-8 JSON, not binary containers
+  (`main: null`).
+- `.ko` files use the `KOBJ\n` binary header followed by a JSON payload
+  (`main: "__main__"`).
 - There is no object payload version field in either format.
 - `typeDerivation` belongs only to relations and currently stores only
   `status`.
 - Source `start` / `end` ranges live on `meta[hash].origins[]` entries.
-- Origin entries do not have `kind`; the metadata entry has `type: "code"` or
-  `type: "rel"`.
-- Stored relation bodies do not include generated input/output boundary filters.
-- KIR-P is available as an inspection/export contract; it does not change the
-  stored `.ko` or `.klib` payload.
-- `.kvm` is not a canonical source/object format; it is a polymorphic backend
-  template artifact (`layer: "KVM-P"`), lowered from KIR-P for runtime execution
-  and JIT specialization.
+- Origin entries do not have `kind`; the metadata entry has `type: "code"`
+  or `type: "rel"`.
+- Stored relation bodies do not include generated input/output filters.
+- KIR-P is available as an inspection/export contract; it does not change
+  the stored `.ko` or `.klib` payload.
+- `.kvm` is a polymorphic backend template artifact (`layer: "KVM-P"`),
+  lowered from KIR-P for runtime execution and JIT specialization.
 
 ## Further reading
 
-- [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) — object file format and pattern encoding
-- [DOCS/KIR_V1.md](../DOCS/KIR_V1.md) — KIR-P inspection/export contract for backends
-- [DOCS/TYPE_DERIVATION.md](../DOCS/TYPE_DERIVATION.md) — type derivation (what compilation skips when loading a `.ko`/`.klib`)
-- [DOCS/CONVERGENCE.md](../DOCS/CONVERGENCE.md) — convergence strategies for type inference
+- [DOCS/FILE_FORMATS.md](../DOCS/FILE_FORMATS.md) — guide to
+  .k, .ko, .klib, and .kvm formats
+- [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) —
+  object file format and pattern encoding
+- [DOCS/KIR_V1.md](../DOCS/KIR_V1.md) — KIR-P inspection/export contract
+  for backends
+- [DOCS/TYPE_DERIVATION.md](../DOCS/TYPE_DERIVATION.md) — type
+  derivation (what compilation skips when loading a `.ko`/`.klib`)
+- [DOCS/CONVERGENCE.md](../DOCS/CONVERGENCE.md) — convergence strategies
+  for type inference

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.10.2",
+    "version": "6.10.3",
     "description": "k — a language for composing first-order partial functions over algebraic data types (products and tagged unions); includes runtime, type derivation, REPL, and codec toolchain",
     "main": "index.mjs",
     "exports": {

package/tests/README.md

@@ -1,6 +1,7 @@
 # k Test Suite
 
-This directory contains the automated tests, type-derivation validation cases, and integration test scripts for the `k` compiler and runtime.
+This directory contains automated tests, type-derivation validation
+cases, and integration test scripts for the `k` compiler and runtime.
 
 ## Running the Tests
 
@@ -9,27 +10,37 @@ To run all core unit tests, type-derivation checks, and integration tests:
 ```bash
 npm test
 ```
-This executes `node scripts/run-tests.mjs`, which discovers and runs the test scripts sequentially.
+This executes `node scripts/run-tests.mjs`, which discovers and runs the
+test scripts sequentially.
 
 ## Test Directory Structure
 
 ### Core Test Files
-- **[test.mjs](file:///Users/wojtek/gits/k/tests/test.mjs)**: Verifies basic parser and runtime execution behavior.
-- **[test-kvm.mjs](file:///Users/wojtek/gits/k/tests/test-kvm.mjs)**: Comprehensive conformance testing for the kVM register compiler and interpreter under both envelope-aware and envelope-free modes.
-- **[test-ieee-arithmetic.mjs](file:///Users/wojtek/gits/k/tests/test-ieee-arithmetic.mjs)**: Verifies IEEE-754 double precision float arithmetic implementation (`Examples/ieee.k`).
-- **[test-repl.mjs](file:///Users/wojtek/gits/k/tests/test-repl.mjs)**: Tests interactive REPL commands, state transitions, imports, and auto-completions.
-- **[test-k-object.mjs](file:///Users/wojtek/gits/k/tests/test-k-object.mjs)**: Tests serialization, compilation, and loading of `.ko` binary objects.
-- **[test-fingerprint.mjs](file:///Users/wojtek/gits/k/tests/test-fingerprint.mjs)**: Tests semantic expression and relation hashing/fingerprinting.
-- **[test-hash-normalization.mjs](file:///Users/wojtek/gits/k/tests/test-hash-normalization.mjs)**: Verifies consistent normalization of type pattern graphs and hashes.
-- **[test-hash-fuzz.mjs](file:///Users/wojtek/gits/k/tests/test-hash-fuzz.mjs)**: Fuzzes expression/relation hashing to guard against collisions.
-
-### WebAssembly Benchmarks
-
-The WebAssembly execution benchmark moved to the separate
-[`fraczak/k-wasm`](https://github.com/fraczak/k-wasm) backend repository.
+- **[test.mjs](test.mjs)**: Verifies basic parser and runtime
+  execution behavior.
+- **[test-kvm.mjs](test-kvm.mjs)**: Conformance testing for the kVM
+  register compiler and interpreter in envelope-aware and envelope-free
+  modes.
+- **[test-kvm-polymorphic.mjs](test-kvm-polymorphic.mjs)**: Tests for
+  polymorphic `.kvm` templates (`layer: "KVM-P"`) and runtime input
+  envelope specialization (`specializeKVM`).
+- **[test-ieee-arithmetic.mjs](test-ieee-arithmetic.mjs)**: Verifies
+  IEEE-754 double precision float arithmetic (`Examples/ieee.k`).
+- **[test-repl.mjs](test-repl.mjs)**: Tests interactive REPL commands,
+  state transitions, imports, `.klib` and `.ko` exports.
+- **[test-k-object.mjs](test-k-object.mjs)**: Tests serialization,
+  compilation, and loading of `.ko` binary objects and `.klib` libraries.
+- **[test-fingerprint.mjs](test-fingerprint.mjs)**: Tests semantic
+  expression and relation hashing/fingerprinting (`@hash`).
+- **[test-hash-normalization.mjs](test-hash-normalization.mjs)**:
+  Verifies consistent normalization of type pattern graphs and hashes.
+- **[test-hash-fuzz.mjs](test-hash-fuzz.mjs)**: Fuzzes expression and
+  relation hashing to guard against collisions.
 
 ### Type Derivation Suites
-- **[code-derivation/](file:///Users/wojtek/gits/k/tests/code-derivation)**: Houses individual files (each containing a focused test scenario) validating type-derivation convergence and pattern-envelope generation.
+- **[code-derivation/](code-derivation/)**: Individual files validating
+  type-derivation convergence and pattern-envelope generation.
 
 ### Integration Scripts
-- **[integration.sh](file:///Users/wojtek/gits/k/tests/integration.sh)**: Shell script checking boundary data pipelines (`k-parse`, `k-show`, `k-print`) against binary outputs.
+- **[integration.sh](integration.sh)**: Shell script checking boundary
+  data pipelines (`k-parse`, `k-show`, `k-print`) against binary outputs.