@fraczak/k 7.0.2 → 7.2.0

package/access-table.mjs

@@ -0,0 +1,343 @@
+// access-table.mjs: State-Indexed Access Table for Polymorphic Execution
+// Translates an input schema S into a compact, indexable navigation table
+// allowing function instructions to access payload fields and variants
+// without runtime string comparisons or dynamic dictionary lookups.
+
+import { patternToPropertyList } from "./codecs/runtime/pattern-json.mjs";
+
+/**
+ * Node descriptor for a single state in schema S.
+ */
+export class NodeDescriptor {
+  constructor(state, kind) {
+    this.state = state;
+    this.kind = kind; // 'product', 'union', or 'any'
+  }
+}
+
+/**
+ * AccessTable encapsulates the complete navigation structure for a
+ * schema S with respect to a function's structural access profile P.
+ */
+export class AccessTable {
+  constructor(descriptors, rootState = 0, wordSize = 8) {
+    this.descriptors = descriptors;
+    this.rootState = rootState;
+    this.wordSize = wordSize;
+    this.stateCount = descriptors.length;
+  }
+
+  getDescriptor(stateId) {
+    const desc = this.descriptors[stateId];
+    if (!desc) {
+      throw new Error(`AccessTable has no descriptor for state ${stateId}`);
+    }
+    return desc;
+  }
+
+  /**
+   * Resolves physical byte offset and child state for a logical
+   * field access.
+   */
+  resolveField(stateId, fieldNameOrSlot) {
+    const desc = this.getDescriptor(stateId);
+    if (desc.kind !== "product") {
+      throw new Error(`State ${stateId} is not a product (is ${desc.kind})`);
+    }
+
+    if (typeof fieldNameOrSlot === "string") {
+      const fieldMeta = desc.fields[fieldNameOrSlot];
+      if (!fieldMeta) {
+        throw new Error(
+          `Field '${fieldNameOrSlot}' not found in state ${stateId}`
+        );
+      }
+      return fieldMeta;
+    }
+
+    const slot = fieldNameOrSlot;
+    return {
+      byteOffset: desc.slotToByteOffset[slot],
+      childState: desc.slotToChildState[slot],
+      skipCount: desc.slotToSkipCount[slot]
+    };
+  }
+
+  /**
+   * Resolves branch index and child state for a variant discriminator.
+   */
+  resolveVariant(stateId, tagOrId) {
+    const desc = this.getDescriptor(stateId);
+    if (desc.kind !== "union") {
+      throw new Error(`State ${stateId} is not a union (is ${desc.kind})`);
+    }
+
+    if (typeof tagOrId === "string") {
+      const tagMeta = desc.tags[tagOrId];
+      if (!tagMeta) {
+        throw new Error(`Variant '${tagOrId}' not found in state ${stateId}`);
+      }
+      return tagMeta;
+    }
+
+    const tagId = tagOrId;
+    return {
+      branchId: desc.branchMap[tagId],
+      childState: desc.childStateMap[tagId]
+    };
+  }
+
+  toJSON() {
+    return {
+      rootState: this.rootState,
+      wordSize: this.wordSize,
+      stateCount: this.stateCount,
+      descriptors: this.descriptors
+    };
+  }
+}
+
+/**
+ * Normalizes a pattern, pattern graph, or property list into
+ * a canonical property list format.
+ */
+function toPropertyList(patternOrGraph) {
+  if (Array.isArray(patternOrGraph)) {
+    return patternOrGraph;
+  }
+  if (patternOrGraph && Array.isArray(patternOrGraph.nodes)) {
+    return patternToPropertyList(patternOrGraph);
+  }
+  if (patternOrGraph?.patterns?.nodes) {
+    // TypePatternGraph from KIR / KVM
+    return patternOrGraph.patterns.nodes.map((node, nodeIdx) => {
+      let kind = "any";
+      if (node.pattern === "{}") kind = "closed-product";
+      else if (node.pattern === "{...}") kind = "open-product";
+      else if (node.pattern === "<>") kind = "closed-union";
+      else if (node.pattern === "<...>") kind = "open-union";
+      const edgeMap = patternOrGraph.edges?.[nodeIdx] || {};
+      const edges = (node.fields || []).map((f) => {
+        const dest = edgeMap[f];
+        const target = Array.isArray(dest)
+          ? dest[0]
+          : typeof dest === "object" && dest !== null
+            ? Object.values(dest)[0]
+            : (dest ?? 0);
+        return [f, target];
+      });
+      return [kind, edges];
+    });
+  }
+  throw new Error("Invalid pattern representation for access table generation");
+}
+
+/**
+ * Builds an Access Table bridging an Input Schema S to Function
+ * Pattern P.
+ *
+ * @param {Array|Object} schema - Concrete input value schema S
+ * @param {Array|Object} pattern - Function's input pattern graph P
+ * @param {Object} [options]
+ * @param {number} [options.wordSize=8] - Word size in bytes (default: 8)
+ * @returns {AccessTable}
+ */
+export function buildAccessTable(schema, pattern, options = {}) {
+  const wordSize = options.wordSize ?? 8;
+  const sList = toPropertyList(schema);
+  const pList = toPropertyList(pattern);
+
+  const stateCount = sList.length;
+  const descriptors = new Array(stateCount);
+
+  const schemaRoot = options.schemaRoot ?? 0;
+  const patternRoot = options.patternRoot ?? 0;
+
+  // Simulation worklist: pairs of [stateInS, stateInP]
+  const visited = new Set();
+  const worklist = [[schemaRoot, patternRoot]];
+
+  while (worklist.length > 0) {
+    const [sId, pId] = worklist.shift();
+    const key = `${sId}:${pId}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+
+    const sNode = sList[sId];
+    const pNode = pList[pId];
+    if (!sNode || !pNode) continue;
+
+    const [sKind, sEdges] = sNode;
+    const [pKind, pEdges] = pNode;
+
+    const sIsUnion = sKind.includes("union");
+    const pIsUnion = pKind.includes("union");
+
+    if (sIsUnion !== pIsUnion && sKind !== "any" && pKind !== "any") {
+      throw new Error(
+        `Structural mismatch at S[${sId}] (${sKind}) vs P[${pId}] (${pKind})`
+      );
+    }
+
+    if (sIsUnion) {
+      // Sort variant tags in S alphabetically to define physical tag IDs
+      const sortedSEdges = [...sEdges].sort((a, b) =>
+        a[0].localeCompare(b[0])
+      );
+      const pEdgeMap = new Map(
+        pEdges.map(([label, target], idx) => [
+          label,
+          { target, branchIdx: idx }
+        ])
+      );
+
+      const tags = {};
+      const branchMap = [];
+      const childStateMap = [];
+
+      sortedSEdges.forEach(([tag, sTarget], tagId) => {
+        const pMatch = pEdgeMap.get(tag);
+        const branchId = pMatch ? pMatch.branchIdx : -1;
+        const pTarget = pMatch ? pMatch.target : null;
+
+        tags[tag] = {
+          tagId,
+          branchId,
+          childState: sTarget,
+          childPatternState: pTarget
+        };
+        branchMap[tagId] = branchId;
+        childStateMap[tagId] = sTarget;
+
+        if (pTarget != null && pTarget < pList.length) {
+          worklist.push([sTarget, pTarget]);
+        }
+      });
+
+      descriptors[sId] = {
+        state: sId,
+        kind: "union",
+        isOpen: sKind.startsWith("open"),
+        variantCount: sortedSEdges.length,
+        tags,
+        branchMap,
+        childStateMap
+      };
+    } else if (sKind.includes("product")) {
+      // Physical layout of fields in S: sorted by label
+      const sortedSEdges = [...sEdges].sort((a, b) =>
+        a[0].localeCompare(b[0])
+      );
+      const sFieldMap = new Map(
+        sortedSEdges.map(([label, target], idx) => [
+          label,
+          { target, physicalSlot: idx }
+        ])
+      );
+
+      const fields = {};
+      const slotToByteOffset = [];
+      const slotToChildState = [];
+      const slotToSkipCount = [];
+
+      pEdges.forEach(([field, pTarget], logicalSlot) => {
+        const sMatch = sFieldMap.get(field);
+        if (!sMatch) {
+          if (!pKind.startsWith("open")) {
+            throw new Error(`Required field '${field}' missing in S[${sId}]`);
+          }
+          return;
+        }
+
+        const physicalSlot = sMatch.physicalSlot;
+        const sTarget = sMatch.target;
+        const byteOffset = physicalSlot * wordSize;
+        const skipCount = physicalSlot;
+
+        fields[field] = {
+          logicalSlot,
+          physicalSlot,
+          byteOffset,
+          skipCount,
+          childState: sTarget,
+          childPatternState: pTarget
+        };
+
+        slotToByteOffset[logicalSlot] = byteOffset;
+        slotToChildState[logicalSlot] = sTarget;
+        slotToSkipCount[logicalSlot] = skipCount;
+
+        if (pTarget < pList.length) {
+          worklist.push([sTarget, pTarget]);
+        }
+      });
+
+      descriptors[sId] = {
+        state: sId,
+        kind: "product",
+        isOpen: sKind.startsWith("open"),
+        fieldCount: sortedSEdges.length,
+        fields,
+        slotToByteOffset,
+        slotToChildState,
+        slotToSkipCount
+      };
+    } else {
+      descriptors[sId] = {
+        state: sId,
+        kind: "any"
+      };
+    }
+  }
+
+  // Populate any unreached states in S as self-contained descriptors
+  for (let sId = 0; sId < stateCount; sId++) {
+    if (!descriptors[sId]) {
+      const [sKind, sEdges] = sList[sId];
+      if (sKind.includes("union")) {
+        const sorted = [...sEdges].sort((a, b) => a[0].localeCompare(b[0]));
+        descriptors[sId] = {
+          state: sId,
+          kind: "union",
+          isOpen: sKind.startsWith("open"),
+          variantCount: sorted.length,
+          tags: Object.fromEntries(
+            sorted.map(([t, target], i) => [
+              t,
+              { tagId: i, branchId: i, childState: target }
+            ])
+          ),
+          branchMap: sorted.map((_, i) => i),
+          childStateMap: sorted.map(([_, target]) => target)
+        };
+      } else if (sKind.includes("product")) {
+        const sorted = [...sEdges].sort((a, b) => a[0].localeCompare(b[0]));
+        descriptors[sId] = {
+          state: sId,
+          kind: "product",
+          isOpen: sKind.startsWith("open"),
+          fieldCount: sorted.length,
+          fields: Object.fromEntries(
+            sorted.map(([f, target], i) => [
+              f,
+              {
+                logicalSlot: i,
+                physicalSlot: i,
+                byteOffset: i * wordSize,
+                skipCount: i,
+                childState: target
+              }
+            ])
+          ),
+          slotToByteOffset: sorted.map((_, i) => i * wordSize),
+          slotToChildState: sorted.map(([_, target]) => target),
+          slotToSkipCount: sorted.map((_, i) => i)
+        };
+      } else {
+        descriptors[sId] = { state: sId, kind: "any" };
+      }
+    }
+  }
+
+  return new AccessTable(descriptors, schemaRoot, wordSize);
+}

package/backend-api.mjs

@@ -1,6 +1,10 @@
 export { annotate } from "./index.mjs";
 export { KVM_FORMAT, KVM_VERSION, lowerKIRRelationToKVM, lowerKIRToKVM, lowerToKVM, executeKVM, objectToKVMArtifact, specializeKVM } from "./kvm.mjs";
-export { decodeWire, encodeToWire } from "./codecs/runtime/prefix-codec.mjs";
+export {
+  decodeWire,
+  decodeWireLazy,
+  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 { Value, fromObject, isProduct, isVariant, isValue } from "./Value.mjs";
@@ -27,3 +31,21 @@ export {
   isIdentityIntrinsic,
   unsupportedIntrinsic
 } from "./intrinsics.mjs";
+export { buildAccessTable, AccessTable } from "./access-table.mjs";
+export {
+  PKIR_FORMAT,
+  PKIR_VERSION,
+  compileRelationToPKIR,
+  executePKIR,
+  specializePKIR,
+  valueToKVal,
+  kvalToValue,
+  lowerPKIRToKVM
+} from "./pkir.mjs";
+export {
+  compileWasmArtifactFromPKIR
+} from "./backends/wasm/src/wasm.mjs";
+export {
+  compileLLVMArtifactFromPKIR
+} from "./backends/llvm/src/llvm.mjs";
+

package/backends/llvm/README.md

@@ -46,34 +46,33 @@ status in `k_result`. These operations can compose through KIR `comp`.
 ```sh
 k-llvm-build [options] [source-snippet | input-file [output-exe]]
 k-llvm-compile [options] [source-snippet | input-file [output.ll]]
-k-llvm-jit [options] object.ko
-k-llvm-run [options] object.ko [input.kv]
+k-llvm [options] ( source-snippet | input-file ) [ input-wire-file ]
 ```
 
 Options:
 
 - `-o, --output path`: specify output file path explicitly.
 - `--lib file`: load one `.klib` or `.k` dependency before compiling.
-- `--export spec`: export a library alias into source scope (`name` or `libname:localname`). May be repeated.
-- `--input-pattern json-or-file`: for `k-llvm-run`, KIR property-list input pattern.
-- `--retype rel`: for `k-llvm-run`, relation to specialize (defaults to object main).
-- `--expect value-or-file`: for `k-llvm-run`, compare the output value against expected value text.
-- `-h`, `--help`: show usage.
-
-The compile commands follow the unified k CLI input convention: pass inline
-source, an existing `.k` source file, or a `.ko`/`.klib` object. Reads UTF-8
-source from stdin when input is omitted. Output paths can be specified as a
-positional argument or explicitly with `-o, --output`.
-Without `--expect`, `k-llvm-run` prints the result value as compact JSON.
+- `--export spec`: export a library alias into scope. Repeatable.
+- `--pkir`: lower via Polymorphic K IR (PKIR).
+- `--retype rel`: relation to specialize (defaults to object main).
+- `--opt flag`: Clang optimization flag (-O0, -O1, -O2, -O3).
+- `-h, --help`: show usage.
+
+The compile commands follow the unified k CLI input convention: pass
+inline source, an existing `.k` source file, or a `.ko`/`.klib` object.
+Reads UTF-8 source from stdin when input is omitted. Output paths can be
+specified as a positional argument or explicitly with `-o, --output`.
 `k-llvm-build` emits a native executable that reads and writes the binary
-k pattern+value envelope used by `codecs/k-parse.mjs` and `codecs/k-print.mjs`.
-The executable checks the stdin envelope pattern against the compiled input
-pattern and encodes stdout with the compiled output pattern.
-`k-llvm-jit` reads the stdin binary envelope first, specializes the object with
-that input pattern, caches the native executable, and writes the compiled
-output envelope to stdout.
-The native envelope codec supports the k Unicode string encoding used for
-labels and tags.
+k pattern+value envelope used by `codecs/k-parse.mjs` and
+`codecs/k-print.mjs`. The executable checks the stdin envelope pattern
+against the compiled input pattern and encodes stdout with the compiled
+output pattern.
+`k-llvm` reads the binary wire envelope, specializes the relation to
+that input pattern, caches the compiled native executable, and writes
+the compiled output envelope to stdout.
+The native envelope codec supports the k Unicode string encoding used
+for labels and tags.
 
 ## Tests
 

package/backends/llvm/bin/k-llvm-build.mjs

@@ -9,35 +9,61 @@ import {
 } from "../src/cli.mjs";
 import {
   compileKVMToExecutable,
-  compileObjectToExecutable
+  compileObjectToExecutable,
+  compilePKIRToExecutable
 } from "../src/executable.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-llvm-build.mjs";
-  stream(`Usage: node ${prog} [options] [source-snippet | input-file [output-exe]]`);
-  stream("Compile k source, .ko, .klib, or .kvm input into a native executable.");
-  stream("");
-  stream("Arguments:");
-  stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, .klib, or .kvm file. Reads UTF-8 source from stdin when omitted.");
-  stream("  output-exe      Output executable path.");
-  stream("");
-  stream("The executable reads a binary k pattern+value envelope from stdin and");
-  stream("writes a binary k pattern+value envelope to stdout.");
-  stream("The stdin envelope pattern must match the compiled input pattern;");
-  stream("stdout is encoded with the compiled output pattern.");
-  stream("");
-  stream("Options:");
-  stream("  -o, --output path        Specify output file path explicitly.");
-  stream("  --input-pattern pattern  Input pattern JSON or file path for specialization.");
-  stream("  --lib file               Load one .klib dependency before compiling.");
-  stream("  --export spec            Export a library alias into source scope. May be repeated.");
-  stream("                           spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help               Show this help.");
+  return [
+    "Compile k source, .ko, .klib, .kvm, or .pkir into a native",
+    "standalone executable.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       [source-snippet | input-file [output-exe]]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet (in the style of k.mjs).",
+    "  input-file       Source .k, .ko, .klib, .kvm, or .pkir file.",
+    "                   Reads UTF-8 source from stdin when omitted.",
+    "  output-exe       Output executable path.",
+    "",
+    "The executable reads a binary k pattern+value envelope from stdin",
+    "and writes a binary k pattern+value envelope to stdout.",
+    "The stdin envelope pattern must match the compiled input pattern;",
+    "stdout is encoded with the compiled output pattern.",
+    "",
+    "Options:",
+    "  -o, --output path        Specify output file path explicitly.",
+    "  --pkir                   Lower via Polymorphic K IR (PKIR).",
+    "  --input-pattern pattern  Input pattern JSON or file for spec.",
+    "  --retype rel             Relation to specialize (default: main).",
+    "  --lib file               Load .klib or .k library before build.",
+    "  --export spec     Export library alias into scope. Repeatable.",
+    "                    spec is 'name' or 'libname:localname'.",
+    "  --opt flag               Clang optimization flag (default: -O3).",
+    "  -h, --help               Show this help.",
+    "",
+    "Environment Variables:",
+    "  CLANG, CC            Path to Clang compiler (default: clang).",
+    "  K_LLVM_CLANG_OPT     Clang optimization flag (default: -O3).",
+    "  K_LLVM_RUNTIME_MODE  Runtime mode: fast, compact (default: fast).",
+    "",
+    "Examples:",
+    `  ${prog} 'x = |x; x x' -o program.exe`,
+    `  ${prog} program.k program.exe`,
+    `  ${prog} --lib Examples/poly.k --export concat 's' -o s.exe`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 function readMaybeFile(textOrPath) {
-  return fs.existsSync(textOrPath) ? fs.readFileSync(textOrPath, "utf8") : textOrPath;
+  return fs.existsSync(textOrPath)
+    ? fs.readFileSync(textOrPath, "utf8")
+    : textOrPath;
 }
 
 function readPattern(inputPattern) {
@@ -54,17 +80,38 @@ try {
 
   let explicitOutput = null;
   let rawInputPattern = null;
+  let relation = null;
+  let clangOpt = process.env.K_LLVM_CLANG_OPT || "-O3";
+  let runtimeMode = process.env.K_LLVM_RUNTIME_MODE || "fast";
   const remainingArgs = [];
   while (args.length > 0) {
     const arg = args[0];
     if (arg === "-o" || arg === "--output") {
       args.shift();
       explicitOutput = args.shift();
-      if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
     } else if (arg === "--input-pattern") {
       args.shift();
       rawInputPattern = args.shift();
-      if (!rawInputPattern) throw new Error("--input-pattern requires a JSON or file argument");
+      if (!rawInputPattern) {
+        throw new Error(
+          "--input-pattern requires a JSON or file argument"
+        );
+      }
+    } else if (arg === "--retype") {
+      args.shift();
+      relation = args.shift();
+      if (!relation) {
+        throw new Error("--retype requires a relation name");
+      }
+    } else if (arg === "--opt") {
+      args.shift();
+      clangOpt = args.shift();
+      if (!clangOpt) {
+        throw new Error("--opt requires a flag (e.g. -O3)");
+      }
     } else {
       remainingArgs.push(args.shift());
     }
@@ -72,17 +119,38 @@ try {
 
   const inputPattern = readPattern(rawInputPattern);
 
-  const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
-  const input = resolveProgramInput(remainingArgs, { allowStdinSource: true });
+  const { libraries, exportSpecs, usePKIR } =
+    parseCompileOptions(remainingArgs);
+  const input = resolveProgramInput(remainingArgs, {
+    allowStdinSource: true
+  });
   const positionalOutput = remainingArgs.shift();
   if (remainingArgs.length > 0) throw new Error("Too many arguments");
 
   const outputPath = explicitOutput || positionalOutput || null;
-  if (outputPath == null) throw new Error("Output executable path is required (pass output-exe or -o/--output)");
+  if (outputPath == null) {
+    throw new Error(
+      "Output executable path required (pass output-exe or -o/--output)"
+    );
+  }
 
-  if (input.kind === "kvm") {
+  if (input.kind === "pkir") {
+    const pkir = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    compilePKIRToExecutable(pkir, outputPath, {
+      entry: relation,
+      inputPattern,
+      clangOpt,
+      runtimeMode
+    });
+  } else if (input.kind === "kvm") {
     const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
-    compileKVMToExecutable(kvm, outputPath, { inputPattern });
+    compileKVMToExecutable(kvm, outputPath, {
+      entry: relation,
+      inputPattern,
+      clangOpt,
+      runtimeMode,
+      usePKIR
+    });
   } else {
     const object = await compileProgramInputToObject(input, {
       libraries,
@@ -90,10 +158,15 @@ try {
       stdin
     });
 
-    compileObjectToExecutable(object, outputPath, { inputPattern });
+    compileObjectToExecutable(object, outputPath, {
+      relation: relation || object.main,
+      inputPattern,
+      clangOpt,
+      runtimeMode,
+      usePKIR
+    });
   }
 } catch (error) {
   console.error(error.stack || error.message || String(error));
-  usage();
   exit(1);
 }