@fraczak/k 6.3.3 → 6.5.0

package/harness/persistent.mjs

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import { parseTraceLine } from "./trace.mjs";
+
+export class PersistentExecutable {
+  constructor(exePath, { env = {} } = {}) {
+    this.exePath = exePath;
+    this.child = spawn(exePath, ["--server"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, K_TRACE: "1", ...env }
+    });
+    this.buffer = Buffer.alloc(0);
+    this.pending = [];
+    this.stderr = [];
+    this.stderrRemainder = "";
+    this.traces = [];
+    this.waitingForTrace = [];
+    this.closed = false;
+    this.currentProfile = null;
+    this.lastProfile = null;
+
+    this.child.stdout.on("data", chunk => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      this.drainOutput();
+    });
+
+    this.child.stderr.on("data", chunk => {
+      this.stderr.push(chunk);
+      this.stderrRemainder += chunk.toString("utf8");
+      let idx;
+      while ((idx = this.stderrRemainder.indexOf("\n")) !== -1) {
+        const line = this.stderrRemainder.slice(0, idx).trim();
+        this.stderrRemainder = this.stderrRemainder.slice(idx + 1);
+        if (line === "K_PROFILE_BEGIN") {
+          this.currentProfile = {};
+        } else if (line.startsWith("K_FUNC_CALL ") && this.currentProfile) {
+          const match = line.match(/^K_FUNC_CALL name=(\S+) count=(\d+)$/);
+          if (match) this.currentProfile[match[1]] = Number(match[2]);
+        } else if (line === "K_PROFILE_END") {
+          this.lastProfile = this.currentProfile;
+          this.currentProfile = null;
+        } else if (line.startsWith("K_TRACE_PHASES ")) {
+          const parsed = parseTraceLine(line);
+          if (parsed) {
+            if (this.lastProfile) {
+              parsed.profile = this.lastProfile;
+              this.lastProfile = null;
+            }
+            if (this.waitingForTrace.length > 0) {
+              const item = this.waitingForTrace.shift();
+              item.resolve({ payload: item.payload, trace: parsed });
+            } else {
+              this.traces.push(parsed);
+            }
+          }
+        }
+      }
+    });
+
+    this.child.on("error", error => this.fail(error));
+    this.child.on("close", status => {
+      this.closed = true;
+      if (status !== 0) {
+        this.fail(new Error(`${this.exePath} --server failed with status ${status}\n${Buffer.concat(this.stderr).toString("utf8")}`.trim()));
+      } else if (this.pending.length > 0 || this.waitingForTrace.length > 0) {
+        this.fail(new Error(`${this.exePath} --server closed with pending request(s)`));
+      }
+    });
+  }
+
+  fail(error) {
+    while (this.pending.length > 0) this.pending.shift().reject(error);
+    while (this.waitingForTrace.length > 0) this.waitingForTrace.shift().reject(error);
+  }
+
+  drainOutput() {
+    while (this.pending.length > 0 && this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32BE(0);
+      if (this.buffer.length < 4 + length) return;
+      const payload = Buffer.from(this.buffer.subarray(4, 4 + length));
+      this.buffer = this.buffer.subarray(4 + length);
+      const req = this.pending.shift();
+      if (!req.includeTrace) {
+        req.resolve(payload);
+      } else if (this.traces.length > 0) {
+        const trace = this.traces.shift();
+        req.resolve({ payload, trace });
+      } else {
+        this.waitingForTrace.push({ payload, resolve: req.resolve, reject: req.reject });
+      }
+    }
+  }
+
+  request(payloadWire) {
+    if (this.closed) return Promise.reject(new Error(`${this.exePath} --server is closed`));
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject, includeTrace: false });
+      const lengthHeader = Buffer.alloc(4);
+      lengthHeader.writeUInt32BE(payloadWire.length, 0);
+      this.child.stdin.write(Buffer.concat([lengthHeader, payloadWire]));
+    });
+  }
+
+  requestWithTrace(payloadWire) {
+    if (this.closed) return Promise.reject(new Error(`${this.exePath} --server is closed`));
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject, includeTrace: true });
+      const lengthHeader = Buffer.alloc(4);
+      lengthHeader.writeUInt32BE(payloadWire.length, 0);
+      this.child.stdin.write(Buffer.concat([lengthHeader, payloadWire]));
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      this.child.stdin.end();
+    } catch {}
+    this.child.kill();
+  }
+}

