@fraczak/k 7.0.1 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/DOCS/BIG_PICTURE.md +5 -5
  3. package/DOCS/FILE_FORMATS.md +241 -18
  4. package/DOCS/OBJECT_FILE_AND_PATTERN.md +9 -9
  5. package/DOCS/PATTERNS.md +3 -3
  6. package/DOCS/POLYMORPHIC_IR.md +104 -0
  7. package/DOCS/PROFILING_AND_TRACING.md +60 -72
  8. package/DOCS/REPL.md +3 -3
  9. package/DOCS/book/03-types-as-finite-automata.md +4 -4
  10. package/DOCS/book/06-values-in-memory.md +9 -9
  11. package/DOCS/book/08-operational-semantics-and-execution.md +1 -1
  12. package/DOCS/book/09-compiler-architecture.md +2 -2
  13. package/DOCS/book/10-from-ast-to-intermediate-representation.md +2 -2
  14. package/DOCS/book/14-canonical-serialization.md +1 -1
  15. package/Examples/arithmetics.k +2 -2
  16. package/Examples/bnat.k +1 -1
  17. package/Examples/karatsuba-mult.k +2 -2
  18. package/JOURNAL.md +288 -0
  19. package/README.md +13 -10
  20. package/access-table.mjs +343 -0
  21. package/backend-api.mjs +18 -0
  22. package/backends/llvm/README.md +20 -21
  23. package/backends/llvm/bin/k-llvm-build.mjs +105 -32
  24. package/backends/llvm/bin/k-llvm-compile.mjs +63 -24
  25. package/backends/llvm/bin/k-llvm.mjs +292 -0
  26. package/backends/llvm/runtime/krt.c +41 -0
  27. package/backends/llvm/runtime/krt.h +2 -0
  28. package/backends/llvm/src/cli.mjs +95 -17
  29. package/backends/llvm/src/executable.mjs +132 -15
  30. package/backends/llvm/src/kvm2llvm.mjs +50 -23
  31. package/backends/llvm/src/llvm.mjs +133 -20
  32. package/backends/llvm/tests/integration.sh +11 -11
  33. package/backends/llvm/{bin → tests}/k-llvm-run.mjs +48 -22
  34. package/backends/llvm/tests/perf-support.mjs +25 -58
  35. package/backends/llvm/tests/test-llvm.mjs +25 -4
  36. package/backends/wasm/bin/k-wasm-compile.mjs +46 -20
  37. package/backends/wasm/bin/k-wasm-run.mjs +61 -20
  38. package/backends/wasm/bin/k-wasm.mjs +47 -13
  39. package/backends/wasm/src/cli.mjs +141 -19
  40. package/backends/wasm/src/wasm.mjs +132 -24
  41. package/backends/wasm/tests/test-wasm.mjs +5 -5
  42. package/browser/repl-browser.mjs +16 -5
  43. package/browser/vfs-data.mjs +5 -5
  44. package/codecs/k-parse.mjs +29 -8
  45. package/codecs/k-print.mjs +22 -6
  46. package/codecs/runtime/codec-sdk.mjs +8 -4
  47. package/codecs/show.mjs +20 -6
  48. package/core.k +8 -8
  49. package/harness/format.mjs +2 -2
  50. package/harness/registry.mjs +0 -2
  51. package/k.mjs +56 -16
  52. package/kir.mjs +200 -75
  53. package/kvm.mjs +49 -12
  54. package/objects/compile.mjs +37 -23
  55. package/objects/decompile.mjs +40 -10
  56. package/objects/extract-aliases.mjs +44 -14
  57. package/objects/inspect.mjs +19 -14
  58. package/objects/validate.mjs +18 -11
  59. package/package.json +10 -7
  60. package/pkir.mjs +772 -0
  61. package/repl.mjs +36 -18
  62. package/scripts/benchmark-idempotency.mjs +12 -8
  63. package/scripts/benchmark.mjs +5 -9
  64. package/scripts/build-repl-html.mjs +16 -4
  65. package/scripts/perf-ieee.mjs +253 -103
  66. package/scripts/perf-int.mjs +585 -297
  67. package/scripts/perf-multiplication.mjs +66 -25
  68. package/scripts/perf-poly.mjs +292 -164
  69. package/scripts/run-tests.mjs +3 -0
  70. package/tests/code-derivation/pattern-envelope.mjs +4 -4
  71. package/tests/test-access-table.mjs +213 -0
  72. package/tests/test-kvm-polymorphic.mjs +2 -2
  73. package/tests/test-pkir.mjs +530 -0
  74. package/tests/test-polymorphic-tdd.mjs +196 -0
  75. package/tests/test-repl-html.mjs +15 -2
  76. package/tests/test-repl.mjs +30 -1
  77. package/backends/arm64/README.md +0 -103
  78. package/backends/arm64/bin/k-arm64-compile.mjs +0 -93
  79. package/backends/arm64/bin/k-arm64-run.mjs +0 -58
  80. package/backends/arm64/bin/k-arm64.mjs +0 -88
  81. package/backends/arm64/scripts/run-tests.mjs +0 -57
  82. package/backends/arm64/src/arm64.mjs +0 -229
  83. package/backends/arm64/src/cli.mjs +0 -155
  84. package/backends/arm64/src/kvm2arm64.mjs +0 -906
  85. package/backends/arm64/src/runtime.c +0 -744
  86. package/backends/arm64/tests/integration.sh +0 -112
  87. package/backends/arm64/tests/test-arm64.mjs +0 -240
  88. package/backends/llvm/bin/k-llvm-jit.mjs +0 -160
  89. package/harness/adapters/arm64.mjs +0 -105
