@fraczak/k 6.3.3 → 6.4.0

package/harness/adapters/native.mjs

@@ -0,0 +1,77 @@
+import {
+  codes,
+  decodeWire,
+  encodeToWire,
+  run,
+  run_converged
+} from "../../backend-api.mjs";
+import { BackendAdapter, BackendRunner } from "../backend.mjs";
+
+class NativeRunner extends BackendRunner {
+  constructor(backendId, mode, state) {
+    super(backendId);
+    this.mode = mode; // "aware" or "free"
+    this.state = state;
+  }
+
+  async runSingle(testCase, options = {}) {
+    const relDef = testCase.relDef;
+    const inputVal = testCase.inputVal;
+    const findCode = codes.find;
+
+    if (this.mode === "free") {
+      run_converged.defs = this.state;
+    }
+
+    const t0 = process.hrtime.bigint();
+    const result = this.mode === "aware"
+      ? run(findCode, relDef.def, inputVal, relDef.typePatternGraph)
+      : run_converged(findCode, relDef.def, inputVal, relDef.typePatternGraph);
+    const t1 = process.hrtime.bigint();
+
+    const evalNs = Number(t1 - t0);
+
+    const trace = options.trace ? {
+      ipcReadNs: 0,
+      decodeNs: 0,
+      flatInNs: 0,
+      evalNs,
+      flatOutNs: 0,
+      encodeNs: 0,
+      ipcWriteNs: 0,
+      totalNs: evalNs
+    } : null;
+
+    return {
+      outputVal: result,
+      trace
+    };
+  }
+}
+
+export class NativeAdapter extends BackendAdapter {
+  constructor(mode = "free", state = null) {
+    const id = mode === "aware" ? "native-aware" : "native-free";
+    const name = mode === "aware" ? "Native JS (Envelope-Aware)" : "Native JS (Envelope-Free)";
+    super(id, name);
+    this.mode = mode;
+    this.state = state;
+  }
+
+  setState(state) {
+    this.state = state;
+  }
+
+  async compile(testCase) {
+    return {
+      status: "ok",
+      relDef: testCase.relDef,
+      inputVal: testCase.inputVal,
+      outputPattern: testCase.outputPattern
+    };
+  }
+
+  async createRunner(compiledCases) {
+    return new NativeRunner(this.id, this.mode, this.state);
+  }
+}

