@fraczak/k 6.0.1 → 6.0.3

package/codecs/runtime/test-codec.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Test the binary codec with basic k types
+ */
+
+import { deriveClosedPattern } from './codec.mjs';
+import { encodeToWire, decodeWire } from './prefix-codec.mjs';
+import { patternToPropertyList } from './pattern-json.mjs';
+import { Product, Variant } from '../../Value.mjs';
+import hash from '../../hash.mjs';
+
+// Type repository
+const types = {};
+
+// Define unit type: {}
+const unitTypeDef = { code: 'product', product: {} };
+const unitTypeStr = '$C0={};';
+const unitTypeName = hash(unitTypeStr);
+types[unitTypeName] = unitTypeDef;
+
+console.log('Unit type name:', unitTypeName);
+
+// Define bool type: <{} false, {} true>
+const boolTypeDef = {
+  code: 'union',
+  union: {
+    false: unitTypeName,
+    true: unitTypeName
+  }
+};
+const boolTypeStr = `$C0=<${unitTypeName}"false",${unitTypeName}"true">;`;
+const boolTypeName = hash(boolTypeStr);
+types[boolTypeName] = boolTypeDef;
+
+console.log('Bool type name:', boolTypeName);
+
+// Resolver function
+function resolveType(typeName) {
+  if (!types[typeName]) {
+    throw new Error(`Unknown type: ${typeName}`);
+  }
+  return types[typeName];
+}
+
+// Test 1: Unit value
+console.log('\n=== Test 1: Unit ===');
+const unitValue = new Product({});
+console.log('Encoding unit:', unitValue.toString());
+
+const unitPattern = patternToPropertyList(deriveClosedPattern(unitTypeName, unitTypeDef, resolveType));
+const unitEncoded = encodeToWire(unitValue, unitPattern);
+console.log('Encoded bytes:', unitEncoded.length, 'bytes');
+console.log('Hex:', unitEncoded.toString('hex'));
+
+const unitDecoded = decodeWire(unitEncoded);
+console.log('Decoded value:', unitDecoded.value.toString());
+console.log('Match:', unitDecoded.value instanceof Product && 
+            Object.keys(unitDecoded.value.product).length === 0);
+
+// Test 2: Bool false
+console.log('\n=== Test 2: Bool (false) ===');
+const falseValue = new Variant('false', new Product({}));
+console.log('Encoding false:', falseValue.toString());
+
+const boolPattern = patternToPropertyList(deriveClosedPattern(boolTypeName, boolTypeDef, resolveType));
+const falseEncoded = encodeToWire(falseValue, boolPattern);
+console.log('Encoded bytes:', falseEncoded.length, 'bytes');
+console.log('Hex:', falseEncoded.toString('hex'));
+
+const falseDecoded = decodeWire(falseEncoded);
+console.log('Decoded value:', falseDecoded.value.toString());
+console.log('Match:', falseDecoded.value instanceof Variant && 
+            falseDecoded.value.tag === 'false');
+
+// Test 3: Bool true
+console.log('\n=== Test 3: Bool (true) ===');
+const trueValue = new Variant('true', new Product({}));
+console.log('Encoding true:', trueValue.toString());
+
+const trueEncoded = encodeToWire(trueValue, boolPattern);
+console.log('Encoded bytes:', trueEncoded.length, 'bytes');
+console.log('Hex:', trueEncoded.toString('hex'));
+
+const trueDecoded = decodeWire(trueEncoded);
+console.log('Decoded value:', trueDecoded.value.toString());
+console.log('Match:', trueDecoded.value instanceof Variant && 
+            trueDecoded.value.tag === 'true');
+
+console.log('\n=== All tests complete ===');

package/kkk.k