package/harness/registry.mjs

@@ -0,0 +1,44 @@
+import { NativeAdapter } from "./adapters/native.mjs";
+import { KVMAdapter } from "./adapters/kvm.mjs";
+import { WasmAdapter } from "./adapters/wasm.mjs";
+import { ARM64Adapter } from "./adapters/arm64.mjs";
+import { LLVMAdapter } from "./adapters/llvm.mjs";
+
+export function createRegistry(config = {}) {
+  const adapters = new Map();
+
+  function register(id, factory) {
+    adapters.set(id, factory);
+  }
+
+  register("native-aware", () => new NativeAdapter("aware", config.state));
+  register("native-free", () => new NativeAdapter("free", config.state));
+  register("kvm", () => new KVMAdapter(config.state));
+  register("wasm", () => new WasmAdapter(config.wasm || {}));
+  register("wasm-in-process", () => new WasmAdapter({ id: "wasm-in-process", mode: "in-process", ...(config.wasm || {}) }));
+  register("arm64", () => new ARM64Adapter(config.arm64 || {}));
+  register("llvm", () => new LLVMAdapter(config.llvm || {}));
+
+  return {
+    getBackend(id) {
+      const factory = adapters.get(id);
+      if (!factory) throw new Error(`Unknown backend ID: '${id}'`);
+      return factory();
+    },
+
+    listBackendIds() {
+      return [...adapters.keys()];
+    },
+
+    getAvailableBackends() {
+      const list = [];
+      for (const [id, factory] of adapters.entries()) {
+        const backend = factory();
+        if (backend.isAvailable()) {
+          list.push(backend);
+        }
+      }
+      return list;
+    }
+  };
+}

package/harness/suite.mjs

