@fraczak/k 6.0.2 → 6.0.3

package/DOCS/OBJECT_FILE_AND_PATTERN.md

@@ -29,6 +29,10 @@ $ pattern-node = <
 $ pattern = < {} nil, { pattern-node car, pattern cdr } cons >;
 ```
 
+This does not mean `core.k` is pre-loaded into ordinary program execution. The
+special role of `core.k` here is that the wire codec relies on the canonical
+`$pattern` definition from that file.
+
 In this schema:
 
 - the first pattern-list element is node `0`, the root,

package/DOCS/REPL.md

@@ -44,7 +44,7 @@ complete.
 | `:C name` | Show canonical code definition |
 | `:codes` | List type aliases |
 | `:rels` | List relation aliases |
-| `:load file` | Load `.k` source or `.klib` into the current state |
+| `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
 | `:klib file` | Export current state as a `.klib` library |
 | `:ko file expr` | Export a `.ko` executable with `expr` as main |
 | `:val` | Print current value and JSON form |
@@ -134,16 +134,17 @@ Type aliases also complete in `$name` position inside raw k input.
 
 ## Loading
 
-### `:load file.k`
+### `:load [--no-alias] file.k`
 
 Compiles the source in the current library context, merges the resulting codes
 and relations into the session, and recovers aliases from user-defined names in
-the file.
+the file unless `--no-alias` is used.
 
-### `:load file.klib`
+### `:load [--no-alias] file.klib`
 
 Decodes the library file and merges its codes, relations, and metadata into the
-session.
+session. Aliases are recovered from library metadata unless `--no-alias` is
+used.
 
 ## Export
 

package/README.md

@@ -34,6 +34,7 @@ k-repl               # start the interactive REPL  (or: node repl2.mjs)
 | `k-pattern` | `patterns/from-k.mjs` | Extract the canonical root pattern from a k script |
 | `k-compile-object` | `objects/compile.mjs` | Compile a `.k` source to an executable `.ko` object |
 | `k-decompile-object` | `objects/decompile.mjs` | Decompile a `.ko` or `.klib` file back to k source |
+| `k-extract-aliases` | `objects/extract-aliases.mjs` | Extract `.klib` metadata aliases as k source |
 
 ---
 
@@ -161,7 +162,7 @@ Start with `k-repl` (or `node repl2.mjs`). The prompt is `> `.
 | `:d name` | Show relation definition |
 | `:C name` | Show canonical code definition |
 | `:codes` / `:rels` | List type or relation aliases |
-| `:load file` | Load `.k` or `.klib` |
+| `:load [--no-alias] file` | Load `.k` or `.klib`; aliases are loaded unless `--no-alias` is used |
 | `:klib file` | Export current state as `.klib` |
 | `:ko file expr` | Export executable `.ko` |
 | `:val` | Print current value |
@@ -239,8 +240,9 @@ console.log(annotated.compileStats);  // per-SCC strategy and iteration counts
 
 ## Standard Library — `core.k`
 
-`core.k` is the k standard core library. It is loaded automatically by the codec pipeline and
-is available as a reference for any k program that needs canonical types.
+`core.k` is the k standard core library. It is **not** pre-loaded into ordinary k
+programs or relation evaluation. Instead, it is the reference source for a few
+canonical definitions that the binary codec depends on, especially `$pattern`.
 It defines four things, in order:
 
 ### §1 & §2 — `$bits` and arithmetic
@@ -277,7 +279,8 @@ $ pattern       = < {} nil, { pattern-node car, pattern cdr } cons >;
 The singleton pattern of `$pattern` itself is the fixed framing constant for the wire format:
 every k binary stream starts with a `$pattern` encoded under that constant,
 followed by the value encoded under the pattern just decoded.
-This is why `core.k` ends with a bare `$pattern` expression — it pins that canonical hash.
+This is why `core.k` ends with a bare `$pattern` expression — it pins that
+canonical code/hash used by the wire codec for the leading pattern payload.
 
 ---
 
@@ -310,6 +313,7 @@ Typical CLI usage:
 ```bash
 ./objects/compile-lib.mjs Examples/ieee.k ieee.klib
 ./objects/compile.mjs --lib ieee.klib Examples/nat.k nat.ko
+./objects/extract-aliases.mjs ieee.klib aliases.k
 ./objects/decompile.mjs nat.ko
 ```
 

package/UU/ta.k

@@ -0,0 +1 @@
+$bit 

package/codecs/README.md

@@ -10,6 +10,10 @@ The default concrete format is now the binary encoding of a `$pattern` value,
 using the `$pattern` type from [`../core.k`](../core.k), immediately followed by
 the binary encoding of the value under that decoded pattern.
 