@@ -0,0 +1,197 @@
+-- core.k — the k standard core library
+--
+-- Defines:
+--   1. $bits — the canonical binary number / bit-path type
+--   2. $string — unicode strings (used for labels)
+--   3. $pattern — the type of pattern graphs
+--   4. Basic $bits arithmetic: succ, plus, times
+
+---------------------------------------------------------------
+-- §1. Bits
+---------------------------------------------------------------
+
+$ bit = < {} 0, {} 1 >;
+b0 = {}|0 $bit;
+b1 = {}|1 $bit;
+
+$ bits = < {} _, bits 0, bits 1 >;
+
+_ = {}|_;
+
+0 = _ |0;
+1 = _ |1;
+
+inv = {() x, _ r} _inv;
+_inv = ${bits x, bits r} < {.x /0 x, .r |0 r} _inv, {.x /1 x, .r |1 r} _inv, .r >;
+
+concat = ${bits x, bits y} {.x inv x, .y y} concat_;
+concat_ = ${bits x, bits y}
+  <
+    {.x /0 x, .y |0 y} concat_,
+    {.x /1 x, .y |1 y} concat_,
+    .y
+  >;
+
+---------------------------------------------------------------
+-- §2. Bits arithmetic
+---------------------------------------------------------------
+
+-- successor (increment by 1)
+succ = {inv x, _ y} _inc;
+
+_inc = ${bits x, bits y} <
+    {.x /0 x, .y |1 y} concat_,
+    {.x /1 x, .y |0 y} _inc,
+    .y |1
+>;
+
+-- constants
+2 = 1 succ;
+3 = 2 succ;
+4 = 3 succ;
+5 = 4 succ;
+6 = 5 succ;
+7 = 6 succ;
+8 = 7 succ;
+9 = 8 succ;
+10 = 9 succ;
+
+-- addition on $bits (unsigned, LSB-first with carry)
+plus = ${bits x, bits y} {.x inv x, .y inv y, b0 c} _plus;
+_plus = ${bits x, bits y, bit c}
+  <
+    {.x /_ if, .y /_ and, <.c/0 0, 1> then} .then,
+    {.x /_ if, .c/0 and, .y then} .then,
+    {.x y, .y /_|_ x, .c c} _plus,
+    {<.c/0 0, 1> x, .y y, .x /_ b0 c} _plus,
+    {.x /0 x, .y /0 y, .c/0 b0 c} _plus |0,
+    {.x /0 x, .y /0 y, .c/1 b0 c} _plus |1,
+    {.x /0 x, .y /1 y, .c/0 b0 c} _plus |1,
+    {.x /0 x, .y /1 y, .c/1 b1 c} _plus |0,
+    {.x /1 x, .y /0 y, .c/0 b0 c} _plus |1,
+    {.x /1 x, .y /0 y, .c/1 b1 c} _plus |0,
+    {.x /1 x, .y /1 y, .c/0 b1 c} _plus |0,
+    {.x /1 x, .y /1 y, .c/1 b1 c} _plus |1
+  >;
+
+-- multiplication on $bits (unsigned, shift-and-add)
+times = ${bits x, bits y} {0 result, .x inv _x, .y y} _times;
+_times = ${bits result, bits _x, bits y}
+  <
+    { .y /_ if, .result then } .then,
+    {
+      .result |0 result,
+      ._x _x,
+      .y /0 y
+    } _times,
+    {
+      {._x x, .result |0 y, b0 c} _plus result,
+      ._x _x,
+      .y /1 y
+    } _times
+  >;
+
+---------------------------------------------------------------
+-- §3. Unicode and String
+---------------------------------------------------------------
+
+-- 8-bit octet used as a building block for UTF-8 payload pieces.
+$ byte = {
+  bit 0, bit 1, bit 2, bit 3,
+  bit 4, bit 5, bit 6, bit 7
+};
+
+-- 7-bit ASCII code point payload (U+0000..U+007F).
+$ ascii = { bit 6, bit 5, bit 4, bit 3, bit 2, bit 1, bit 0 };
+
+-- 11-bit payload used for Plane 0 code points U+0080..U+07FF.
+-- Plane 0 is the Basic Multilingual Plane (BMP): U+0000..U+FFFF.
+$ u0080_07FF = { bit 10, bit 9, bit 8, bit 7, bit 6, bit 5, bit 4, bit 3, bit 2, bit 1, bit 0 };
+
+-- High-byte classes for common BMP ranges, excluding surrogate/private-use partitions.
+-- BMP (Basic Multilingual Plane) is Plane 0: the first 65,536 code points.
+$ bmp_hi_common = <
+  { bit 2, bit 1, bit 0 } h08_0F,
+  { bit 6, bit 5, bit 4, bit 3, bit 2, bit 1, bit 0 } h10_7F,
+  { bit 6, bit 5, bit 4, bit 3, bit 2, bit 1, bit 0 } h80_CF,
+  { bit 2, bit 1, bit 0 } hD0_D7,
+  {} hF9,
+  { bit 0 } hFA_FB,
+  { bit 0 } hFC_FD,
+  { bit 0 } hFE_FF
+>;
+
+-- High-byte classes for BMP private-use/high-reserved slices.
+-- These partitions keep Plane 0 subsets explicit in the type encoding.
+$ bmp_hi_private_use = <
+  { bit 3, bit 2, bit 1, bit 0 } hE0_EF,
+  { bit 2, bit 1, bit 0 } hF0_F7,
+  {} hF8
+>;
+
+-- Plane selector for supplementary code points in Planes 2..16.
+-- Supplementary planes are all planes above BMP (Plane 0).
+$ plane_02_10 = <
+  { bit 0 } p02_03,
+  { bit 1, bit 0 } p04_07,
+  { bit 2, bit 1, bit 0 } p08_0F,
+  {} p10
+>;
+
+-- Canonical Unicode scalar-value partition used by string encoding.
+-- Branch meaning:
+-- - ascii: U+0000..U+007F (subset of BMP / Plane 0)
+-- - plane0: U+0080..U+07FF (still Plane 0)
+-- - bmp_common, bmp_private_use: U+0800..U+FFFF partitions (Plane 0)
+-- - supplementary_plane1: U+10000..U+1FFFF (Plane 1)
+-- - supplementary_planes2_16: U+20000..U+10FFFF (Planes 2..16)
+$ unicode = <
+  ascii ascii,
+  u0080_07FF plane0,
+  { bmp_hi_common hi, byte lo } bmp_common,
+  { bmp_hi_private_use hi, byte lo } bmp_private_use,
+  { byte mid, byte lo } supplementary_plane1,
+  { plane_02_10 plane, byte mid, byte lo } supplementary_planes2_16
+>;
+
+-- Linked-list string: nil or (unicode car, string cdr).
+$ string = < {} nil, { unicode car, string cdr } cons >;
+
+---------------------------------------------------------------
+-- §4. Pattern
+---------------------------------------------------------------
+
+-- Edge: a labeled edge in a pattern graph.
+-- 'label' is the field name or tag name.
+-- 'target' is the index (as $bits) of the target node in the pattern list.
+
+$ edge = { string label, bits target };
+
+-- Edge list: the edges of a pattern node, sorted by label.
+
+$ edges = < {} nil, { edge car, edges cdr } cons >;
+
+-- Pattern node: one of five kinds.
+-- "any" is the unconstrained position (...), carrying no edges.
+-- The four others carry their edge list directly.
+
+$ pattern-node = <
+  {} any,
+  edges open-product,
+  edges open-union,
+  edges closed-product,
+  edges closed-union
+>;
+
+-- Pattern: a cons-list of pattern nodes.
+-- Node 0 (first element) is the root.
+-- Edges reference nodes by their index in this list, encoded as $bits.
+--
+-- The singleton pattern of $pattern itself is a fixed constant.
+-- That constant is the implicit framing for all k wire formats:
+-- to decode any value, first decode a $pattern under that constant,
+-- then decode the value under the pattern just obtained.
+
+$ pattern = < {} nil, { pattern-node car, pattern cdr } cons >;
+
+$pattern

