@fraczak/k 6.8.0 → 6.9.0

package/codecs/README.md

@@ -79,6 +79,8 @@ notation for k values. That notation is documented in
 [`../DOCS/TEXTUAL_VALUES.md`](../DOCS/TEXTUAL_VALUES.md). It is a readable
 notation for k values, not a separate JSON container format.
 
+For the codec architecture and specification, see
+[`../DOCS/CODEC_ARCHITECTURE.md`](../DOCS/CODEC_ARCHITECTURE.md).
 For the contributor-facing guide to writing a new external codec module, see
 [`../DOCS/CODECS.md`](../DOCS/CODECS.md).
 
@@ -238,6 +240,10 @@ The new codec work is split into layers:
 
 ## Files
 
+- [`../DOCS/CODEC_ARCHITECTURE.md`](../DOCS/CODEC_ARCHITECTURE.md):
+  comprehensive architecture specification for k codecs.
+- [`../DOCS/CODECS.md`](../DOCS/CODECS.md):
+  practical guide to writing, running, and testing codecs.
 - [`POLYMORPHIC_BINARY_FORMAT.md`](./POLYMORPHIC_BINARY_FORMAT.md):
   main design document for the new pattern-plus-prefix-tree codec.
 - [`BINARY_FORMAT.md`](./BINARY_FORMAT.md):
@@ -247,3 +253,4 @@ The new codec work is split into layers:
 
 The active command-line pipeline emits and consumes the self-hosted binary
 pattern+value stream.
+

package/codecs/ieee.mjs

@@ -1,20 +1,28 @@
 #!/usr/bin/env node
 
-import { stdin, stdout, argv, exit } from "node:process";
-import { Value, isProduct, isVariant } from "../Value.mjs";
-import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
-import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
-import { FLOAT64_PATTERN } from "./runtime/ieee-pattern.mjs";
+import { Value, isProduct, isVariant, withPattern, patternFromFilter, runCodecCLI } from "./runtime/codec-sdk.mjs";
+
+export const doc = `
+IEEE 754 64-bit float codec.
+
+Parses decimal floats, Infinity, -Infinity, NaN to 64-bit IEEE products.
+`;
+
+const FLOAT64_PATTERN = patternFromFilter(`
+$bit  = < {} 0, {} 1 >;
+$sign = < {} "+", {} "-" >;
+$exp11  = {bit 0, bit 1, bit 2, bit 3, bit 4, bit 5, bit 6, bit 7, bit 8, bit 9, bit 10};
+$frac52 = {bit 0, bit 1, bit 2, bit 3, bit 4, bit 5, bit 6, bit 7, bit 8, bit 9,
+           bit 10, bit 11, bit 12, bit 13, bit 14, bit 15, bit 16, bit 17, bit 18, bit 19,
+           bit 20, bit 21, bit 22, bit 23, bit 24, bit 25, bit 26, bit 27, bit 28, bit 29,
+           bit 30, bit 31, bit 32, bit 33, bit 34, bit 35, bit 36, bit 37, bit 38, bit 39,
+           bit 40, bit 41, bit 42, bit 43, bit 44, bit 45, bit 46, bit 47, bit 48, bit 49,
+           bit 50, bit 51};
+$float64 = {sign sign, exp11 exponent, frac52 fraction};
+?$float64
+`);
+
 const UNIT = Value.product({});
