@fraczak/k 6.2.0 → 6.2.1

package/Examples/list.k

@@ -0,0 +1,7 @@
+list? = ?< {} nil, {X car, Y cdr} cons > = Y;
+nil = {} |nil list?;
+singleton = {() car, nil cdr} | cons list?;
+cons = {.car car, .cdr cdr} | cons list?;
+nil? = list? /nil nil;
+car = list? /cons .car;
+cdr = list? /cons .cdr;

package/Examples/nat.k

@@ -0,0 +1,12 @@
+$ nat = < {} 0, nat +1 >;
+0 = {} | 0 ;
+0? = $ nat { / 0 if, () then} .then;
+succ = | +1 $ nat ;
+pred = $nat / +1 ;
+add = ?{ $nat x, ... } = X <{.x pred x, .y succ y} ?X add, .y> ;
+mult = <
+    {{.x pred x, .y y} mult x, .y y} add,
+    0
+> ;
+
+succ {()x,()y} add

package/Examples/vhdl_to_k.k

@@ -0,0 +1,50 @@
+-- VHDL to K Translation Patterns
+
+-- VHDL: signal a : std_logic;
+-- K:    $ bit = <{} 0, {} 1>;
+
+-- VHDL: signal bus : std_logic_vector(7 downto 0);
+-- K:    $ byte = {bit 0, bit 1, bit 2, bit 3, bit 4, bit 5, bit 6, bit 7};
+
+-- VHDL: entity adder is port(a,b: in std_logic; sum: out std_logic); end;
+-- K:    adder = ${bit a, bit b} {.a a_out, .b b_out, xor_gate sum_out};
+
+-- VHDL: process(clk) begin if rising_edge(clk) then q <= d; end if; end;
+-- K:    dff = $bit .;  -- Identity (register holds value)
+
+-- VHDL: y <= a and b;
+-- K:    and_gate = ${bit a, bit b} <{.a.1 1, .b.1 1, 1}, 0>;
+
+-- VHDL: y <= a or b;  
+-- K:    or_gate = ${bit a, bit b} <{.a.0 0, .b.0 0, 0}, 1>;
+
+-- VHDL: y <= not a;
+-- K:    not_gate = $bit <{.0 0, 1}, {.1 1, 0}>;
+
+-- VHDL: with sel select y <= a when "00", b when "01", c when others;
+-- K:    mux = ${bit sel0, bit sel1, bit a, bit b, bit c} <
+--             {.sel0.0 0, .sel1.0 0, .a},
+--             {.sel0.1 1, .sel1.0 0, .b}, 
+--             .c>;
+
+-- VHDL: architecture of 4-bit adder
+four_bit_adder = ${
+  {bit 0, bit 1, bit 2, bit 3} a,
+  {bit 0, bit 1, bit 2, bit 3} b
+} {
+  {.a.0 a0, .b.0 b0} full_adder fa0,
+  {.a.1 a1, .b.1 b1, .fa0.carry c_in} full_adder fa1,
+  {.a.2 a2, .b.2 b2, .fa1.carry c_in} full_adder fa2,
+  {.a.3 a3, .b.3 b3, .fa2.carry c_in} full_adder fa3,
+  {.fa0.sum 0, .fa1.sum 1, .fa2.sum 2, .fa3.sum 3} sum,
+  .fa3.carry overflow
+};
+
+-- VHDL: Full adder component
+full_adder = ${bit a, bit b, bit c_in} {
+  {.a a_val, .b b_val} xor_gate ab_xor,
+  {.ab_xor xor_val, .c_in c_val} xor_gate sum,
+  {.a a_val, .b b_val} and_gate ab_and,
+  {.ab_xor xor_val, .c_in c_val} and_gate xor_cin_and,
+  {.ab_and and1, .xor_cin_and and2} or_gate carry
+};

package/README.md

@@ -195,6 +195,14 @@ Installed binary names are `k-` plus the source basename without `.mjs`, except
 for `k.mjs` itself. Source names that already include `k-`, such as
 `codecs/k-parse.mjs`, keep that name.
 