package/harness/adapters/wasm.mjs

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BackendAdapter, BackendRunner } from "../backend.mjs";
+import { PersistentExecutable } from "../persistent.mjs";
+import {
+  compileWasmArtifactFromObject,
+  instantiateWasmArtifact
+} from "../../backends/wasm/src/wasm.mjs";
+import { decodeWire } from "../../backend-api.mjs";
+
+class WasmInProcessRunner extends BackendRunner {
+  constructor(backendId) {
+    super(backendId);
+  }
+
+  async runSingle(testCase, options = {}) {
+    const runner = testCase.runner;
+    if (options.trace) {
+      const res = runner.execute(testCase.inputWire, { trace: true });
+      const decoded = decodeWire(res.outputWire);
+      return {
+        outputWire: res.outputWire,
+        outputVal: decoded.value,
+        outputPattern: decoded.pattern,
+        trace: {
+          ipcReadNs: 0,
+          decodeNs: res.trace.decodeNs,
+          flatInNs: res.trace.flatInNs,
+          evalNs: res.trace.evalNs,
+          flatOutNs: res.trace.flatOutNs,
+          encodeNs: res.trace.encodeNs,
+          ipcWriteNs: 0,
+          totalNs: res.trace.totalNs
+        }
+      };
+    } else {
+      const outWire = runner.execute(testCase.inputWire);
+      const decoded = decodeWire(outWire);
+      return {
+        outputWire: outWire,
+        outputVal: decoded.value,
+        outputPattern: decoded.pattern
+      };
+    }
+  }
+
+  async runBatch(compiledCases) {
+    for (const c of compiledCases) {
+      c.runner.execute(c.inputWire);
+    }
+  }
+
+  async close() {}
+}
+
+class WasmPipeRunner extends BackendRunner {
+  constructor(backendId, servers = new Map()) {
+    super(backendId);
+    this.servers = servers;
+  }
+
+  getServer(exePath) {
+    let server = this.servers.get(exePath);
+    if (!server) {
+      server = new PersistentExecutable(exePath);
+      this.servers.set(exePath, server);
+    }
+    return server;
+  }
+
+  async runSingle(testCase, options = {}) {
+    const server = this.getServer(testCase.exePath);
+    if (options.trace) {
+      const res = await server.requestWithTrace(testCase.inputWire);
+      const decoded = decodeWire(res.payload);
+      return {
+        outputWire: res.payload,
+        outputVal: decoded.value,
+        outputPattern: decoded.pattern,
+        trace: res.trace,
+        profile: res.trace?.profile
+      };
+    } else {
+      const payload = await server.request(testCase.inputWire);
+      const decoded = decodeWire(payload);
+      return {
+        outputWire: payload,
+        outputVal: decoded.value,
+        outputPattern: decoded.pattern
+      };
+    }
+  }
+
+  async runBatch(compiledCases) {
+    for (const c of compiledCases) {
+      const server = this.getServer(c.exePath);
+      await server.request(c.inputWire);
+    }
+  }
+
+  async close() {
+    for (const server of this.servers.values()) {
+      server.close();
+    }
+    this.servers.clear();
+  }
+}
+
+export class WasmAdapter extends BackendAdapter {
+  constructor(options = {}) {
+    const mode = options.mode || "pipe"; // "pipe" or "in-process"
+    const id = options.id || (mode === "in-process" ? "wasm-in-process" : "wasm");
+    const name = options.name || `WebAssembly (${mode === "pipe" ? "persistent pipe" : "in-process"})`;
+    super(id, name, options);
+    this.mode = mode;
+  }
+
+  isAvailable() {
+    return true; // Runs in Node.js via WABT / V8 Wasm
+  }
+
+  async compile(testCase, options = {}) {
+    const cacheDir = options.cacheDir || path.join(process.cwd(), ".cache");
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const name = testCase.op || testCase.relName || "case";
+    const wasmPath = path.join(cacheDir, `harness_wasm_${name}.wasm`);
+    const exePath = path.join(cacheDir, `harness_wasm_${name}.exe`);
+
+    try {
+      const entry = testCase.relHash || testCase.relName || testCase.op;
+      const wasmBuf = await compileWasmArtifactFromObject(testCase.object, {
+        entry,
+        profile: Boolean(options.profile)
+      });
+      fs.writeFileSync(wasmPath, wasmBuf);
+
+      const runBin = fileURLToPath(import.meta.resolve("../../backends/wasm/bin/k-wasm-run.mjs"));
+      fs.writeFileSync(exePath, `#!/bin/sh\nexec node "${runBin}" "${wasmPath}" "$@"\n`, { mode: 0o755 });
+
+      let inProcessRunner = null;
+      if (this.mode === "in-process") {
+        inProcessRunner = await instantiateWasmArtifact(wasmBuf);
+      }
+
+      return {
+        status: "ok",
+        wasmPath,
+        exePath,
+        runner: inProcessRunner,
+        inputWire: testCase.inputWire,
+        inputVal: testCase.inputVal,
+        outputPattern: testCase.outputPattern
+      };
+    } catch (error) {
+      return {
+        status: "failed",
+        error: error.stack || error.message || String(error)
+      };
+    }
+  }
+
+  async createRunner(compiledCases) {
+    if (this.mode === "in-process") {
+      return new WasmInProcessRunner(this.id);
+    }
+    return new WasmPipeRunner(this.id);
+  }
+}

package/harness/backend.mjs