package/object.mjs

@@ -61,19 +61,86 @@ function hydrateAnnotated(serialized) {
   };
 }
 
+const NAME_RE = /^[a-zA-Z0-9_+-][a-zA-Z0-9_?!+-]*$/;
+
+function isSourceName(name) {
+  return NAME_RE.test(name) && !name.startsWith("@") && !name.startsWith(":");
+}
+
+function addOrigin(meta, hash, type, origin) {
+  if (!hash) return;
+  if (!meta[hash]) {
+    meta[hash] = { type, origins: [] };
+  } else if (meta[hash].type == null) {
+    meta[hash].type = type;
+  } else if (meta[hash].type !== type) {
+    throw new Error(`Metadata type conflict for ${hash}: ${meta[hash].type} vs ${type}`);
+  }
+  if (meta[hash].origins.some((existing) =>
+    existing.source === origin.source &&
+    existing.name === origin.name &&
+    existing.compiledAt === origin.compiledAt
+  )) {
+    return;
+  }
+  meta[hash].origins.push(origin);
+}
+
+function mergeMetaEntries(...metas) {
+  const merged = {};
+  for (const meta of metas) {
+    for (const [hash, entry] of Object.entries(meta || {})) {
+      const type = entry?.type;
+      if (type !== "code" && type !== "rel") continue;
+      for (const origin of entry.origins || []) {
+        if (!origin?.name) continue;
+        addOrigin(merged, hash, type, {
+          ...(origin.source == null ? {} : { source: origin.source }),
+          name: origin.name,
+          ...(origin.compiledAt == null ? {} : { compiledAt: origin.compiledAt })
+        });
+      }
+    }
+  }
+  return merged;
+}
+
 function buildMeta(annotated, source) {
   const meta = {};
+  const representatives = annotated.representatives || {};
   const relAlias = annotated.relAlias || {};
   const now = new Date().toISOString();
-  // Relation metadata: source name → canonical hash
+
+  for (const [name, hash] of Object.entries(representatives)) {
+    if (!isSourceName(name)) continue;
+    addOrigin(meta, hash, "code", { source, name, compiledAt: now });
+  }
+
   for (const [name, hash] of Object.entries(relAlias)) {
     if (name === "__main__") continue;
-    if (!meta[hash]) meta[hash] = { origins: [] };
-    meta[hash].origins.push({ source, name, compiledAt: now });
+    if (!isSourceName(name)) continue;
+    addOrigin(meta, hash, "rel", { source, name, compiledAt: now });
   }
   return meta;
 }
 