@@ -7,9 +7,9 @@
7
7
  * across available execution backends:
8
8
  * - LLVM (native binary via Clang/LLVM)
9
9
  * - WebAssembly (persistent runner via Wasm)
10
+ * - PKIR (persistent runner via Wasm/PKIR)
10
11
  * - kVM Interpreter (envelope-free bytecode engine)
11
12
  * - Native JS (envelope-free convergence engine)
12
- * - ARM64 (native binary, on supported Linux aarch64 hosts)
13
13
  *
14
14
  * Modes:
15
15
  * --mode squaring : Successive squarings starting from --input
@@ -67,7 +67,7 @@ function printHelp() {
67
67
 
68
68
  Multiplication Algorithm & Multi-Backend Performance Harness.
69
69
  Compares multiplication algorithms ('times' vs 'karatsuba') across
70
- available execution backends (LLVM, Wasm, kVM, JS, ARM64).
70
+ available execution backends (LLVM, Wasm, PKIR, kVM, JS).
71
71
 
72
72
  Options:
73
73
  --mode <squaring|sizes>
@@ -76,7 +76,8 @@ Options:
76
76
  (default: squaring)
77
77
  --backends <csv>
78
78
  Comma-separated list of execution backends to test:
79
- llvm, wasm, kvm, js, arm64. (default: llvm,wasm,kvm,js)
79
+ llvm, llvm-pkir, wasm, pkir, kvm, js.
80
+ (default: llvm,llvm-pkir,wasm,pkir,kvm,js)
80
81
  --algos <csv>
81
82
  Comma-separated list of multiplication algorithms to test:
82
83
  times, karatsuba. (default: times,karatsuba)
@@ -106,11 +107,7 @@ Environment Variables:
106
107
  LLVM_PIPELINE
107
108
  Set to '1' to use persistent pipelined LLVM runner mode.
108
109
  LLVM_SPAWN_PER_CALL
109
- Set to '1' to spawn a new LLVM process on each invocation.
110
- ARM64_PIPELINE
111
- Set to '1' to use persistent pipelined ARM64 runner mode.
112
- ARM64_SPAWN_PER_CALL
113
- Set to '1' to spawn a new ARM64 process on each invocation.`);
110
+ Set to '1' to spawn a new LLVM process on each invocation.`);
114
111
  }
115
112
 