@@ -0,0 +1,95 @@
+// Base class for all backend adapters
+
+export class BackendAdapter {
+  constructor(id, name, options = {}) {
+    this.id = id;
+    this.name = name;
+    this.options = options;
+  }
+
+  isAvailable() {
+    return true;
+  }
+
+  getLaneName() {
+    return this.name;
+  }
+
+  /**
+   * Compiles or prepares a test case for execution.
+   * @param {object} testCase
+   * @param {object} options
+   * @returns {Promise<object>} compiled artifact/handle
+   */
+  async compile(testCase, options = {}) {
+    throw new Error(`compile() not implemented for backend '${this.id}'`);
+  }
+
+  /**
+   * Creates a runner for a suite of compiled cases.
+   * @param {Array<object>} compiledCases
+   * @param {object} options
+   * @returns {Promise<BackendRunner>}
+   */
+  async createRunner(compiledCases, options = {}) {
+    throw new Error(`createRunner() not implemented for backend '${this.id}'`);
+  }
+}
+
+export class BackendRunner {
+  constructor(backendId, options = {}) {
+    this.backendId = backendId;
+    this.options = options;
+  }
+
+  /**
+   * Run a single case.
+   * @param {object} compiledCase
+   * @param {object} options { trace?: boolean, profile?: boolean }
+   * @returns {Promise<{ outputWire?: Buffer, outputVal?: any, trace?: object, profile?: object }>}
+   */
+  async runSingle(compiledCase, options = {}) {
+    throw new Error(`runSingle() not implemented for runner '${this.backendId}'`);
+  }
+
+  /**
+   * Run all cases once.
+   * @param {Array<object>} compiledCases
+   * @returns {Promise<void>}
+   */
+  async runBatch(compiledCases) {
+    for (const c of compiledCases) {
+      await this.runSingle(c);
+    }
+  }
+
+  /**
+   * Run timed iterations over all cases.
+   * @param {Array<object>} compiledCases
+   * @param {number} iterations
+   * @returns {Promise<{ totalNs: number, perIterationMs: number, iterationTimes: number[] }>}
+   */
+  async runIterations(compiledCases, iterations) {
+    const iterationTimes = [];
+    let totalNs = 0;
+
+    for (let i = 0; i < iterations; i++) {
+      const t0 = process.hrtime.bigint();
+      await this.runBatch(compiledCases);
+      const t1 = process.hrtime.bigint();
+      const diffNs = Number(t1 - t0);
+      totalNs += diffNs;
+      iterationTimes.push(diffNs / 1000000);
+    }
+
+    return {
+      totalNs,
+      perIterationMs: iterations > 0 ? (totalNs / iterations / 1000000) : 0,
+      iterationTimes
+    };
+  }
+
+  async close() {
+    // Optional cleanup
+  }
+}