-const name = "ieee";
-const patterns = [FLOAT64_PATTERN];
-
-function usage(stream = console.error) {
-  stream(`Usage: ${argv[1]} --parse | --print`);
-  stream("  --parse      Read a float literal from stdin, write binary pattern+value stream.");
-  stream("  --print      Read binary pattern+value stream from stdin, write a float literal.");
-  stream("  -h, --help   Show this help.");
-}
 
 function bitValue(bit) {
   return Value.variant(bit === 0 ? "0" : "1", UNIT);
@@ -29,10 +37,11 @@ function bitsProduct(width, value) {
   return Value.product(product);
 }
 
-function encodeNumberToValue(number) {
-  const buf = Buffer.alloc(8);
-  buf.writeDoubleBE(number, 0);
-  const bits = buf.readBigUInt64BE(0);
+const floatView = new DataView(new ArrayBuffer(8));
+
+export function encodeNumberToValue(number) {
+  floatView.setFloat64(0, number, false);
+  const bits = floatView.getBigUint64(0, false);
   const sign = Number((bits >> 63n) & 1n);
   const exponent = Number((bits >> 52n) & 0x7ffn);
   const fraction = bits & ((1n << 52n) - 1n);
@@ -71,7 +80,7 @@ function parseBitsProduct(value, maxBit, where) {
   return n;
 }
 
-function decodeValueToNumber(value) {
+export function decodeValueToNumber(value) {
   const product = requireProduct(value, "float64");
   const sign = requireVariant(product.sign, "float64.sign");
   if (sign.tag !== "+" && sign.tag !== "-") {
@@ -85,9 +94,8 @@ function decodeValueToNumber(value) {
     (exponent << 52n) |
     fraction;
 
-  const buf = Buffer.alloc(8);
-  buf.writeBigUInt64BE(bits, 0);
-  return buf.readDoubleBE(0);
+  floatView.setBigUint64(0, bits, false);
+  return floatView.getFloat64(0, false);
 }
 
 function parseFloatText(text) {
@@ -98,68 +106,35 @@ function parseFloatText(text) {
 
   if (/^[+-]?nan$/i.test(trimmed)) return NaN;
   if (/^[+]?inf(inity)?$/i.test(trimmed)) return Infinity;
-  if (/^-inf(inity)?$/i.test(trimmed)) return -Infinity;
+  if (/^[-](inf|infinity)$/i.test(trimmed)) return -Infinity;
 
-  const value = Number(trimmed);
-  if (Number.isNaN(value)) {
-    throw new Error(`Invalid floating-point literal: ${JSON.stringify(trimmed)}`);
+  const n = Number(trimmed);
+  if (Number.isNaN(n)) {
+    throw new Error(`Invalid float literal ${JSON.stringify(trimmed)}`);
   }
-  return value;
+  return n;
 }
 
-function printFloatText(number) {
-  if (Number.isNaN(number)) return "NaN";
-  if (number === Infinity) return "Infinity";
-  if (number === -Infinity) return "-Infinity";
-  if (Object.is(number, -0)) return "-0";
-  return String(number);
+function printFloatText(n) {
+  if (Number.isNaN(n)) return "NaN";
+  if (n === Infinity) return "Infinity";
+  if (n === -Infinity) return "-Infinity";
+  if (Object.is(n, -0)) return "-0";
+  return String(n);
 }
 
-function parse(text) {
-  return encodeNumberToValue(parseFloatText(text));
+export function parse(text) {
+  const n = parseFloatText(text);
+  const value = encodeNumberToValue(n);
+  return withPattern(value, FLOAT64_PATTERN);
 }
 
-function print(value) {
+export function print(value) {
   return printFloatText(decodeValueToNumber(value));
 }
 
-function readAll(stream) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-async function main() {
-  const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    usage(console.log);
-    exit(0);
-  }
-
-  if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    usage();
-    exit(1);
-  }
-
-  const buf = await readAll(stdin);
-
-  if (args[0] === "--parse") {
-    const value = encodeNumberToValue(parseFloatText(buf.toString("utf8")));
-    stdout.write(encodeToWire(value, FLOAT64_PATTERN));
-  } else {
-    const { value } = decodeWire(buf);
-    stdout.write(`${printFloatText(decodeValueToNumber(value))}\n`);
-  }
-}
-
-if (isMainEntrypoint(import.meta.url, argv[1])) {
-  main().catch((error) => {
-    console.error(error.message || String(error));
-    exit(1);
-  });
-}
+runCodecCLI(import.meta.url, { parse, print, doc });
 
-export { FLOAT64_PATTERN, name, patterns, parse, print };
+export {
+  FLOAT64_PATTERN
+};

package/codecs/int.mjs

@@ -1,48 +1,31 @@
 #!/usr/bin/env node
 
 /**
- * int: parse/print integers in the k 'int' binary pattern+value stream.
+ * int: parse/print integers and integer lists as enveloped k values.
  *
  * $ bits = < {} _, bits 0, bits 1 >;
  * $ int  = < bits '+', bits '-' >;
- *
- * Bits are stored MSB-outermost (remove_leading_zeros strips outermost 0s).
- *
- * Usage:
- *   echo "-21"  | int.mjs --parse   # decimal → binary pattern+value stream
- *   <wire>      | int.mjs --print   # binary pattern+value stream → decimal
+ * list   = < {} nil, {int car, list cdr} cons >;
  */
 
-import { stdin, stdout, argv, exit } from "node:process";
-import { Value, isVariant } from "../Value.mjs";
-import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
-import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
+import { Value, isProduct, isVariant, withPattern, patternFromFilter, runCodecCLI } from "./runtime/codec-sdk.mjs";
 
-function usage(stream = console.error) {
-  stream(`Usage: ${argv[1]} --parse | --print`);
-  stream("  --parse      Read a decimal integer from stdin, write binary pattern+value stream.");
-  stream("  --print      Read binary pattern+value stream from stdin, write decimal integer.");
-  stream("  -h, --help   Show this help.");
-}
+export const doc = `
+Decimal integers and integer lists.
+
+Syntax:
+  Decimal integer (e.g. 42, -15) or bracketed integer list (e.g. [0, 1, 2], []).
+`;
 
 // Closed pattern for $ int = < bits '+', bits '-' >
 // with $ bits = < {} _, bits 0, bits 1 >
-const INT_PATTERN = [
-  ["closed-union", [["+", 1], ["-", 1]]],
-  ["closed-union", [["0", 1], ["1", 1], ["_", 2]]],
-  ["closed-product", []]
-];
-const name = "int";
-const patterns = [INT_PATTERN];
+const INT_PATTERN = patternFromFilter('?< <bits 0, bits 1, {} _>=bits "+", bits "-">');
 
-function readAll(stream) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    stream.on("data", c => chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
+// Closed pattern for list of int:
+// list = < {} nil, {int car, list cdr} cons >
+const INT_LIST_PATTERN = patternFromFilter(
+  '$ bits = < bits 0, bits 1, {} _ >; $ int = < bits "+", bits "-" >; ?< {} nil, { $int car, list cdr } cons > = list'
+);
 
 // Build bits Value (MSB outermost) from a non-negative BigInt.
 function buildBits(n) {
@@ -54,7 +37,7 @@ function buildBits(n) {
   return v;
 }
 
-// Parse a decimal integer string ([-+]?[ ]*[1-9][0-9]*|0) into a k int Value.
+// Parse a decimal integer string into a k int Value.
 function parseIntStr(str) {
   str = str.trim();
   let sign = "+";
@@ -64,12 +47,44 @@ function parseIntStr(str) {
     throw new Error(`Invalid integer syntax: ${JSON.stringify(str)}`);
   }
   const n = BigInt(str);
-  if (n === 0n) sign = "+"; // zero is always '+'
+  if (n === 0n) sign = "+";
   return Value.variant(sign, buildBits(n));
 }
 
-// Walk a decoded int Value (Variant sign → bits) and return a decimal string.
-function printIntValue(value) {
+// Parse a list of decimal integers, e.g. "[0,1,2]" or "[]"
+function parseIntListStr(str) {
+  str = str.trim();
+  if (!str.startsWith("[") || !str.endsWith("]")) {
+    throw new Error(`Invalid integer list syntax: ${JSON.stringify(str)}`);
+  }
+  const inner = str.slice(1, -1).trim();
+  if (inner === "") {
+    return Value.variant("nil", Value.product({}));
+  }
+  const parts = inner.split(",");
+  const items = parts.map((part) => parseIntStr(part));
+  let result = Value.variant("nil", Value.product({}));
+  for (let i = items.length - 1; i >= 0; i--) {
+    result = Value.variant("cons", Value.product({
+      car: items[i],
+      cdr: result
+    }));
+  }
+  return result;
+}
+
+// Parse a decimal integer string or integer list into an enveloped k Value.
+export function parse(str) {
+  str = str.trim();
+  const raw = str.startsWith("[") ? parseIntListStr(str) : parseIntStr(str);
+  const pattern = isVariant(raw) && (raw.tag === "nil" || raw.tag === "cons")
+    ? INT_LIST_PATTERN
+    : INT_PATTERN;
+  return withPattern(raw, pattern);
+}
+
+// Walk a decoded int Value and return a decimal string.
+function printSingleInt(value) {
   if (!isVariant(value) || (value.tag !== "+" && value.tag !== "-")) {
     throw new Error("Not a valid k int value");
   }
@@ -80,42 +95,48 @@ function printIntValue(value) {
     bits += node.tag;
     node = node.value;
   }
-  // bits is MSB-first binary string (may be empty for zero represented as "0")
   const n = bits === "" ? 0n : BigInt("0b" + bits);
   const digits = n.toString(10);
   if (n === 0n) return "0";
   return (sign === "-" ? "-" : "") + digits;
 }
 
-async function main() {
-  const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    usage(console.log);
-    exit(0);
+// Walk a decoded int list Value and return a bracketed string like "[0,1,2]".
+function printIntList(value) {
+  const items = [];
+  let node = value;
+  while (isVariant(node) && node.tag === "cons") {
+    const product = isProduct(node.value) ? node.value.product : null;
+    if (!product || !product.car || !product.cdr) {
+      throw new Error("Invalid list cons node");
+    }
+    items.push(printSingleInt(product.car));
+    node = product.cdr;
   }
-
-  if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    usage();
-    exit(1);
+  if (!isVariant(node) || node.tag !== "nil") {
+    throw new Error("Not a valid k int list: does not terminate in nil");
   }
+  return `[${items.join(",")}]`;
+}
 
-  const buf = await readAll(stdin);
-
-  if (args[0] === "--parse") {
-    const text = buf.toString("utf8").trim();
-    const value = parseIntStr(text);
-    stdout.write(encodeToWire(value, INT_PATTERN));
-  } else {
-    const { value } = decodeWire(buf);
-    stdout.write(printIntValue(value) + "\n");
+// Walk a decoded int or int list Value and return a formatted string.
+export function print(value) {
+  if (isVariant(value)) {
+    if (value.tag === "nil" || value.tag === "cons") {
+      return printIntList(value);
+    }
+    if (value.tag === "+" || value.tag === "-") {
+      return printSingleInt(value);
+    }
   }
+  throw new Error("Not a valid k int or int list value");
 }
 
-if (isMainEntrypoint(import.meta.url, argv[1])) {
-  main().catch(err => {
-    console.error(err.message || String(err));
-    exit(1);
-  });
-}
+runCodecCLI(import.meta.url, { parse, print, doc });
 
-export { INT_PATTERN, name, patterns, parseIntStr as parse, printIntValue as print };
+export {
+  INT_PATTERN,
+  INT_LIST_PATTERN,
+  parseIntStr,
+  parseIntListStr
+};

package/codecs/json-codec.mjs

@@ -1,44 +1,11 @@
 import { Value, isProduct, isVariant } from "../Value.mjs";
+import { patternFromFilter } from "./runtime/codec-sdk.mjs";
 import { STRING_PATTERN_PROPERTY_LIST, textToStringValue, stringValueToText } from "./string-codec.mjs";
-import { FLOAT64_PATTERN } from "./runtime/ieee-pattern.mjs";
+import { FLOAT64_PATTERN, encodeNumberToValue, decodeValueToNumber } from "./ieee.mjs";
 
 const UNIT = Value.product({});
-const BOOL_PATTERN = [
-  ["closed-union", [["false", 1], ["true", 1]]],
-  ["closed-product", []]
-];
-const NULL_PATTERN = [
-  ["closed-union", [["null", 1]]],
-  ["closed-product", []]
-];
-
-function bitValue(bit) {
-  return Value.variant(bit === 0 ? "0" : "1", UNIT);
-}
-
-function bitsProduct(width, value) {
-  const big = BigInt(value);
-  const product = {};
-  for (let i = width - 1; i >= 0; i--) {
-    product[String(i)] = bitValue(Number((big >> BigInt(i)) & 1n));
-  }
-  return Value.product(product);
-}
-
-function encodeNumberToValue(number) {
-  const buf = Buffer.alloc(8);
-  buf.writeDoubleBE(number, 0);
-  const bits = buf.readBigUInt64BE(0);
-  const sign = Number((bits >> 63n) & 1n);
-  const exponent = Number((bits >> 52n) & 0x7ffn);
-  const fraction = bits & ((1n << 52n) - 1n);
-
-  return Value.product({
-    sign: Value.variant(sign === 0 ? "+" : "-", UNIT),
-    exponent: bitsProduct(11, exponent),
-    fraction: bitsProduct(52, fraction)
-  });
-}
+const BOOL_PATTERN = patternFromFilter("?< {} false, {} true >");
+const NULL_PATTERN = patternFromFilter("?< {} null >");
 
 function requireProduct(value, where) {
   if (!isProduct(value)) {
@@ -47,45 +14,6 @@ function requireProduct(value, where) {
   return value.product;
 }
 
-function requireVariant(value, where) {
-  if (!isVariant(value)) {
-    throw new Error(`${where}: expected Variant`);
-  }
-  return value;
-}
-
-function parseBitsProduct(value, maxBit, where) {
-  const product = requireProduct(value, where);
-  let n = 0n;
-  for (let i = maxBit; i >= 0; i--) {
-    const entry = requireVariant(product[String(i)], `${where}.bit${i}`);
-    if (entry.tag !== "0" && entry.tag !== "1") {
-      throw new Error(`${where}.bit${i}: expected tag 0 or 1`);
-    }
-    n = (n << 1n) | BigInt(entry.tag === "1" ? 1 : 0);
-  }
-  return n;
-}
-
-function decodeValueToNumber(value) {
-  const product = requireProduct(value, "json.number");
-  const sign = requireVariant(product.sign, "json.number.sign");
-  if (sign.tag !== "+" && sign.tag !== "-") {
-    throw new Error(`json.number.sign: expected + or -, got ${sign.tag}`);
-  }
-  const exponent = parseBitsProduct(product.exponent, 10, "json.number.exponent");
-  const fraction = parseBitsProduct(product.fraction, 51, "json.number.fraction");
-
-  const bits =
-    (BigInt(sign.tag === "-" ? 1 : 0) << 63n) |
-    (exponent << 52n) |
-    fraction;
-
-  const buf = Buffer.alloc(8);
-  buf.writeBigUInt64BE(bits, 0);
-  return buf.readDoubleBE(0);
-}
-
 function fromJsonValue(value) {
   if (value === null) {
     return Value.variant("null", UNIT);
@@ -153,7 +81,7 @@ function patternFromJsonValue(value) {
     return composePattern(
       "closed-product",
       Object.keys(value)
-        .sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
         .map((key) => [key, patternFromJsonValue(value[key])])
     );
   }

package/codecs/json.mjs

@@ -1,67 +1,23 @@
 #!/usr/bin/env node
 
-import { stdin, stdout, argv, exit } from "node:process";
-import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
-import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
+import { withPattern, runCodecCLI } from "./runtime/codec-sdk.mjs";
 import { fromJsonValue, toJsonValue, patternFromJsonValue } from "./json-codec.mjs";
 
-const name = "json";
-const universal = true;
+export const doc = `
+JSON codec (RFC 8259).
 
-function usage(stream = console.error) {
-  stream(`Usage: ${argv[1]} --parse | --print`);
-  stream("  --parse      Read JSON from stdin, write binary pattern+value stream.");
-  stream("  --print      Read binary pattern+value stream from stdin, write JSON.");
-  stream("  -h, --help   Show this help.");
-}
-
-function readAll(stream) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
+Translates JSON data to/from self-describing enveloped k values.
+`;
 
-function parse(text) {
-  return fromJsonValue(JSON.parse(text));
+export function parse(text) {
+  const json = JSON.parse(text);
+  const value = fromJsonValue(json);
+  const pattern = patternFromJsonValue(json);
+  return withPattern(value, pattern);
 }
 
-function print(value) {
+export function print(value) {
   return JSON.stringify(toJsonValue(value));
 }
 
-async function main() {
-  const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    usage(console.log);
-    exit(0);
-  }
-
-  if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    usage();
-    exit(1);
-  }
-
-  const buf = await readAll(stdin);
-
-  if (args[0] === "--parse") {
-    const text = buf.toString("utf8");
-    const json = JSON.parse(text);
-    const value = fromJsonValue(json);
-    stdout.write(encodeToWire(value, patternFromJsonValue(json)));
-  } else {
-    const { value } = decodeWire(buf);
-    stdout.write(`${print(value)}\n`);
-  }
-}
-
-if (isMainEntrypoint(import.meta.url, argv[1])) {
-  main().catch((error) => {
-    console.error(error.stack || error.message || String(error));
-    exit(1);
-  });
-}
-
-export { name, universal, parse, print };
+runCodecCLI(import.meta.url, { parse, print, doc });

package/codecs/k-parse.mjs

@@ -2,11 +2,9 @@
 
 import fs from "node:fs";
 import { argv, stdin, exit, stdout } from "node:process";
-import k from "../index.mjs";
 import { parseValue } from "../valueIO.mjs";
 import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
-import { exportPatternGraph } from "./runtime/codec.mjs";
-import { patternToPropertyList } from "./runtime/pattern-json.mjs";
+import { patternFromFilter } from "./runtime/pattern-k.mjs";
 import { encodeToWire } from "./runtime/prefix-codec.mjs";
 
 function usage(prog) {
@@ -32,20 +30,6 @@ function readAll(stream) {
   });
 }
 
-function propertyListFromScript(script) {
-  const annotated = k.annotate(script);
-  const mainRel = annotated.rels.__main__;
-  if (!mainRel || !mainRel.typePatternGraph) {
-    throw new Error("Could not resolve __main__ relation");
-  }
-  if (mainRel.def.op !== "filter" && mainRel.def.op !== "code") {
-    throw new Error("Input script must end with a filter or a type name");
-  }
-  const rootPatternId = mainRel.typePatternGraph.find(mainRel.def.patterns[0]);
-  const pattern = exportPatternGraph(mainRel.typePatternGraph, rootPatternId);
-  return patternToPropertyList(pattern);
-}
-
 async function main() {
   const prog = argv[1];
   const args = argv.slice(2);
@@ -82,8 +66,8 @@ async function main() {
   const value = parseValue(inputText, null, null);
 
   const propertyList = (() => {
-    if (inputTypeArg != null) return propertyListFromScript(maybeReadFile(inputTypeArg));
-    if (inputPatternArg != null) return propertyListFromScript(maybeReadFile(inputPatternArg));
+    if (inputTypeArg != null) return patternFromFilter(maybeReadFile(inputTypeArg));
+    if (inputPatternArg != null) return patternFromFilter(maybeReadFile(inputPatternArg));
     return null;
   })();