@@ -0,0 +1,257 @@
+import { createRegistry } from "./registry.mjs";
+import { safeDeepEqual, average, min, max, stdDev, makeCacheDir } from "./util.mjs";
+import { averageTrace } from "./trace.mjs";
+
+export class BenchmarkSuite {
+  constructor(name, options = {}) {
+    this.name = name;
+    this.options = options;
+    this.cases = [];
+    this.state = options.state || null;
+    this.registry = createRegistry({ state: this.state, ...options });
+    this.compiled = new Map(); // backendId -> Array<compiledCase>
+    this.runners = new Map();  // backendId -> runner
+    this.cacheDir = options.cacheDir || makeCacheDir(`k-harness-${name}-`);
+  }
+
+  addCase(testCase) {
+    this.cases.push(testCase);
+  }
+
+  getBackend(id) {
+    return this.registry.getBackend(id);
+  }
+
+  getAvailableBackendIds() {
+    return this.registry.getAvailableBackends().map(b => b.id);
+  }
+
+  async compileAll(backendIds, options = {}) {
+    const results = {};
+    for (const id of backendIds) {
+      const backend = this.getBackend(id);
+      if (!backend.isAvailable()) {
+        results[id] = { status: "unavailable", reason: "not supported on this platform" };
+        continue;
+      }
+
+      const compiledCases = [];
+      let allOk = true;
+      let failureError = null;
+
+      for (const tc of this.cases) {
+        const res = await backend.compile(tc, {
+          cacheDir: this.cacheDir,
+          profile: options.profile,
+          trace: options.trace
+        });
+        if (res.status !== "ok") {
+          allOk = false;
+          failureError = res.error;
+        }
+        compiledCases.push({ ...tc, ...res });
+      }
+
+      this.compiled.set(id, compiledCases);
+      results[id] = {
+        status: allOk ? "ok" : "failed",
+        total: this.cases.length,
+        ready: compiledCases.filter(c => c.status === "ok").length,
+        error: failureError
+      };
+    }
+    return results;
+  }
+
+  async getRunner(backendId) {
+    let runner = this.runners.get(backendId);
+    if (!runner) {
+      const backend = this.getBackend(backendId);
+      const compiledCases = this.compiled.get(backendId);
+      if (!compiledCases) throw new Error(`Backend '${backendId}' not compiled yet`);
+      runner = await backend.createRunner(compiledCases);
+      this.runners.set(backendId, runner);
+    }
+    return runner;
+  }
+
+  async checkConformance(backendIds) {
+    const baselineId = backendIds.includes("native-aware")
+      ? "native-aware"
+      : (backendIds.includes("kvm") ? "kvm" : backendIds[0]);
+
+    const results = [];
+
+    for (let i = 0; i < this.cases.length; i++) {
+      const tc = this.cases[i];
+      const caseResult = {
+        name: tc.name || tc.op,
+        conformance: {},
+        passed: true
+      };
+
+      let baselineVal = tc.expectedVal;
+
+      for (const id of backendIds) {
+        const compiledCases = this.compiled.get(id);
+        if (!compiledCases || compiledCases[i]?.status !== "ok") {
+          caseResult.conformance[id] = { status: "compile_failed" };
+          caseResult.passed = false;
+          continue;
+        }
+
+        const runner = await this.getRunner(id);
+        try {
+          const res = await runner.runSingle(compiledCases[i], { trace: false });
+          const val = res.outputVal;
+
+          if (id === baselineId && baselineVal == null) {
+            baselineVal = val;
+          }
+
+          const matches = baselineVal == null || safeDeepEqual(val, baselineVal);
+          caseResult.conformance[id] = {
+            status: matches ? "ok" : "mismatch",
+            val
+          };
+          if (!matches) caseResult.passed = false;
+        } catch (err) {
+          caseResult.conformance[id] = {
+            status: "error",
+            error: err.message
+          };
+          caseResult.passed = false;
+        }
+      }
+
+      results.push(caseResult);
+    }
+
+    return results;
+  }
+
+  async runTrace(backendIds, reps = 5) {
+    const traceResults = [];
+
+    for (let i = 0; i < this.cases.length; i++) {
+      const tc = this.cases[i];
+      const caseTrace = {
+        op: tc.op || tc.name,
+        label: tc.label || ""
+      };
+
+      for (const id of backendIds) {
+        const compiledCases = this.compiled.get(id);
+        if (!compiledCases || compiledCases[i]?.status !== "ok") continue;
+
+        const runner = await this.getRunner(id);
+        const samples = [];
+
+        // Warmup 2 reps
+        for (let w = 0; w < 2; w++) {
+          await runner.runSingle(compiledCases[i], { trace: true });
+        }
+
+        // Measured reps
+        for (let r = 0; r < reps; r++) {
+          const res = await runner.runSingle(compiledCases[i], { trace: true });
+          if (res.trace) samples.push(res.trace);
+        }
+
+        caseTrace[id] = averageTrace(samples);
+      }
+
+      traceResults.push(caseTrace);
+    }
+
+    return traceResults;
+  }
+
+  async runProfile(backendIds) {
+    const profileResults = [];
+
+    for (let i = 0; i < this.cases.length; i++) {
+      const tc = this.cases[i];
+      const caseProfile = {
+        op: tc.op || tc.name
+      };
+
+      for (const id of backendIds) {
+        const compiledCases = this.compiled.get(id);
+        if (!compiledCases || compiledCases[i]?.status !== "ok") continue;
+
+        const runner = await this.getRunner(id);
+        const res = await runner.runSingle(compiledCases[i], { profile: true });
+        if (res.profile) {
+          caseProfile[id] = res.profile;
+        }
+      }
+
+      profileResults.push(caseProfile);
+    }
+
+    return profileResults;
+  }
+
+  async runBenchmark(backendIds, { warmup = 1, iterations = 3 } = {}) {
+    const benchResults = [];
+
+    for (const id of backendIds) {
+      const compiledCases = this.compiled.get(id);
+      const readyCases = (compiledCases || []).filter(c => c.status === "ok");
+      if (!readyCases || readyCases.length === 0) continue;
+
+      const runner = await this.getRunner(id);
+      const backend = this.getBackend(id);
+
+      // Warmup
+      if (warmup > 0) {
+        for (let w = 0; w < warmup; w++) {
+          await runner.runBatch(readyCases);
+        }
+      }
+
+      // Measured iterations
+      const iterRes = await runner.runIterations(readyCases, iterations);
+
+      // Sample pure evaluation time (Phase 4) across cases
+      let pureEvalMs = null;
+      try {
+        let totalEvalNs = 0;
+        let count = 0;
+        for (const c of readyCases) {
+          const sample = await runner.runSingle(c, { trace: true });
+          if (sample?.trace?.evalNs != null) {
+            totalEvalNs += sample.trace.evalNs;
+            count++;
+          }
+        }
+        if (count > 0 && totalEvalNs > 0) {
+          pureEvalMs = totalEvalNs / 1000000;
+        }
+      } catch {}
+
+      benchResults.push({
+        id,
+        name: backend.getLaneName(),
+        totalNs: iterRes.totalNs,
+        perIterationMs: iterRes.perIterationMs,
+        pureEvalMs,
+        iterationTimes: iterRes.iterationTimes,
+        minMs: min(iterRes.iterationTimes),
+        maxMs: max(iterRes.iterationTimes),
+        stdDevMs: stdDev(iterRes.iterationTimes),
+        samples: iterations
+      });
+    }
+
+    return benchResults;
+  }
+
+  async close() {
+    for (const runner of this.runners.values()) {
+      await runner.close();
+    }
+    this.runners.clear();
+  }
+}