+## WebAssembly Backend
+
+The experimental WebAssembly backend lives in the separate
+[`fraczak/k-wasm`](https://github.com/fraczak/k-wasm) repository. Keeping the
+backend separate avoids adding its WABT dependency to the core runtime. External
+backends integrate with the compiler and binary codecs through
+[`backend-api.mjs`](backend-api.mjs).
+
 ## Node.js API
 
 ```js

package/backend-api.mjs

@@ -0,0 +1,12 @@
+export { annotate } from "./index.mjs";
+export { lowerToKVM, executeKVM } from "./kvm.mjs";
+export { decodeWire, encodeToWire } from "./codecs/runtime/prefix-codec.mjs";
+export { exportPatternGraph, NODE_KIND } from "./codecs/runtime/codec.mjs";
+export { patternToPropertyList, propertyListToPattern } from "./codecs/runtime/pattern-json.mjs";
+export { Product, Variant, fromObject } from "./Value.mjs";
+export { decodeObject, loadLibrary } from "./object.mjs";
+export { createState, evaluateInput } from "./repl.mjs";
+export { parse as parseFloat64, print as printFloat64 } from "./codecs/ieee.mjs";
+export { valueForCode } from "./repl-codecs.mjs";
+export { default as codes } from "./codes.mjs";
+export { default as run, run_converged } from "./run.mjs";

package/codecs/runtime/codec.mjs

@@ -614,6 +614,7 @@ function refinePatternForValue(pattern, value) {
     }
 
     if (baseNode.kind === NODE_KIND.CLOSED_PRODUCT || baseNode.kind === NODE_KIND.OPEN_PRODUCT) {
+      result.kind = NODE_KIND.CLOSED_PRODUCT;
       const values = occurrences.get(patternNodeId) || [];
       const explicit = new Map(baseNode.edges.map((edge) => [edge.label, edge.target]));
       let labels = [...explicit.keys()].sort();

package/kvm.mjs

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { argv, stdin, exit, stdout } from "node:process";
+import { Product, Variant, composePattern, withPattern } from "./Value.mjs";
+import { exportPatternGraph } from "./codecs/runtime/codec.mjs";
+import { patternToPropertyList } from "./codecs/runtime/pattern-json.mjs";
+import {
+  constrainWithPattern,
+  intersectPatterns,
+  projectionPattern,
+  verify,
+  run
+} from "./run.mjs";
+import { annotate } from "./index.mjs";
+import { decodeWire, encodeToWire } from "./codecs/runtime/prefix-codec.mjs";
+import { decodeObject, loadLibrary } from "./object.mjs";
+import codes from "./codes.mjs";
+import { isMainEntrypoint } from "./codecs/runtime/cli-entry.mjs";
+
+class KVMBuilder {
+  constructor(typePatternGraph) {
+    this.typePatternGraph = typePatternGraph;
+    this.regCount = 0;
+    this.instructions = [];
+  }
+
+  nextReg() {
+    return `%v${this.regCount++}`;
+  }
+
+  emit(inst) {
+    this.instructions.push(inst);
+  }
+
+  getStaticPattern(exp, index) {
+    if (!this.typePatternGraph || !exp.patterns) return null;
+    const patternId = this.typePatternGraph.find(exp.patterns[index]);
+    return patternToPropertyList(exportPatternGraph(this.typePatternGraph, patternId));
+  }
+}
+
+function compile(exp, inputReg, builder) {
+  switch (exp.op) {
+    case "identity": {
+      const dest = builder.nextReg();
+      builder.emit({ op: "id", dest, src: inputReg });
+      return dest;
+    }
+    case "empty": {
+      builder.emit({ op: "fail" });
+      return builder.nextReg();
+    }
+    case "filter": {
+      const dest = builder.nextReg();
+      builder.emit({
+        op: "guard_pattern",
+        dest,
+        src: inputReg,
+        pattern: builder.getStaticPattern(exp, 0),
+        exp
+      });
+      return dest;
+    }
+    case "code": {
+      const dest = builder.nextReg();
+      builder.emit({
+        op: "guard_code",
+        dest,
+        src: inputReg,
+        code: exp.code,
+        exp
+      });
+      return dest;
+    }
+    case "dot": {
+      const dest = builder.nextReg();
+      builder.emit({
+        op: "project_field",
+        dest,
+        src: inputReg,
+        label: exp.dot,
+        pattern: builder.getStaticPattern(exp, 1),
+        exp
+      });
+      return dest;
+    }
+    case "div": {
+      const dest = builder.nextReg();
+      builder.emit({
+        op: "project_variant",
+        dest,
+        src: inputReg,
+        tag: exp.div,
+        pattern: builder.getStaticPattern(exp, 1),
+        exp
+      });
+      return dest;
+    }
+    case "vid": {
+      const dest = builder.nextReg();
+      builder.emit({
+        op: "make_variant",
+        dest,
+        tag: exp.vid,
+        src: inputReg
+      });
+      return dest;
+    }
+    case "ref": {
+      const dest = builder.nextReg();
+      if (exp.ref.startsWith("_")) {
+        builder.emit({
+          op: "call_intrinsic",
+          dest,
+          symbol: exp.ref,
+          src: inputReg,
+          pattern: builder.getStaticPattern(exp, 0),
+          exp
+        });
+      } else {
+        builder.emit({
+          op: "call",
+          dest,
+          func: exp.ref,
+          src: inputReg,
+          exp
+        });
+      }
+      return dest;
+    }
+    case "comp": {
+      let currentReg = inputReg;
+      const compInputPattern = builder.getStaticPattern(exp, 0);
+      if (compInputPattern) {
+        const guarded = builder.nextReg();
+        builder.emit({ op: "guard_pattern", dest: guarded, src: currentReg, pattern: compInputPattern, exp });
+        currentReg = guarded;
+      }
+      for (const subExp of exp.comp) {
+        currentReg = compile(subExp, currentReg, builder);
+      }
+      return currentReg;
+    }
+    case "product": {
+      const dest = builder.nextReg();
+      const branches = [];
+      for (const { label, exp: fieldExp } of exp.product) {
+        const branchBuilder = new KVMBuilder(builder.typePatternGraph);
+        const branchInput = "%in";
+        const branchOutput = compile(fieldExp, branchInput, branchBuilder);
+        branchBuilder.emit({ op: "return", src: branchOutput });
+        branches.push({
+          label,
+          body: branchBuilder.instructions
+        });
+      }
+      builder.emit({
+        op: "product",
+        dest,
+        src: inputReg,
+        branches,
+        pattern: builder.getStaticPattern(exp, 1),
+        exp
+      });
+      return dest;
+    }
+    case "union": {
+      const dest = builder.nextReg();
+      const branches = [];
+      for (const branchExp of exp.union) {
+        const branchBuilder = new KVMBuilder(builder.typePatternGraph);
+        const branchInput = "%in";
+        const branchOutput = compile(branchExp, branchInput, branchBuilder);
+        branchBuilder.emit({ op: "return", src: branchOutput });
+        branches.push({
+          body: branchBuilder.instructions
+        });
+      }
+      builder.emit({
+        op: "union",
+        dest,
+        src: inputReg,
+        branches,
+        exp
+      });
+      return dest;
+    }
+    default:
+      throw new Error(`Unsupported AST operation: ${exp.op}`);
+  }
+}
+
+export function lowerToKVM(relDef, name, options = {}) {
+  const typePatternGraph = relDef.typePatternGraph || null;
+  const builder = new KVMBuilder(typePatternGraph);
+  const inputReg = "%in";
+
+  let currentReg = inputReg;
+  const inputPattern = builder.getStaticPattern(relDef.def, 0);
+  if (inputPattern) {
+    const guarded = builder.nextReg();
+    builder.emit({ op: "guard_pattern", dest: guarded, src: currentReg, pattern: inputPattern, exp: relDef.def });
+    currentReg = guarded;
+  }
+
+  const bodyOutput = compile(relDef.def, currentReg, builder);
+
+  let finalReg = bodyOutput;
+  const outputPattern = builder.getStaticPattern(relDef.def, 1);
+  if (outputPattern) {
+    const guarded = builder.nextReg();
+    builder.emit({ op: "guard_pattern", dest: guarded, src: finalReg, pattern: outputPattern, exp: relDef.def });
+    finalReg = guarded;
+  }
+
+  builder.emit({ op: "return", src: finalReg });
+
+  return {
+    name,
+    inputPattern,
+    outputPattern,
+    isConverged: relDef.typeDerivation?.status === "converged",
+    body: builder.instructions
+  };
+}
+
+function executeBlock(instructions, inputVal, context) {
+  const registers = new Map();
+  registers.set("%in", inputVal);
+
+  for (const inst of instructions) {
+    const res = executeInstruction(inst, registers, context);
+    if (res === undefined) {
+      return undefined;
+    }
+    if (res.type === "return") {
+      return res.value;
+    }
+  }
+  return undefined;
+}
+
+function executeInstruction(inst, registers, context) {
+  const options = context.options || {};
+  switch (inst.op) {
+    case "id": {
+      registers.set(inst.dest, registers.get(inst.src));
+      return { type: "continue" };
+    }
+    case "fail": {
+      return undefined;
+    }
+    case "guard_pattern": {
+      const val = registers.get(inst.src);
+      if (options.envelopeFree) {
+        registers.set(inst.dest, val);
+        return { type: "continue" };
+      }
+      try {
+        const constrained = constrainWithPattern(val, inst.pattern, inst.exp);
+        registers.set(inst.dest, constrained);
+        return { type: "continue" };
+      } catch (err) {
+        if (err instanceof TypeError) {
+          throw err;
+        }
+        return undefined;
+      }
+    }
+    case "guard_code": {
+      const val = registers.get(inst.src);
+      if (options.envelopeFree) {
+        registers.set(inst.dest, val);
+        return { type: "continue" };
+      }
+      if (verify(context.findCode, inst.code, val)) {
+        registers.set(inst.dest, val);
+        return { type: "continue" };
+      }
+      return undefined;
+    }
+    case "project_field": {
+      const val = registers.get(inst.src);
+      if (!(val instanceof Product)) return undefined;
+      const fieldVal = val.product[inst.label];
+      if (fieldVal === undefined) return undefined;
+
+      if (options.envelopeFree) {
+        registers.set(inst.dest, fieldVal);
+      } else {
+        const pattern = projectionPattern(inst.pattern, val.pattern, inst.label, inst.exp);
+        registers.set(inst.dest, withPattern(fieldVal, pattern));
+      }
+      return { type: "continue" };
+    }
+    case "project_variant": {
+      const val = registers.get(inst.src);
+      if (!(val instanceof Variant) || val.tag !== inst.tag) return undefined;
+
+      if (options.envelopeFree) {
+        registers.set(inst.dest, val.value);
+      } else {
+        const pattern = projectionPattern(inst.pattern, val.pattern, inst.tag, inst.exp);
+        registers.set(inst.dest, withPattern(val.value, pattern));
+      }
+      return { type: "continue" };
+    }
+    case "make_variant": {
+      const val = registers.get(inst.src);
+      if (options.envelopeFree) {
+        registers.set(inst.dest, new Variant(inst.tag, val));
+      } else {
+        registers.set(
+          inst.dest,
+          new Variant(inst.tag, val, composePattern("open-union", [[inst.tag, val.pattern]]))
+        );
+      }
+      return { type: "continue" };
+    }
+    case "call": {
+      const val = registers.get(inst.src);
+      const relDef = context.rels[inst.func];
+      if (!relDef) {
+        throw new Error(`Unknown ref: '${inst.func}'`);
+      }
+      if (options.requireConverged && relDef.typeDerivation?.status !== "converged") {
+        throw new Error(`Cannot run '${inst.func}' without envelopes: type derivation is not converged`);
+      }
+      if (options.trace) {
+        console.log(`[Trace] Calling ${inst.func} with:`, val ? val.toString() : "null");
+      }
+      if (!relDef._kvmFunc) {
+        relDef._kvmFunc = lowerToKVM(relDef, inst.func);
+      }
+      const res = executeKVM(relDef._kvmFunc, val, context);
+      if (options.trace) {
+        console.log(`[Trace] Returned from ${inst.func} ->:`, res ? res.toString() : "fail");
+      }
+      if (res === undefined) return undefined;
+      registers.set(inst.dest, res);
+      return { type: "continue" };
+    }
+    case "call_intrinsic": {
+      const val = registers.get(inst.src);
+      const builtinFunc = run.builtin[inst.symbol];
+      if (!builtinFunc) {
+        throw new Error(`Unknown builtin: '${inst.symbol}'`);
+      }
+      if (!options.envelopeFree && inst.pattern) {
+        try {
+          const constrained = constrainWithPattern(val, inst.pattern, inst.exp);
+          const res = builtinFunc(constrained);
+          registers.set(inst.dest, res);
+          return { type: "continue" };
+        } catch (err) {
+          throw err;
+        }
+      } else {
+        const res = builtinFunc(val);
+        registers.set(inst.dest, res);
+        return { type: "continue" };
+      }
+    }
+    case "product": {
+      const val = registers.get(inst.src);
+      const result = {};
+      const patternEntries = [];
+      for (const branch of inst.branches) {
+        const branchRes = executeBlock(branch.body, val, context);
+        if (branchRes === undefined) return undefined;
+        result[branch.label] = branchRes;
+        if (!options.envelopeFree) {
+          patternEntries.push([branch.label, branchRes.pattern]);
+        }
+      }
+      let productValue;
+      if (options.envelopeFree) {
+        productValue = new Product(result);
+      } else {
+        const staticOutputPattern = inst.pattern;
+        if (staticOutputPattern) {
+          productValue = new Product(result, staticOutputPattern);
+        } else {
+          productValue = new Product(result, composePattern("closed-product", patternEntries));
+        }
+      }
+      registers.set(inst.dest, productValue);
+      return { type: "continue" };
+    }
+    case "union": {
+      const val = registers.get(inst.src);
+      for (const branch of inst.branches) {
+        const branchRes = executeBlock(branch.body, val, context);
+        if (branchRes !== undefined) {
+          registers.set(inst.dest, branchRes);
+          return { type: "continue" };
+        }
+      }
+      return undefined;
+    }
+    case "return": {
+      return { type: "return", value: registers.get(inst.src) };
+    }
+    default:
+      throw new Error(`Unknown instruction op: ${inst.op}`);
+  }
+}
+
+export function executeKVM(kvmFunc, inputVal, context) {
+  const options = context.options || {};
+  if (options.requireConverged && !kvmFunc.isConverged) {
+    throw new Error(`Cannot run '${kvmFunc.name}' without envelopes: type derivation is not converged`);
+  }
+
+  const result = executeBlock(kvmFunc.body, inputVal, context);
+  if (result === undefined) return undefined;
+
+  if (options.envelopeFree && kvmFunc.isConverged) {
+    return withPattern(result, kvmFunc.outputPattern);
+  }
+  return result;
+}
+
+export default {
+  lowerToKVM,
+  executeKVM
+};
+
+function usage() {
+  const prog = argv[1] || "kvm.mjs";
+  console.error(`Usage: node ${prog} [ options ] ( k-expr | -k file ) [ input-file ]`);
+  console.error("Options:");
+  console.error("  --lib file          Load a .klib dependency before compiling. May be repeated.");
+  console.error("  --envelope-free     Run the interpreter in envelope-free mode.");
+  console.error("  -h, --help          Show this help.");
+}
+
+async function main() {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage();
+    return exit(0);
+  }
+
+  let envelopeFree = false;
+  const libraries = [];
+
+  // Parse options
+  while (args.length > 0) {
+    if (args[0] === "--envelope-free") {
+      envelopeFree = true;
+      args.shift();
+    } else if (args[0] === "--lib") {
+      args.shift();
+      const libPath = args.shift();
+      if (!libPath) throw new Error("--lib requires a file argument");
+      const libBuffer = fs.readFileSync(libPath);
+      libraries.push(loadLibrary(decodeObject(libBuffer)));
+    } else {
+      break;
+    }
+  }
+
+  let kScriptStr = (function (arg) {
+    if (arg == null) {
+      throw new Error("Missing script argument");
+    }
+    if (arg === "-k") {
+      const fileArg = args.shift();
+      if (!fileArg) throw new Error("-k requires a file argument");
+      return fs.readFileSync(fileArg, "utf8");
+    } else {
+      return arg;
+    }
+  })(args.shift());
+
+  const inputStream = (function (arg) {
+    if (arg == null) {
+      return stdin;
+    }
+    return fs.createReadStream(arg);
+  })(args.shift());
+
+  const defs = annotate(kScriptStr, { libraries });
+  const mainRel = defs.rels.__main__;
+  if (!mainRel) {
+    throw new Error("No main relation (__main__) defined in script");
+  }
+
+  const kvmFunc = lowerToKVM(mainRel, "__main__");
+
+  const buffer = [];
+  inputStream.on("data", (data) => buffer.push(Buffer.isBuffer(data) ? data : Buffer.from(data)));
+  inputStream.on("end", () => {
+    try {
+      const inputBuffer = Buffer.concat(buffer);
+      const { pattern: inputPattern, value } = decodeWire(inputBuffer);
+      const context = {
+        rels: defs.rels,
+        findCode: codes.find,
+        options: {
+          envelopeFree
+        }
+      };
+      const result = executeKVM(kvmFunc, value, context);
+      if (result === undefined) {
+        throw new Error("kVM expression evaluated to undefined");
+      }
+      stdout.write(encodeToWire(result, result.pattern));
+    } catch (error) {
+      console.error(error.stack || error.message || String(error));
+      exit(1);
+    }
+  });
+}
+
+if (isMainEntrypoint(import.meta.url, argv[1])) {
+  main().catch((error) => {
+    console.error(error.stack || error.message || String(error));
+    usage();
+    exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.2.0",
+    "version": "6.2.1",
     "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": {
@@ -30,7 +30,8 @@
         "k-show": "./codecs/show.mjs",
         "k-unit": "./codecs/unit.mjs",
         "k-utf16": "./codecs/utf16.mjs",
-        "k-utf8": "./codecs/utf8.mjs"
+        "k-utf8": "./codecs/utf8.mjs",
+        "k-vm": "./kvm.mjs"
     },
     "devDependencies": {
         "jiwson": "^0.1.2"

package/run.mjs

@@ -483,4 +483,4 @@ run_converged.defs = null;
 const run_coverged = run_converged;
 
 export default run;
-export { run, run_rel, run_converged, run_coverged };
+export { run, run_rel, run_converged, run_coverged, constrainWithPattern, intersectPatterns, projectionPattern, verify };

package/scripts/run-tests.mjs

@@ -20,6 +20,7 @@ const tests = [
   ["tests/test-hash-normalization.mjs", node, ["tests/test-hash-normalization.mjs"]],
   ["tests/test-k-object.mjs", node, ["tests/test-k-object.mjs"]],
   ["tests/test-repl.mjs", node, ["tests/test-repl.mjs"]],
+  ["tests/test-kvm.mjs", node, ["tests/test-kvm.mjs"]],
   ["tests/test-ieee-arithmetic.mjs", node, ["tests/test-ieee-arithmetic.mjs"]],
   ["tests/integration.sh", path.join(root, "tests/integration.sh"), []]
 ];