+function importedLibraryMeta(libraries = []) {
+  return mergeMetaEntries(...libraries.map((library) => library.meta || {}));
+}
+
+function isEofParseError(error) {
+  return error?.hash?.token === "EOF" || /got 'EOF'|Expecting/.test(error?.message || "");
+}
+
+function annotateLibrary(script, options = {}) {
+  try {
+    return annotate(script, options);
+  } catch (error) {
+    if (!isEofParseError(error)) throw error;
+    return annotate(`${script}\n()`, options);
+  }
+}
+
 function collectReachable(mainName, rels, allCodes) {
   const reachableRels = new Set();
   const reachableCodes = new Set();
@@ -140,7 +207,10 @@ function compileObject(script, options = {}) {
   const annotated = annotate(script, options);
   const allCodes = codes.dump();
   const serialized = serializeAnnotated(annotated);
-  const meta = buildMeta(annotated, options.source || null);
+  const meta = mergeMetaEntries(
+    importedLibraryMeta(options.libraries),
+    buildMeta(annotated, options.source || null)
+  );
 
   // Prune to reachable from main
   const { reachableRels, reachableCodes } = collectReachable("__main__", serialized.rels, allCodes);
@@ -189,9 +259,12 @@ function rewriteRefsToCanonical(exp, relAlias) {
 }
 
 function compileLibrary(script, options = {}) {
-  const annotated = annotate(script, options);
+  const annotated = annotateLibrary(script, options);
   const serialized = serializeAnnotated(annotated);
-  const meta = buildMeta(annotated, options.source || null);
+  const meta = mergeMetaEntries(
+    importedLibraryMeta(options.libraries),
+    buildMeta(annotated, options.source || null)
+  );
   const relAlias = serialized.relAlias || {};
 
   // Key rels by canonical hash, rewrite internal refs to canonical hashes
@@ -482,6 +555,83 @@ function decompileObjectBuffer(buffer) {
   return decompileObject(decodeObject(buffer));
 }
 
+function hashBody(hash) {
+  return hash.startsWith("@") ? hash.slice(1) : hash;
+}
+
+function compareAliasEntries(left, right) {
+  return (
+    left.typeOrder - right.typeOrder ||
+    left.name.localeCompare(right.name) ||
+    compareMaybeTimestamp(left.compiledAt, right.compiledAt) ||
+    left.hash.localeCompare(right.hash) ||
+    left.source.localeCompare(right.source)
+  );
+}
+
+function compareMaybeTimestamp(left, right) {
+  if (left == null && right == null) return 0;
+  if (left == null) return 1;
+  if (right == null) return -1;
+  return left.localeCompare(right);
+}
+
+function originComment(origin) {
+  return JSON.stringify({
+    ...(origin.source == null ? {} : { source: origin.source }),
+    ...(origin.compiledAt == null ? {} : { compiledAt: origin.compiledAt })
+  });
+}
+
+function extractAliasesFromObject(object) {
+  const hydrated = isHydratedObject(object) ? object : hydrateObject(object);
+  const entries = [];
+
+  for (const [hash, entry] of Object.entries(hydrated.meta || {})) {
+    const type = entry?.type;
+    if (type !== "code" && type !== "rel") continue;
+    const typeOrder = type === "code" ? 0 : 1;
+    for (const origin of entry.origins || []) {
+      if (!origin?.name || !isSourceName(origin.name)) continue;
+      entries.push({
+        type,
+        typeOrder,
+        hash,
+        name: origin.name,
+        source: origin.source || "",
+        compiledAt: origin.compiledAt,
+        comment: originComment(origin)
+      });
+    }
+  }
+
+  entries.sort(compareAliasEntries);
+
+  const activeEntries = new Set();
+  for (let i = 0; i < entries.length; i++) {
+    const next = entries[i + 1];
+    if (!next || next.type !== entries[i].type || next.name !== entries[i].name) {
+      activeEntries.add(entries[i]);
+    }
+  }
+
+  const lines = [];
+  let lastType = null;
+  for (const entry of entries) {
+    if (lastType != null && lastType !== entry.type) lines.push("");
+    lastType = entry.type;
+    const prefix = entry.type === "code" ? "$ " : "";
+    const line = `${prefix}${entry.name} = @${hashBody(entry.hash)}; # ${entry.comment}`;
+    lines.push(activeEntries.has(entry) ? line : `# ${line}`);
+  }
+
+  return `${lines.join("\n")}${lines.length === 0 ? "" : "\n"}`;
+}
+
+function extractAliasesFromObjectBuffer(buffer) {
+  return extractAliasesFromObject(decodeObject(buffer));
+}
+
 export {
   compileObject,
   compileObjectBuffer,
@@ -496,7 +646,9 @@ export {
   runObject,
   objectToFunction,
   decompileObject,
-  decompileObjectBuffer
+  decompileObjectBuffer,
+  extractAliasesFromObject,
+  extractAliasesFromObjectBuffer
 };
 
 export default {
@@ -513,5 +665,7 @@ export default {
   runObject,
   objectToFunction,
   decompileObject,
-  decompileObjectBuffer
+  decompileObjectBuffer,
+  extractAliasesFromObject,
+  extractAliasesFromObjectBuffer
 };

package/objects/README.md

@@ -31,6 +31,16 @@ Decompiles a `.ko` or `.klib` back into human-readable k source.
 ./objects/decompile.mjs [object-file [k-file]]
 ```
 
+### extract-aliases.mjs
+
+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
+./objects/extract-aliases.mjs [object-file [k-file]]
+```
+
 ## Further reading
 
 - [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) — object file format and pattern encoding

package/objects/compile-lib.mjs

@@ -4,8 +4,27 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { compileLibraryBuffer, decodeObject, loadLibrary } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ lib-file ] ]`);
+function helpText() {
+  return [
+    "Compile a k source file into a .klib library object.",
+    "",
+    `Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ lib-file ] ]`,
+    "",
+    "Arguments:",
+    "  k-file    Source .k file to compile. Reads UTF-8 source from stdin when omitted.",
+    "  lib-file  Output .klib path. Writes binary library data to stdout when omitted.",
+    "",
+    "Options:",
+    "  --lib file   Load a .klib dependency before compiling. May be repeated.",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} --lib core.klib library.k library.klib`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function readStdinText() {
@@ -18,6 +37,11 @@ async function readStdinText() {
 
 try {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   const libraries = [];
   while (args.length > 0 && args[0] === "--lib") {
     args.shift();

package/objects/compile.mjs

@@ -4,8 +4,27 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { compileObjectBuffer, decodeObject, loadLibrary } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ object-file ] ]`);
+function helpText() {
+  return [
+    "Compile a k source file into an executable .ko object.",
+    "",
+    `Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ object-file ] ]`,
+    "",
+    "Arguments:",
+    "  k-file       Source .k file to compile. Reads UTF-8 source from stdin when omitted.",
+    "  object-file  Output .ko path. Writes binary object data to stdout when omitted.",
+    "",
+    "Options:",
+    "  --lib file   Load a .klib dependency before compiling. May be repeated.",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} --lib core.klib program.k program.ko`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function readStdinText() {
@@ -18,6 +37,11 @@ async function readStdinText() {
 
 try {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   const libraries = [];
   while (args.length > 0 && args[0] === "--lib") {
     args.shift();

package/objects/decompile.mjs

@@ -4,8 +4,26 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { decompileObjectBuffer } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ object-file [ k-file ] ]`);
+function helpText() {
+  return [
+    "Decompile a .ko or .klib object into readable k source.",
+    "",
+    `Usage: ${argv[1]} [ object-file [ k-file ] ]`,
+    "",
+    "Arguments:",
+    "  object-file  Input .ko or .klib path. Reads binary object data from stdin when omitted.",
+    "  k-file       Output .k path. Writes source to stdout when omitted.",
+    "",
+    "Options:",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} program.ko program.decompiled.k`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function readStdinBuffer() {
@@ -18,6 +36,11 @@ async function readStdinBuffer() {
 
 try {
   const [, , objectPath, outputPath] = argv;
+  if (objectPath === "-h" || objectPath === "--help") {
+    usage(console.log);
+    exit(0);
+  }
+
   const objectBuffer = objectPath == null ? await readStdinBuffer() : fs.readFileSync(objectPath);
   const source = decompileObjectBuffer(objectBuffer);
   if (outputPath == null) {