package/harness/suites/poly.mjs

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  codes,
+  decodeWire,
+  encodeToWire,
+  executeKVM,
+  lowerToKVM,
+  run,
+  run_converged,
+  valueForCode,
+  Value
+} from "../../backend-api.mjs";
+import { compileLibrary, loadLibrary, decodeObject, compileObjectBuffer } from "../../object.mjs";
+import { parse as parseIntValue } from "../../codecs/int.mjs";
+import { BenchmarkSuite } from "../suite.mjs";
+import { inputPatternForObjectRelation } from "../../backends/llvm/src/executable.mjs";
+import { prepareRelation } from "../../backends/llvm/tests/perf-support.mjs";
+
+export async function createPolySuite({ listLength = 40, cacheDir = null } = {}) {
+  const ops = ["reverse", "concat", "split_by", "get_nth", "length"];
+  const benchNames = Object.fromEntries(ops.map(op => [op, `bench_${op}`]));
+
+  const arithmeticsPath = fileURLToPath(import.meta.resolve("../../Examples/arithmetics.k"));
+  const arithmeticsSource = fs.readFileSync(arithmeticsPath, "utf8");
+  const arithmeticsLib = loadLibrary(compileLibrary(arithmeticsSource, { source: arithmeticsPath }));
+
+  const polyPath = fileURLToPath(import.meta.resolve("../../Examples/poly.k"));
+  const polySource = fs.readFileSync(polyPath, "utf8");
+
+  function buildExportPreamble(exports, libraries) {
+    const aliasMap = {};
+    for (const lib of libraries) {
+      for (const [name, hash] of Object.entries(lib.relAlias || {})) {
+        if (name !== "__main__") aliasMap[name] = hash;
+      }
+    }
+    const lines = [];
+    for (const spec of exports) {
+      const [libName, localName] = spec.includes(":") ? spec.split(":", 2) : [spec, spec];
+      const hash = aliasMap[libName];
+      if (!hash) throw new Error(`--export: '${libName}' not found in loaded libraries`);
+      const body = hash.startsWith("@") ? hash.slice(1) : hash;
+      lines.push(`${localName} = @${body};`);
+    }
+    return lines.join("\n") + "\n";
+  }
+
+  const neededExports = ["0", "int", "inc", "dec", "nat", "zero_int?", "nil", "cons", "car", "cdr"];
+  const exportPreamble = buildExportPreamble(neededExports, [arithmeticsLib]);
+  const polyLib = loadLibrary(compileLibrary(exportPreamble + polySource, {
+    source: polyPath,
+    libraries: [arithmeticsLib]
+  }));
+
+  const state = {
+    codes: { ...arithmeticsLib.codes, ...polyLib.codes },
+    rels: { ...arithmeticsLib.rels, ...polyLib.rels },
+    typeAliases: {},
+    relAliases: { ...polyLib.relAlias },
+    meta: { ...arithmeticsLib.meta, ...polyLib.meta }
+  };
+
+  for (const [hash, entry] of Object.entries(arithmeticsLib.meta)) {
+    if (entry.type === "code") {
+      for (const origin of entry.origins || []) {
+        if (origin.name) state.typeAliases[origin.name] = hash;
+      }
+    }
+  }
+
+  for (const op of ops) {
+    state.relAliases[benchNames[op]] = polyLib.relAlias[op];
+  }
+
+  function intValue(text) {
+    return valueForCode(parseIntValue(text), state.typeAliases.int, codes.find);
+  }
+
+  function makeList(elements) {
+    let curr = Value.variant("nil", Value.product({}));
+    for (let i = elements.length - 1; i >= 0; i--) {
+      curr = Value.variant("cons", Value.product({
+        car: elements[i],
+        cdr: curr
+      }));
+    }
+    return curr;
+  }
+
+  const relations = {};
+  for (const op of ops) {
+    const name = benchNames[op];
+    relations[op] = prepareRelation(state, name);
+  }
+  codes.load(state.codes);
+
+  const intElements = Array.from({ length: listLength }, (_, i) => intValue(String(i + 1)));
+  const fullList = makeList(intElements);
+  const halfLen = Math.floor(listLength / 2);
+  const firstHalf = makeList(intElements.slice(0, halfLen));
+  const secondHalf = makeList(intElements.slice(halfLen));
+  const midIdx = intValue(String(halfLen));
+
+  const rawCases = [
+    { op: "reverse", label: `len ${listLength}`, inputVal: fullList },
+    { op: "concat", label: `2x len ${halfLen}`, inputVal: Value.product({ xs: firstHalf, ys: secondHalf }) },
+    { op: "split_by", label: `at ${halfLen} of ${listLength}`, inputVal: Value.product({ n: midIdx, xs: fullList }) },
+    { op: "get_nth", label: `idx ${halfLen} of ${listLength}`, inputVal: Value.product({ n: midIdx, xs: fullList }) },
+    { op: "length", label: `len ${listLength}`, inputVal: fullList }
+  ];
+
+  const suite = new BenchmarkSuite("poly", { state, cacheDir });
+
+  for (const tc of rawCases) {
+    const relation = relations[tc.op];
+    let expected;
+    try {
+      run.defs = state;
+      run_converged.defs = state;
+      expected = run_converged(codes.find, relation.relDef.def, tc.inputVal, relation.relDef.typePatternGraph);
+    } catch {
+      expected = executeKVM(relation.kvmFunc, tc.inputVal, {
+        rels: state.rels,
+        codes: state.codes,
+        options: { envelopeFree: true }
+      });
+    }
+
+    const inferredPat = inputPatternForObjectRelation(relation.object, relation.relationName);
+    const inputWire = encodeToWire(tc.inputVal, inferredPat);
+    const inputPattern = decodeWire(inputWire).pattern;
+
+    const outWire = encodeToWire(expected);
+    const outputPattern = decodeWire(outWire).pattern;
+
+    suite.addCase({
+      op: tc.op,
+      label: tc.label,
+      relName: relation.relationName,
+      relHash: relation.relHash,
+      relDef: relation.relDef,
+      object: relation.object,
+      kvmFunc: relation.kvmFunc,
+      inputVal: tc.inputVal,
+      inputWire,
+      inputPattern,
+      outputPattern,
+      expectedVal: expected
+    });
+  }
+
+  return suite;
+}