+`core.k` is not loaded automatically as a library when user programs run. The
+codec only depends on the canonical `$pattern` definition from that file as the
+schema for the leading pattern value.
+
 There is no separate JSON container format.
 
 ## Objectives

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) {

package/objects/extract-aliases.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { extractAliasesFromObjectBuffer } from "../object.mjs";
+
+function helpText() {
+  return [
+    "Extract metadata aliases from a .ko or .klib as a valid k source snippet.",
+    "",
+    `Usage: ${argv[1]} [ object-file [ k-file ] ]`,
+    "",
+    "Output is grouped by metadata type (code, then rel), then sorted by alias",
+    "name and compiledAt. Earlier definitions of the same alias are commented",
+    "out so only the latest one remains active.",
+    "",
+    "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]} core.klib aliases.k`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
+}
+
+async function readStdinBuffer() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+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 = extractAliasesFromObjectBuffer(objectBuffer);
+  if (outputPath == null) {
+    stdout.write(source);
+  } else {
+    fs.writeFileSync(outputPath, source);
+  }
+} catch (error) {
+  console.error(error);
+  usage();
+  exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.0.2",
+    "version": "6.0.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",
     "scripts": {
@@ -18,6 +18,7 @@
         "k": "./k.mjs",
         "k-compile-object": "./objects/compile.mjs",
         "k-decompile-object": "./objects/decompile.mjs",
+        "k-extract-aliases": "./objects/extract-aliases.mjs",
         "k-parse": "./codecs/k-parse.mjs",
         "k-pattern": "./patterns/from-k.mjs",
         "k-print": "./codecs/k-print.mjs",

package/repl2.mjs

@@ -146,21 +146,27 @@ function annotateWithOptionalIdentity(source, options) {
 function mergeMeta(state, meta = {}) {
   for (const [hash, entry] of Object.entries(meta)) {
     const origins = entry?.origins || [];
-    if (!state.meta[hash]) state.meta[hash] = { origins: [] };
-    state.meta[hash].origins.push(...origins);
+    const entryType = entry?.type;
+    if (!state.meta[hash]) state.meta[hash] = { type: entryType, origins: [] };
+    if (state.meta[hash].type == null && entryType != null) state.meta[hash].type = entryType;
+    state.meta[hash].origins.push(...origins.map(({ source, name, compiledAt }) => ({
+      source,
+      name,
+      ...(compiledAt == null ? {} : { compiledAt })
+    })));
   }
 }
 
-function rememberOrigin(state, hash, name, kind, source = "<repl>") {
-  if (!state.meta[hash]) state.meta[hash] = { origins: [] };
+function rememberOrigin(state, hash, name, type, source = "<repl>") {
+  if (!state.meta[hash]) state.meta[hash] = { type, origins: [] };
+  if (state.meta[hash].type == null) state.meta[hash].type = type;
   const exists = state.meta[hash].origins.some((origin) =>
-    origin.name === name && origin.kind === kind && origin.source === source
+    origin.name === name && state.meta[hash].type === type && origin.source === source
   );
   if (!exists) {
     state.meta[hash].origins.push({
       source,
       name,
-      kind,
       compiledAt: new Date().toISOString()
     });
   }
@@ -170,40 +176,47 @@ function recoverAliasesFromMeta(state, lib) {
   for (const [hash, entry] of Object.entries(lib.meta || {})) {
     for (const origin of entry?.origins || []) {
       if (!origin?.name || !NAME_RE.test(origin.name)) continue;
-      if (origin.kind === "code" || (!origin.kind && hash in state.codes && !(hash in state.rels))) {
+      const type = entry?.type;
+      if (type === "code" || (!type && hash in state.codes && !(hash in state.rels))) {
         state.typeAliases[origin.name] = hash;
-      } else if (origin.kind === "rel" || hash in state.rels) {
+      } else if (type === "rel" || hash in state.rels) {
         state.relAliases[origin.name] = hash;
       }
     }
   }
 }
 
-function mergeLibrary(state, lib, source = "<load>") {
+function mergeLibrary(state, lib, source = "<load>", options = {}) {
+  const loadAliases = options.loadAliases ?? true;
   state.codes = { ...state.codes, ...(lib.codes || {}) };
   state.rels = { ...state.rels, ...(lib.rels || {}) };
-  state.relAliases = { ...state.relAliases, ...(lib.relAlias || {}) };
   mergeMeta(state, lib.meta);
 
-  for (const [name, hash] of Object.entries(lib.relAlias || {})) {
-    if (name !== "__main__" && NAME_RE.test(name) && hash in state.rels) {
-      state.relAliases[name] = hash;
-      rememberOrigin(state, hash, name, "rel", source);
+  if (loadAliases) {
+    state.relAliases = { ...state.relAliases, ...(lib.relAlias || {}) };
+    for (const [name, hash] of Object.entries(lib.relAlias || {})) {
+      if (name !== "__main__" && NAME_RE.test(name) && hash in state.rels) {
+        state.relAliases[name] = hash;
+        rememberOrigin(state, hash, name, "rel", source);
+      }
     }
+    recoverAliasesFromMeta(state, lib);
   }
-  recoverAliasesFromMeta(state, lib);
   restoreCodes(state);
 }
 
 function savedLibrary(state) {
   const meta = cloneJSON(state.meta);
+  const now = new Date().toISOString();
   for (const [name, hash] of Object.entries(state.typeAliases)) {
-    if (!meta[hash]) meta[hash] = { origins: [] };
-    meta[hash].origins.push({ source: "<repl>", name, kind: "code" });
+    if (!meta[hash]) meta[hash] = { type: "code", origins: [] };
+    if (meta[hash].type == null) meta[hash].type = "code";
+    meta[hash].origins.push({ source: "<repl>", name, compiledAt: now });
   }
   for (const [name, hash] of Object.entries(state.relAliases)) {
-    if (!meta[hash]) meta[hash] = { origins: [] };
-    meta[hash].origins.push({ source: "<repl>", name, kind: "rel" });
+    if (!meta[hash]) meta[hash] = { type: "rel", origins: [] };
+    if (meta[hash].type == null) meta[hash].type = "rel";
+    meta[hash].origins.push({ source: "<repl>", name, compiledAt: now });
   }
   return {
     format: "k-object",
@@ -285,8 +298,8 @@ function libraryOriginsFromSource(source, fullSource, lib, options) {
   for (const name of typeNames) {
     const hash = annotated.representatives?.[name];
     if (!hash) continue;
-    if (!meta[hash]) meta[hash] = { origins: [] };
-    meta[hash].origins.push({ source: options.source || null, name, kind: "code", compiledAt: now });
+    if (!meta[hash]) meta[hash] = { type: "code", origins: [] };
+    meta[hash].origins.push({ source: options.source || null, name, compiledAt: now });
   }
 
   const relAlias = Object.fromEntries(
@@ -296,8 +309,8 @@ function libraryOriginsFromSource(source, fullSource, lib, options) {
   );
 
   for (const [name, hash] of Object.entries(relAlias)) {
-    if (!meta[hash]) meta[hash] = { origins: [] };
-    meta[hash].origins.push({ source: options.source || null, name, kind: "rel", compiledAt: now });
+    if (!meta[hash]) meta[hash] = { type: "rel", origins: [] };
+    meta[hash].origins.push({ source: options.source || null, name, compiledAt: now });
   }
 
   return { relAlias, meta };
@@ -401,6 +414,26 @@ function commandArgIndex(arg) {
   return trimmed.split(/\s+/).length - 1;
 }
 
+function loadPathCompletionStart(argStart, arg) {
+  const leadingWhitespace = arg.length - arg.trimStart().length;
+  const trimmed = arg.trimStart();
+  if (trimmed === "" || !trimmed.startsWith("--no-alias")) {
+    if (commandArgIndex(arg) !== 0) return null;
+    return argStart + completionTokenStart(arg);
+  }
+  if (!"--no-alias".startsWith(trimmed) && !trimmed.startsWith("--no-alias ")) {
+    return null;
+  }
+  if (trimmed !== "--no-alias" && !trimmed.startsWith("--no-alias ")) {
+    return null;
+  }
+  if (trimmed === "--no-alias") return null;
+  const restStart = leadingWhitespace + "--no-alias".length;
+  const rest = arg.slice(restStart);
+  const restLeadingWhitespace = rest.length - rest.trimStart().length;
+  return argStart + restStart + restLeadingWhitespace + completionTokenStart(rest.trimStart());
+}
+
 function completeCommandArgument(line, state) {
   const body = line.slice(1);
   const firstSpace = body.search(/\s/);
@@ -410,8 +443,13 @@ function completeCommandArgument(line, state) {
   const argStart = 1 + firstSpace + 1;
   const arg = line.slice(argStart);
 
-  if (PATH_COMMANDS.has(command) && commandArgIndex(arg) === 0) {
-    const tokenStart = argStart + completionTokenStart(arg);
+  if (PATH_COMMANDS.has(command)) {
+    const tokenStart = command === "load"
+      ? loadPathCompletionStart(argStart, arg)
+      : commandArgIndex(arg) === 0
+        ? argStart + completionTokenStart(arg)
+        : null;
+    if (tokenStart == null) return [[], line];
     return completePath(line, tokenStart);
   }
 
@@ -460,6 +498,20 @@ function isEofParseError(error) {
   return /got 'EOF'|Unexpected end of input/.test(error.message || "");
 }
 
+function parseLoadArgs(arg, usagePrefix = ":") {
+  const trimmed = arg.trim();
+  if (!trimmed) throw new Error(`${usagePrefix}load requires a file path`);
+  if (trimmed === "--no-alias") {
+    throw new Error(`${usagePrefix}load --no-alias requires a file path`);
+  }
+  if (trimmed.startsWith("--no-alias ")) {
+    const path = trimmed.slice("--no-alias".length).trim();
+    if (!path) throw new Error(`${usagePrefix}load --no-alias requires a file path`);
+    return { path, loadAliases: false };
+  }
+  return { path: arg.trim(), loadAliases: true };
+}
+
 function lineForContinuation(line) {
   return line.replace(/\\\s*$/, "");
 }
@@ -703,28 +755,28 @@ async function evaluateCommand(line, state) {
       return [`saved ${path} (${main})`];
     }
     case "load": {
-      if (!arg) throw new Error(`${usagePrefix}load requires a file path`);
-      if (arg.endsWith(".klib")) {
-        const lib = loadLibrary(decodeLibrary(fs.readFileSync(arg)));
-        mergeLibrary(state, lib, arg);
+      const { path: loadPath, loadAliases } = parseLoadArgs(arg, usagePrefix);
+      if (loadPath.endsWith(".klib")) {
+        const lib = loadLibrary(decodeLibrary(fs.readFileSync(loadPath)));
+        mergeLibrary(state, lib, loadPath, { loadAliases });
       } else {
         restoreCodes(state);
-        const source = fs.readFileSync(arg, "utf8");
+        const source = fs.readFileSync(loadPath, "utf8");
         const preamble = aliasPreamble(state);
         const fullSource = [preamble, source].filter(Boolean).join("\n");
         const options = {
-          source: arg,
+          source: loadPath,
           libraries: [stateLibrary(state)]
         };
         try {
           const lib = compileWithOptionalIdentity(fullSource, options);
           const { relAlias, meta } = libraryOriginsFromSource(source, fullSource, lib, options);
-          mergeLibrary(state, { ...lib, relAlias, meta }, arg);
+          mergeLibrary(state, { ...lib, relAlias, meta }, loadPath, { loadAliases });
         } catch (error) {
           throw remapError(error, preambleLineCount(preamble));
         }
       }
-      return [`loaded ${arg}`];
+      return [`loaded ${loadPath}`];
     }
     case "t": {
       if (!arg) throw new Error(`${usagePrefix}t requires a relation name`);
@@ -759,7 +811,8 @@ function helpText() {
     ":type name           show type definition",
     ":codes               list type aliases",
     ":rels                list relation aliases",
-    ":load file           load .k source or .klib",
+    ":load [--no-alias] file",
+    "                     load .k source or .klib",
     ":klib file           export state as a library",
     ":ko file expr        export executable .ko using expr as main",
     ":val                 print current value",

package/test-k-object.mjs

@@ -6,7 +6,14 @@ import { decodeWire, encodeToWire, CORE_PATTERN_PROPERTY_LIST } from "./codecs/r
 import { Product, Variant } from "./Value.mjs";
 import { exportPatternGraph } from "./codecs/runtime/codec.mjs";
 import { patternToPropertyList } from "./codecs/runtime/pattern-json.mjs";
-import { compileObjectBuffer, decodeObject, objectToFunction, decompileObjectBuffer } from "./object.mjs";
+import {
+  compileObjectBuffer,
+  compileLibraryBuffer,
+  decodeObject,
+  objectToFunction,
+  decompileObjectBuffer,
+  extractAliasesFromObject
+} from "./object.mjs";
 
 const value = parseValue("{a:{b:x,c:{}}}");
 const wire = encodeToWire(value, null);
@@ -71,4 +78,73 @@ const sccSource = decompileObjectBuffer(compileObjectBuffer("c = {}; b = c |x; a
 assert.match(sccSource, /----- rels -----\nPQgV = .+\n\naQAD = .+\n\nN9UH = /s);
 assert.deepEqual(k.compile(sccSource)(new Product({})).toJSON(), { y: "x" });
 
+const library = decodeObject(compileLibraryBuffer("$ nat = <{} zero, nat succ>;\nsucc = |succ;\n", { source: "defs-only.k" }));
+assert.equal(library.main, null);
+assert(Object.values(library.meta).some(({ type, origins }) =>
+  type === "code" &&
+  origins.some((origin) =>
+    origin.source === "defs-only.k" &&
+    origin.name === "nat" &&
+    JSON.stringify(Object.keys(origin).sort()) === JSON.stringify(["compiledAt", "name", "source"]) &&
+    typeof origin.compiledAt === "string"
+  )
+));
+assert(Object.values(library.meta).some(({ type, origins }) =>
+  type === "rel" &&
+  origins.some((origin) =>
+    origin.source === "defs-only.k" &&
+    origin.name === "succ" &&
+    JSON.stringify(Object.keys(origin).sort()) === JSON.stringify(["compiledAt", "name", "source"]) &&
+    typeof origin.compiledAt === "string"
+  )
+));
+
+const derivedLibrary = decodeObject(compileLibraryBuffer("other = |other;\n", {
+  source: "derived.k",
+  libraries: [library]
+}));
+const derivedAliases = extractAliasesFromObject(derivedLibrary);
+assert.match(derivedAliases, /^\$ nat = @/m);
+assert.match(derivedAliases, /^succ = @/m);
+assert.match(derivedAliases, /^other = @/m);
+assert(derivedAliases.indexOf("$ nat = @") < derivedAliases.indexOf("other = @"));
+assert(derivedAliases.indexOf("other = @") < derivedAliases.indexOf("succ = @"));
+
+const aliasSnippet = extractAliasesFromObject({
+  format: "k-object",
+  version: 2,
+  codes: {},
+  rels: {},
+  meta: {
+    "@relB": {
+      type: "rel",
+      origins: [
+        { source: "new.k", name: "times", compiledAt: "2026-04-12T06:08:10.390Z" },
+        { source: "core.k", name: "times", compiledAt: "2026-03-09T06:17:23.390Z" },
+        { source: "other.k", name: "plus", compiledAt: "2026-05-17T06:10:23.390Z" }
+      ]
+    },
+    "@codeB": {
+      type: "code",
+      origins: [
+        { source: "z.k", name: "edges", compiledAt: "2026-03-09T06:17:23.390Z" }
+      ]
+    },
+    "@codeA": {
+      type: "code",
+      origins: [
+        { source: "a.k", name: "bits", compiledAt: "2026-05-17T06:10:23.390Z" }
+      ]
+    }
+  },
+  main: null
+});
+assert.deepEqual(aliasSnippet.split("\n").filter(Boolean), [
+  '$ bits = @codeA; # {"source":"a.k","compiledAt":"2026-05-17T06:10:23.390Z"}',
+  '$ edges = @codeB; # {"source":"z.k","compiledAt":"2026-03-09T06:17:23.390Z"}',
+  'plus = @relB; # {"source":"other.k","compiledAt":"2026-05-17T06:10:23.390Z"}',
+  '# times = @relB; # {"source":"core.k","compiledAt":"2026-03-09T06:17:23.390Z"}',
+  'times = @relB; # {"source":"new.k","compiledAt":"2026-04-12T06:08:10.390Z"}'
+]);
+
 console.log("OK");

package/test-repl2.mjs

@@ -88,6 +88,8 @@ assert.equal(output[0], `saved ${libPath}`);
 
 completions = completeInput(`:load ${tmpDir}/ses`, state)[0];
 assert(completions.includes(`:load ${libPath}`));
+completions = completeInput(`:load --no-alias ${tmpDir}/ses`, state)[0];
+assert(completions.includes(`:load --no-alias ${libPath}`));
 
 output = await evaluateInput(`:ko ${koPath} succ`, state);
 assert.equal(output[0], `saved ${koPath} (succ)`);
@@ -125,6 +127,14 @@ assert.match(output[0], /^succ = @/m);
 output = await evaluateInput("succ", reloaded);
 assert.equal(output[0], "{}|succ ?<{} succ, ...>");
 
+const noAliasReloaded = createState();
+output = await evaluateInput(`:load --no-alias ${libPath}`, noAliasReloaded);
+assert.equal(output[0], `loaded ${libPath}`);
+output = await evaluateInput(":codes", noAliasReloaded);
+assert.equal(output[0], "(none)");
+output = await evaluateInput(":rels", noAliasReloaded);
+assert.equal(output[0], "(none)");
+
 const shorthand = createState();
 output = await evaluateInput("$ nat = <{} zero, nat succ>\n; succ = |succ\n;", shorthand);
 assert.deepEqual(output, []);