package/harness/cli.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { createPolySuite } from "./suites/poly.mjs";
+import {
+  formatPhaseTable,
+  formatProfileTable,
+  formatBenchmarkTable
+} from "./format.mjs";
+
+async function main() {
+  const options = {
+    suite: { type: "string", default: "poly" },
+    backends: { type: "string", short: "b" },
+    iterations: { type: "string", short: "i", default: "3" },
+    warmup: { type: "string", short: "w", default: "1" },
+    trace: { type: "boolean", default: false },
+    profile: { type: "boolean", default: false },
+    conformance: { type: "boolean", default: false },
+    all: { type: "boolean", default: false },
+    format: { type: "string", default: "text" },
+    listLength: { type: "string", default: "40" },
+    help: { type: "boolean", short: "h", default: false }
+  };
+
+  const { values } = parseArgs({ options, allowPositionals: true });
+
+  if (values.help) {
+    console.log(`Usage: node harness/cli.mjs [options]
+
+Options:
+  --suite <name>       Benchmark suite: poly (default: poly)
+  -b, --backends <csv> Comma-separated backends (default: all available)
+  -i, --iterations <n> Measured iterations (default: 3)
+  -w, --warmup <n>     Warmup iterations (default: 1)
+  --trace              Measure 7-phase nanosecond execution timing
+  --profile            Measure per-function call count profiling
+  --conformance        Verify output equality across all backends
+  --all                Run conformance, profile, trace, and benchmark
+  --format <fmt>       Output format: text, json (default: text)
+  --listLength <n>     Workload size for list operations (default: 40)
+  -h, --help           Show this help message
+`);
+    return;
+  }
+
+  const listLength = parseInt(values.listLength, 10);
+  const iterations = parseInt(values.iterations, 10);
+  const warmup = parseInt(values.warmup, 10);
+  const doTrace = values.trace || values.all;
+  const doProfile = values.profile || values.all;
+  const doConformance = values.conformance || values.all;
+  const doBenchmark = !values.trace && !values.profile && !values.conformance ? true : values.all;
+
+  console.log(`==> Initializing test suite: ${values.suite} (listLength=${listLength})...`);
+  let suite;
+  if (values.suite === "poly") {
+    suite = await createPolySuite({ listLength });
+  } else {
+    throw new Error(`Unknown suite: ${values.suite}`);
+  }
+
+  const available = suite.getAvailableBackendIds();
+  const selectedBackends = values.backends
+    ? values.backends.split(",").map(b => b.trim()).filter(Boolean)
+    : available;
+
+  console.log(`==> Target backends: ${selectedBackends.join(", ")}`);
+  console.log(`==> Compiling test cases for backends...`);
+  const compileResults = await suite.compileAll(selectedBackends, {
+    profile: doProfile,
+    trace: doTrace
+  });
+
+  for (const [id, res] of Object.entries(compileResults)) {
+    console.log(`  [${id}] ${res.status}: ${res.ready}/${res.total} cases ready`);
+    if (res.status !== "ok" && res.error) {
+      console.log(`      Error: ${res.error.split("\n")[0]}`);
+    }
+  }
+
+  const readyBackends = selectedBackends.filter(id => compileResults[id]?.status === "ok");
+
+  try {
+    // 1. Conformance
+    if (doConformance) {
+      console.log("\n==> Running Conformance Verification...");
+      const confResults = await suite.checkConformance(readyBackends);
+      let allPassed = true;
+      for (const r of confResults) {
+        const statuses = Object.entries(r.conformance).map(([id, c]) => `${id}:${c.status}`).join(" ");
+        console.log(`  ${r.name.padEnd(15)} -> ${statuses}`);
+        if (!r.passed) allPassed = false;
+      }
+      console.log(allPassed ? "  All backends conform!" : "  Conformance failure detected!");
+    }
+
+    // 2. Profile
+    if (doProfile) {
+      console.log("\n==> Running Per-Function Call Profiling...");
+      const profResults = await suite.runProfile(readyBackends);
+      console.log(formatProfileTable(profResults, readyBackends));
+    }
+
+    // 3. Trace
+    if (doTrace) {
+      console.log("\n==> Running 7-Phase Execution Tracing...");
+      const traceResults = await suite.runTrace(readyBackends, 3);
+      console.log(formatPhaseTable(traceResults, readyBackends));
+    }
+
+    // 4. Benchmark
+    if (doBenchmark) {
+      console.log(`\n==> Running Benchmark (${iterations} iterations, ${warmup} warmup)...`);
+      const benchResults = await suite.runBenchmark(readyBackends, { warmup, iterations });
+      if (values.format === "json") {
+        console.log(JSON.stringify(benchResults, null, 2));
+      } else {
+        console.log(formatBenchmarkTable(benchResults));
+      }
+    }
+  } finally {
+    await suite.close();
+  }
+}
+
+main().catch(err => {
+  console.error("Harness error:", err);
+  process.exit(1);
+});

package/harness/format.mjs