package/harness/trace.mjs

@@ -0,0 +1,50 @@
+// 7-phase trace protocol and aggregation
+
+export const PHASES = [
+  { name: "1. IPC Read (Pipe In)", key: "ipcReadNs" },
+  { name: "2. Wire Decode & Validate", key: "decodeNs" },
+  { name: "3. Flat Input Prep (Arena)", key: "flatInNs" },
+  { name: "4. Pure Evaluation", key: "evalNs" },
+  { name: "5. Flat Output Prep (Arena)", key: "flatOutNs" },
+  { name: "6. Wire Encode", key: "encodeNs" },
+  { name: "7. IPC Write (Pipe Out)", key: "ipcWriteNs" },
+  { name: "Total Request Time", key: "totalNs", isTotal: true }
+];
+
+export function parseTraceLine(line) {
+  const parts = line.trim().split(/\s+/);
+  if (parts[0] !== "K_TRACE_PHASES") return null;
+  const result = {};
+  for (let i = 1; i < parts.length; i++) {
+    const [key, val] = parts[i].split("=");
+    if (!key || val == null) continue;
+    if (key === "backend") {
+      result.backend = val;
+    } else {
+      const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+      result[camelKey] = Number(val);
+    }
+  }
+  return result;
+}
+
+export function averageTrace(samples) {
+  if (!samples || samples.length === 0) return null;
+  const result = {};
+  for (const phase of PHASES) {
+    const key = phase.key;
+    const values = samples.map(s => s[key]).filter(v => v != null && !isNaN(v));
+    if (values.length > 0) {
+      result[key] = values.reduce((sum, v) => sum + v, 0) / values.length;
+    } else {
+      result[key] = 0;
+    }
+  }
+  return result;
+}
+
+export function formatUs(ns) {
+  if (ns == null || ns === 0) return "      -     ";
+  const us = ns / 1000;
+  return `${us.toFixed(2)} µs`.padStart(12);
+}