116
113
  if (hasFlag("-h") || hasFlag("--help")) {
@@ -119,7 +116,11 @@ if (hasFlag("-h") || hasFlag("--help")) {
119
116
  }
120
117
 
121
118
  const mode = getArg("--mode", "squaring"); // 'squaring' or 'sizes'
122
- const backendsArg = getArg("--backends", "llvm,wasm,kvm,js");
119
+ const defaultBackends = "llvm,llvm-pkir,wasm,pkir,kvm,js";
120
+ const backendsArg = getArg(
121
+ "--backends",
122
+ process.env.BACKENDS || defaultBackends
123
+ );
123
124
  const selectedBackends = backendsArg
124
125
  .split(",").map(b => b.trim().toLowerCase()).filter(Boolean);
125
126
  const algosArg = getArg("--algos", "times,karatsuba");
@@ -244,7 +245,7 @@ const cacheDir = makeCacheDir("k-mult-perf-");
244
245
  // 2. Prepare Squaring Relations & Binaries
245
246
  // For squaring: relation name `s_${algo} = {()x, ()y} ${algo}; s_${algo}`
246
247
  const algoRelations = {};
247
- const algoServers = { llvm: {}, wasm: {} };
248
+ const algoServers = { llvm: {}, "llvm-pkir": {}, wasm: {}, pkir: {} };
248
249
 
249
250
  let commonState = null;
250
251
 
@@ -277,7 +278,10 @@ for (const algo of selectedAlgos) {
277
278
  const exePath = path.join(cacheDir, `perf_mult_llvm_${algo}`);
278
279
  try {
279
280
  compileObjectToExecutable(
280
- algoRelations[algo].object, exePath, { clangOpt: "-O2" }
281
+ algoRelations[algo].object, exePath, {
282
+ clangOpt: "-O2",
283
+ inputPattern: parseIntValue("0").pattern
284
+ }
281
285
  );
282
286
  algoServers.llvm[algo] = new PersistentExecutable(exePath);
283
287
  } catch (e) {
@@ -287,6 +291,26 @@ for (const algo of selectedAlgos) {
287
291
  }
288
292
  }
289
293
 
294
+ // LLVM (via PKIR)
295
+ if (selectedBackends.includes("llvm-pkir")) {
296
+ const exePath = path.join(cacheDir, `perf_mult_llvm_pkir_${algo}`);
297
+ try {
298
+ compileObjectToExecutable(
299
+ algoRelations[algo].object, exePath, {
300
+ clangOpt: "-O2",
301
+ inputPattern: parseIntValue("0").pattern,
302
+ usePKIR: true
303
+ }
304
+ );
305
+ algoServers["llvm-pkir"][algo] =
306
+ new PersistentExecutable(exePath);
307
+ } catch (e) {
308
+ console.warn(
309
+ `[WARN] Failed to compile LLVM-PKIR for ${algo}: ${e.message}`
310
+ );
311
+ }
312
+ }
313
+
290
314
  // Wasm
291
315
  if (selectedBackends.includes("wasm")) {
292
316
  const wasmPath = path.join(cacheDir, `perf_mult_wasm_${algo}.wasm`);
@@ -311,15 +335,36 @@ for (const algo of selectedAlgos) {
311
335
  );
312
336
  }
313
337
  }
338
+
339
+ // PKIR
340
+ if (selectedBackends.includes("pkir")) {
341
+ const pkirPath = path.join(cacheDir, `perf_mult_pkir_${algo}.wasm`);
342
+ const exePath = path.join(cacheDir, `perf_mult_pkir_${algo}.exe`);
343
+ try {
344
+ const wasmBuf = await compileWasmArtifactFromObject(
345
+ algoRelations[algo].object, { entry: "__main__", usePKIR: true }
346
+ );
347
+ fs.writeFileSync(pkirPath, wasmBuf);
348
+ const runBin = fileURLToPath(
349
+ import.meta.resolve("../backends/wasm/bin/k-wasm-run.mjs")
350
+ );
351
+ fs.writeFileSync(
352
+ exePath,
353
+ `#!/bin/sh\nexec node "${runBin}" "${pkirPath}" "$@"\n`,
354
+ { mode: 0o755 }
355
+ );
356
+ algoServers.pkir[algo] = new PersistentExecutable(exePath);
357
+ } catch (e) {
358
+ console.warn(
359
+ `[WARN] Failed to compile PKIR for ${algo}: ${e.message}`
360
+ );
361
+ }
362
+ }
314
363
  }
315
364
 
316
365
  // 3. Squaring Mode Benchmark
317
366
  if (mode === "squaring") {
318
- const sInitVal = valueForCode(
319
- parseIntValue(squaringInputText),
320
- commonState.typeAliases.int,
321
- codes.find
322
- );
367
+ const sInitVal = parseIntValue(squaringInputText);
323
368
  const { inputWire: sInitWire } = wireInput(sInitVal);
324
369
 
325
370
  const results = {};
@@ -333,8 +378,8 @@ if (mode === "squaring") {
333
378
  const stepBits = [];
334
379
 
335
380
  try {
336
- // A. Run persistent backends (LLVM, Wasm)
337
- const activeBackends = ["llvm", "wasm"]
381
+ // A. Run persistent backends (LLVM, LLVM-PKIR, Wasm, PKIR)
382
+ const activeBackends = ["llvm", "llvm-pkir", "wasm", "pkir"]
338
383
  .filter(b => selectedBackends.includes(b));
339
384
  for (const backend of activeBackends) {
340
385
  for (const algo of selectedAlgos) {
@@ -547,7 +592,7 @@ if (mode === "squaring") {
547
592
 
548
593
  } finally {
549
594
  // Teardown persistent servers
550
- for (const backend of ["llvm", "wasm"]) {
595
+ for (const backend of ["llvm", "llvm-pkir", "wasm", "pkir"]) {
551
596
  for (const algo of selectedAlgos) {
552
597
  algoServers[backend]?.[algo]?.child?.kill();
553
598
  }
@@ -584,12 +629,8 @@ if (mode === "sizes") {
584
629
  const strA = randomBigIntBits(bits);
585
630
  const strB = randomBigIntBits(bits);
586
631
 
587
- const valA = valueForCode(
588
- parseIntValue(strA), commonState.typeAliases.int, codes.find
589
- );
590
- const valB = valueForCode(
591
- parseIntValue(strB), commonState.typeAliases.int, codes.find
592
- );
632
+ const valA = parseIntValue(strA);
633
+ const valB = parseIntValue(strB);
593
634
  const pairInput = { tag: "product", value: { x: valA, y: valB } };
594
635
 
595
636
  for (const backend of selectedBackends) {