@@ -0,0 +1,95 @@
+import { PHASES, formatUs } from "./trace.mjs";
+
+export function formatPhaseTable(phaseResults, backendIds = ["arm64", "llvm", "wasm", "kvm"]) {
+  const lines = [];
+
+  for (const item of phaseResults) {
+    lines.push(`\n--- Operation: ${item.op || item.name} (${item.label || ""}) ---`);
+    const header = ["Phase".padEnd(25), ...backendIds.map(id => id.padEnd(14))].join(" | ");
+    lines.push(header);
+    lines.push("-".repeat(header.length));
+
+    for (const phase of PHASES) {
+      if (phase.isTotal) {
+        lines.push("-".repeat(header.length));
+      }
+      const pName = phase.name.padEnd(25);
+      const cols = backendIds.map(id => {
+        const val = item[id]?.[phase.key];
+        return formatUs(val).padEnd(14);
+      });
+      lines.push([pName, ...cols].join(" | "));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function formatProfileTable(profileResults, backendIds = ["arm64", "wasm", "kvm"]) {
+  const lines = [];
+
+  for (const item of profileResults) {
+    lines.push(`\nFunction Call Profile: ${item.op || item.name}`);
+    const header = ["Function Name".padEnd(30), ...backendIds.map(id => `${id} Calls`.padEnd(18))].join(" | ");
+    lines.push(header);
+    lines.push("-".repeat(header.length));
+
+    const funcNames = new Set();
+    for (const id of backendIds) {
+      const prof = item[id] || {};
+      for (const fn of Object.keys(prof)) funcNames.add(fn);
+    }
+
+    const sortedFuncs = [...funcNames].sort();
+    const totals = Object.fromEntries(backendIds.map(id => [id, 0]));
+
+    for (const fn of sortedFuncs) {
+      const rowCols = backendIds.map(id => {
+        const count = item[id]?.[fn];
+        if (count != null) {
+          totals[id] += count;
+          return String(count).padStart(18);
+        }
+        return " - ".padStart(18);
+      });
+      lines.push([fn.padEnd(30), ...rowCols].join(" | "));
+    }
+
+    lines.push("-".repeat(header.length));
+    const totalRow = backendIds.map(id => String(totals[id]).padStart(18));
+    lines.push(["Total Calls".padEnd(30), ...totalRow].join(" | "));
+  }
+
+  return lines.join("\n");
+}
+
+export function formatBenchmarkTable(benchResults) {
+  const lines = [];
+  const hasPureEval = benchResults.some(r => r.pureEvalMs != null);
+  const header = [
+    "Backend".padEnd(35),
+    "Mean (ms/iter)".padStart(15),
+    ...(hasPureEval ? ["Pure Eval (ms)".padStart(15)] : []),
+    "Min (ms)".padStart(12),
+    "Max (ms)".padStart(12),
+    "Samples".padStart(10)
+  ].join(" | ");
+
+  lines.push(header);
+  lines.push("-".repeat(header.length));
+
+  for (const res of benchResults) {
+    const name = (res.name || res.id).padEnd(35);
+    const mean = (res.perIterationMs != null ? res.perIterationMs.toFixed(3) : "N/A").padStart(15);
+    const pureEval = hasPureEval
+      ? (res.pureEvalMs != null ? res.pureEvalMs.toFixed(3) : "-").padStart(15)
+      : null;
+    const min = (res.minMs != null ? res.minMs.toFixed(3) : "-").padStart(12);
+    const max = (res.maxMs != null ? res.maxMs.toFixed(3) : "-").padStart(12);
+    const samples = (res.samples != null ? String(res.samples) : "0").padStart(10);
+    const cols = [name, mean, ...(pureEval ? [pureEval] : []), min, max, samples];
+    lines.push(cols.join(" | "));
+  }
+
+  return lines.join("\n");
+}

package/harness/index.mjs

@@ -0,0 +1,25 @@
+export { BenchmarkSuite } from "./suite.mjs";
+export { createRegistry } from "./registry.mjs";
+export { BackendAdapter, BackendRunner } from "./backend.mjs";
+export { PersistentExecutable } from "./persistent.mjs";
+export {
+  safeDeepEqual,
+  toPlainObject,
+  average,
+  stdDev,
+  min,
+  max,
+  formatTiming,
+  makeCacheDir
+} from "./util.mjs";
+export {
+  PHASES,
+  parseTraceLine,
+  averageTrace,
+  formatUs
+} from "./trace.mjs";
+export {
+  formatPhaseTable,
+  formatProfileTable,
+  formatBenchmarkTable
+} from "./format.mjs";