@fraczak/k 6.3.3 → 6.4.0

package/Examples/poly.k

@@ -0,0 +1,67 @@
+-- Examples/poly.k: Polymorphic list functions in k
+-- Uses list constructors/destructors from Examples/list.k
+-- and arbitrary-precision integer representations from Examples/arithmetics.k.
+
+-- Decrement an integer and normalize its representation (stripping leading zeros)
+pred_int = dec /'+' nat | '+';
+
+-- Concatenate two lists: {xs, ys} -> list
+concat = {.xs reverse xs, .ys acc} _reverse;
+
+-- Reverse a list: xs -> list
+reverse = {() xs, nil acc} _reverse;
+_reverse = <
+  {.xs cdr xs, {.xs car car, .acc cdr} cons acc} _reverse,
+  .acc
+>;
+
+-- Length of a list: xs -> int
+length = {() xs, 0 int acc} _length;
+_length = <
+  {.xs /nil if, .acc then} .then,
+  {.xs cdr xs, .acc inc acc} _length
+>;
+
+-- Get N-th element of a list (0-indexed): {n, xs} -> element
+get_nth = <
+  {.n zero_int? if, .xs car then} .then,
+  {.n pred_int n, .xs cdr xs} get_nth
+>;
+
+-- Split list at index N: {n, xs} -> {first, second}
+split_by = {.n n, .xs xs, nil acc} _split_by;
+_split_by = <
+  {.n zero_int? if, {.acc reverse first, .xs second} then} .then,
+  {.xs /nil if, {.acc reverse first, nil second} then} .then,
+  {.n pred_int n, .xs cdr xs, {.xs car car, .acc cdr} cons acc} _split_by
+>;
+
+-- Take the first N elements of a list: {n, xs} -> list
+take = split_by .first;
+
+-- Drop the first N elements of a list: {n, xs} -> list
+drop = <
+  {.n zero_int? if, .xs then} .then,
+  {.xs /nil if, nil then} .then,
+  {.n pred_int n, .xs cdr xs} drop
+>;
+
+-- Repeat element X, N times: {n, x} -> list
+repeat = {.n n, .x x, nil acc} _repeat;
+_repeat = <
+  {.n zero_int? if, .acc then} .then,
+  {.n pred_int n, .x x, {.x car, .acc cdr} cons acc} _repeat
+>;
+
+-- Append an element to the end of a list: {x, xs} -> list
+append = {.xs xs, {.x car, nil cdr} cons ys} concat;
+
+-- Zip two lists into a list of {x, y} pairs: {xs, ys} -> list
+zip = <
+  {.xs /nil if, nil then} .then,
+  {.ys /nil if, nil then} .then,
+  {
+    {.xs car x, .ys car y} car,
+    {.xs cdr xs, .ys cdr ys} zip cdr
+  } cons
+>;

package/README.md

@@ -64,6 +64,15 @@ one successor. The REPL also prints the inferred value envelope.
 
 ## Try It
 
+### In the Browser (Zero Install)
+
+Try k directly in your browser without installing anything:
+**[https://fraczak.github.io/k/](https://fraczak.github.io/k/)**
+
+The Web REPL is self-contained, powered by an in-process WebAssembly compiler and execution engine with built-in codecs, autocompletion, interactive input, and standard libraries.
+
+### From Source
+
 From a checkout:
 
 ```bash
@@ -91,6 +100,13 @@ Start the interactive interpreter:
 k-repl
 ```
 
+Build the standalone single-file Web REPL locally:
+
+```bash
+npm run build:repl-html
+# generates repl.html (open in any web browser)
+```
+
 Every installed command supports `-h` and `--help`.
 
 ## What k Gives You
@@ -149,13 +165,13 @@ k-print   # binary pattern+value stream -> textual value
 
 k programs can be compiled into:
 
-- `.klib`: plain JSON library objects
+- `.klib`: library objects
 - `.ko`: executable binary object containers
-- `.kvm`: JSON kVM programs
+- `.kvm`: specialized kVM backend artifacts
 
 Object and library files keep canonical code/relation definitions, aliases,
-metadata, and type-derivation status. The `.kvm` output is a lowered JSON
-program for backend inspection and execution experiments.
+metadata, and type-derivation status. The `.kvm` output is a lowered backend
+artifact for inspection and execution experiments.
 
 ## CLI Tour
 
@@ -191,17 +207,30 @@ program for backend inspection and execution experiments.
 | `k-compile` | Compile `.k` source to `.ko`, `.klib`, or `.kvm` output |
 | `k-decompile` | Decompile `.ko` or `.klib` back to k source |
 | `k-extract-aliases` | Recover metadata aliases as k source |
+| `k-inspect-object` | Inspect object sections or print the KIR-P backend export |
+| `k-validate-object` | Validate `.ko`, `.klib`, or exported KIR-P artifacts |
+| `k-kir` | Export KIR-P from `.ko` or `.klib` |
+| `k-vm` | Execute or inspect lowered kVM bytecode artifacts (`.kvm`) |
+| `k-wasm` / `k-wasm-compile` / `k-wasm-run` | Compile and run via WebAssembly backend |
+| `k-llvm-build` / `k-llvm-compile` / `k-llvm-run` | Compile and run via LLVM backend |
+| `k-arm64` / `k-arm64-compile` / `k-arm64-run` | Compile and run via Linux ARM64 native backend |
 
 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
+## Backends
+
+Backends live under [`backends/`](backends/) as npm workspaces:
+
+- [`backends/wasm`](backends/wasm/) lowers typed k programs through kVM into
+  WebAssembly artifacts. Powers both the CLI REPL (`wasm-in-process`) and the standalone Web REPL.
+- [`backends/llvm`](backends/llvm/) lowers polymorphic kVM programs into LLVM IR and
+  compiled native test executables.
+- [`backends/arm64`](backends/arm64/) lowers polymorphic kVM programs directly into
+  standalone Linux ARM64 native executables without external compiler dependencies.
 
-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
+All backends integrate with the compiler and binary codecs through
 [`backend-api.mjs`](backend-api.mjs).
 
 ## Node.js API
@@ -265,28 +294,41 @@ serialization, or teaching tools, there is room to shape the project.
 
 ## Examples
 
-The [`Examples/`](Examples/) directory contains small language demonstrations:
+The [`Examples/`](Examples/) directory contains language demonstrations and standard libraries:
 
 | File | Contents |
 | --- | --- |
+| `core.k` | Standard library: booleans, units, strings, optionals, and fundamental helpers |
+| `arithmetics.k` | Integer and rational arithmetic built from bit-level relations from scratch |
+| `ieee.k` | IEEE 754 binary64 floating-point arithmetic (`add`, `sub`, `mul`, `div`) |
+| `poly.k` | Polymorphic list operations (`concat`, `reverse`, `length`, `get_nth`, `split_by`, `zip`) |
 | `nat.k` | Peano natural numbers |
 | `byte.k` | Byte type |
-| `ieee.k` | IEEE 754 floating-point layout |
 | `bnat.k` | Binary natural numbers |
-| `arithmetics.k` | Integer and rational arithmetic built from scratch |
+| `buda.k` | Compact relational data transformations |
 
 `list.k` is also useful as a focused demonstration of filters and patterns.
 
-`ieee.k` is the largest example. It builds an IEEE-754 binary64 model from
-bit-level types upward, including comparison and floating-point `add`, `sub`,
-`mul`, and `div` relations. Those public aliases return `{ result, flags }`;
-compose with `.result` when only the floating-point value is needed.
+`ieee.k` is a complete IEEE-754 binary64 model built from bit-level types
+upward with hierarchical significand adders, including comparison and
+floating-point `add`, `sub`, `mul`, and `div` relations. Those public aliases
+return `{ result, flags }`; compose with `.result` when only the floating-point
+value is needed.
 
 ## Development
 
 ```bash
-npm run prepare   # regenerate parsers from .jison grammars
-npm test          # run the fail-fast full suite with per-test timings
+npm run prepare         # regenerate parsers from .jison grammars
+npm test                # run the fail-fast full suite with per-test timings
+npm run test:wasm       # run the WebAssembly backend tests
+npm run test:llvm       # run the LLVM backend tests
+npm run test:arm64      # run the Linux ARM64 backend tests
+npm run build:repl-html # build the standalone single-file Web REPL (repl.html)
+npm run compare         # run multi-backend benchmark and conformance harness
+npm run perf:poly       # run polymorphic benchmark across backends
+npm run perf:poly:trace # run execution phase tracing & call profiling
+npm run perf:int        # run integer arithmetic benchmark across backends
+npm run perf:ieee       # run IEEE-754 arithmetic benchmark across backends
 ```
 
 The test runner prints each test before execution and reports its elapsed time
@@ -297,14 +339,21 @@ afterward. It stops immediately when a test fails. The suite covers:
 - hash/fingerprint stability
 - object file round-trips
 - REPL scripted interaction
+- Web REPL headless browser verification
+- polymorphic kVM and specialization
 - shell integration tests
 
 ## Further Reading
 
-- [DOCS/REPL.md](DOCS/REPL.md) - interactive interpreter details
+- [DOCS/DICTIONARY.md](DOCS/DICTIONARY.md) - concept names and terminology
+- [DOCS/REPL.md](DOCS/REPL.md) - interactive interpreter and codec details
+- [DOCS/WEB_REPL_REQUIREMENTS.md](DOCS/WEB_REPL_REQUIREMENTS.md) - Web REPL architecture and requirements
+- [DOCS/KVM_EXECUTION_MODEL.md](DOCS/KVM_EXECUTION_MODEL.md) - kVM execution model and bytecode design
 - [DOCS/TEXTUAL_VALUES.md](DOCS/TEXTUAL_VALUES.md) - textual boundary notation
 - [DOCS/PATTERNS.md](DOCS/PATTERNS.md) - pattern representation
 - [DOCS/OBJECT_FILE_AND_PATTERN.md](DOCS/OBJECT_FILE_AND_PATTERN.md) - object format
+- [DOCS/PROFILING_AND_TRACING.md](DOCS/PROFILING_AND_TRACING.md) - execution phase tracing and function call profiling across backends
+- [DOCS/CODECS.md](DOCS/CODECS.md) - writing external codecs
 - [codecs/README.md](codecs/README.md) - binary codec internals
 - [objects/README.md](objects/README.md) - object/library tools
 - [DOCS/book.md](DOCS/book.md) - longer language reference

package/augmentation.mjs

@@ -1,4 +1,5 @@
 import codes from "./codes.mjs";
+import { getIntrinsic } from "./intrinsics.mjs";
 
 const unitCode = codes.unitCode;
 
@@ -187,12 +188,13 @@ function augmentRef(rel,rootDef,rels) {
       });
     return;
   }
-  // it is built-in
-  switch (rel.ref) {
-    case "_log!":
-      rel.patterns[0] = rel.patterns[1] = rootDef.typePatternGraph.addNewNode();
-      break;
-    default:
-      throw new Error(`No definition found for '${rel.ref}'`);  
+  const intrinsic = getIntrinsic(rel.ref);
+  if (intrinsic) {
+    if (intrinsic.type !== "identity") {
+      throw new Error(`No type rule found for intrinsic '${rel.ref}'`);
+    }
+    rel.patterns[0] = rel.patterns[1] = rootDef.typePatternGraph.addNewNode();
+    return;
   }
+  throw new Error(`No definition found for '${rel.ref}'`);  
 }

package/backend-api.mjs

@@ -1,12 +1,21 @@
 export { annotate } from "./index.mjs";
-export { lowerToKVM, executeKVM } from "./kvm.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 { 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";
-export { decodeObject, loadLibrary } from "./object.mjs";
+export { KIR_FORMAT, KIR_VERSION, objectToKIRP, retypeObjectRelation, retypeObjectRelationForBackend } from "./kir.mjs";
+export { compileLibrary, 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";
+export {
+  intrinsicDefinitions,
+  jsIntrinsicFunctions,
+  getIntrinsic,
+  isIntrinsic,
+  isIdentityIntrinsic,
+  unsupportedIntrinsic
+} from "./intrinsics.mjs";

package/backends/arm64/README.md

@@ -0,0 +1,104 @@
+# k Linux ARM64 Backend
+
+`@fraczak/k-arm64` is the native Linux AArch64 (ARM64) backend for
+[`@fraczak/k`](https://github.com/fraczak/k). It lowers typed k programs directly from
+the kVM representation into GNU AArch64 assembly text (`.s`), compiles native ELF
+executables, and provides CLI tools and runners for binary `pattern + value` streams
+and `--json` input/output.
+
+## Features
+
+- **Direct kVM to ARM64 Lowering**: Generates pure GNU AArch64 assembly text without requiring LLVM or external code generators.
+- **Calling Convention & Registers (AAPCS64)**:
+  - `x0`: Input value pointer on entry; Return status (`0` for success, non-zero for failure) on exit.
+  - `x1`: Output value pointer on exit.
+  - `x19`: Callee-saved Arena bump pointer preserved and updated across relation calls.
+  - Standard 16-byte stack frame alignment with FP (`x29`) and LR (`x30`) chaining.
+- **Flat Arena Memory Representation**:
+  - Word 0 (bytes 0–1): Total block size in bytes (16-byte aligned).
+  - Word 1 (bytes 2–3): Value kind (`1` = Product, `2` = Variant).
+  - Word 2 (bytes 4–7): Product field count OR Variant 32-bit tag ID.
+  - Payloads (bytes 8+): 64-bit pointers to child values in the arena.
+- **Self Tail-Call Optimization (TCO)**:
+  - Recursion where the tail call passes new product fields directly updates cached field slots and jumps back to `.Ltail_loop` with zero frame overhead, enabling deep recursion without stack overflow.
+- **Union Backtracking & Memory Rollback**:
+  - Union branches save the arena bump pointer (`x19`) before evaluation. If a branch fails, `x19` is rewound to cleanly roll back all allocations made in the failed speculative branch before attempting subsequent branches.
+- **Standalone Linux Binaries**:
+  - Links with a lightweight C driver (`backends/arm64/src/runtime.c`) and `backends/llvm/runtime/krt.c` to produce independent native ELF executables that execute directly on Linux without Node.js.
+  - Supports `--json` for direct text output, stdin/stdout piping, and binary envelope streams.
+
+## Quick Start
+
+Compile an expression to a standalone native Linux ARM64 executable:
+
+```bash
+node ./backends/arm64/bin/k-arm64-compile.mjs -o /tmp/ok '|ok'
+```
+
+Execute it over unit input and decode output:
+
+```bash
+node ./codecs/unit.mjs --parse | /tmp/ok --json
+```
+
+Output:
+```json
+"ok"
+```
+
+Compile with library dependencies (`--lib` and `--export`):
+
+```bash
+node ./backends/arm64/bin/k-arm64-compile.mjs \
+  --lib Examples/arithmetics.k \
+  --export plus:+ --export succ --export int \
+  '{succ int x,int y}+' \
+  -o /tmp/add-one
+
+node ./codecs/k-parse.mjs <<< '{"x":{"succ":"zero"},"y":{"succ":{"succ":"zero"}}}' |
+  /tmp/add-one --json
+```
+
+Output:
+```json
+{"+":{"1":"_"}}
+```
+
+## CLI Commands
+
+| Command | Purpose |
+| --- | --- |
+| `k-arm64` | Compile k source, `.ko`, or `.kvm` in memory and run immediately |
+| `k-arm64-compile` | Compile k source, `.ko`, or `.kvm` to standalone ELF executable or assembly (`-S`) |
+| `k-arm64-run` | Run a compiled ELF executable over binary wire streams |
+
+### Options
+
+All tools accept `--help`.
+
+- `-S, --assembly`: Emit GNU ARM64 assembly text (`.s`) instead of an ELF binary.
+- `-o, --output <file>`: Specify the output file path.
+- `--entry <name>`: Specify the entry relation (defaults to `__main__`).
+- `--lib <file>`: Load one `.klib` or `.k` library dependency.
+- `--export <spec>`: Export library symbols into source scope (`name` or `libname:localname`).
+- `--json`: Format output as JSON instead of binary wire format.
+
+## Running Tests
+
+Run unit tests:
+
+```bash
+node ./backends/arm64/tests/test-arm64.mjs
+```
+
+Run integration tests:
+
+```bash
+./backends/arm64/tests/integration.sh
+```
+
+Run the complete ARM64 backend test suite:
+
+```bash
+npm run test:arm64
+```

package/backends/arm64/bin/k-arm64-compile.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+
+import {
+  compileProgramInput,
+  parseCompileOptions,
+  resolveProgramInput
+} from "../src/cli.mjs";
+
+function usage(stream = console.error) {
+  const prog = argv[1] || "k-arm64-compile.mjs";
+  stream(`Usage: node ${prog} [options] [source-snippet | input-file [output-file]]`);
+  stream("Compile k source, .ko, or .kvm input into a standalone Linux ARM64 executable or assembly.");
+  stream("");
+  stream("Arguments:");
+  stream("  source-snippet  Inline k source, in the same style as k.mjs.");
+  stream("  input-file      Source .k, .ko, or .kvm file. Reads UTF-8 source from stdin when omitted.");
+  stream("  output-file     Output file path. Writes to stdout when omitted and --assembly is set.");
+  stream("");
+  stream("Options:");
+  stream("  -S, --assembly   Emit GNU ARM64 assembly (.s) instead of an executable binary.");
+  stream("  -o, --output     Specify output file path explicitly.");
+  stream("  --entry name     Specify entry relation name.");
+  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.");
+}
+
+try {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
+  let emitAssembly = false;
+  let explicitOutput = null;
+  let entry = null;
+
+  // Extract ARM64-specific flags
+  const remainingArgs = [];
+  while (args.length > 0) {
+    const arg = args[0];
+    if (arg === "-S" || arg === "--assembly") {
+      emitAssembly = true;
+      args.shift();
+    } else if (arg === "-o" || arg === "--output") {
+      args.shift();
+      explicitOutput = args.shift();
+      if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+    } else if (arg === "--entry") {
+      args.shift();
+      entry = args.shift();
+      if (!entry) throw new Error("--entry requires a name argument");
+    } else {
+      remainingArgs.push(args.shift());
+    }
+  }
+
+  const { libraries, exportSpecs } = 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;
+
+  const result = await compileProgramInput(input, {
+    libraries,
+    exportSpecs,
+    stdin,
+    entry,
+    emit: emitAssembly ? "assembly" : null,
+    outputPath: (!emitAssembly && outputPath) ? outputPath : null
+  });
+
+  if (emitAssembly) {
+    const asmText = typeof result === "string" ? result : result.assembly;
+    if (outputPath == null) {
+      stdout.write(asmText);
+    } else {
+      fs.writeFileSync(outputPath, asmText, "utf8");
+    }
+  } else {
+    if (outputPath == null) {
+      if (Buffer.isBuffer(result)) {
+        stdout.write(result);
+      } else if (typeof result === "string") {
+        stdout.write(fs.readFileSync(result));
+      }
+    } else if (Buffer.isBuffer(result)) {
+      fs.writeFileSync(outputPath, result, { mode: 0o755 });
+    }
+  }
+} catch (error) {
+  console.error(error.stack || error.message || String(error));
+  usage();
+  exit(1);
+}

package/backends/arm64/bin/k-arm64-run.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+
+import { readAll } from "../src/cli.mjs";
+import { runARM64Artifact } from "../src/arm64.mjs";
+
+function usage(stream = console.error) {
+  const prog = argv[1] || "k-arm64-run.mjs";
+  stream(`Usage: node ${prog} [options] executable-file [input-file]`);
+  stream("Run a standalone k Linux ARM64 executable over a binary wire stream.");
+  stream("");
+  stream("Arguments:");
+  stream("  executable-file  Input compiled ELF binary produced by k-arm64-compile.");
+  stream("  input-file       Optional binary input wire file. Reads stdin when omitted.");
+  stream("");
+  stream("Options:");
+  stream("  --json           Format output as JSON instead of binary wire format.");
+  stream("  -h, --help       Show this help.");
+}
+
+async function main() {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
+  let json = false;
+  const filteredArgs = [];
+  for (const arg of args) {
+    if (arg === "--json") {
+      json = true;
+    } else {
+      filteredArgs.push(arg);
+    }
+  }
+
+  const execPath = filteredArgs.shift();
+  if (!execPath) throw new Error("Missing executable artifact path");
+  const inputPath = filteredArgs.shift();
+  if (filteredArgs.length > 0) throw new Error("Too many arguments");
+
+  const input = await readAll(inputPath == null ? stdin : fs.createReadStream(inputPath));
+  const result = runARM64Artifact(execPath, input, { json });
+  if (json) {
+    stdout.write(result);
+  } else {
+    stdout.write(result);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message || String(error));
+  usage();
+  exit(1);
+});

package/backends/arm64/bin/k-arm64.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { decodeWire } from "../../../backend-api.mjs";
+
+import {
+  compileProgramInput,
+  parseCompileOptions,
+  readAll,
+  resolveProgramInput
+} from "../src/cli.mjs";
+import { runARM64Artifact } from "../src/arm64.mjs";
+
+function usage(stream = console.error) {
+  const prog = argv[1] || "k-arm64.mjs";
+  stream(`Usage: node ${prog} [options] ( source-snippet | input-file ) [ input-file ]`);
+  stream("Compile k source, .ko, or .kvm input to ARM64 in memory and run it over a binary pattern+value stream.");
+  stream("");
+  stream("Options:");
+  stream("  --json           Format output as JSON instead of binary wire format.");
+  stream("  --entry name     Specify entry relation name.");
+  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.");
+}
+
+async function main() {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
+  let json = false;
+  let entry = null;
+  const remainingArgs = [];
+  while (args.length > 0) {
+    const arg = args[0];
+    if (arg === "--json") {
+      json = true;
+      args.shift();
+    } else if (arg === "--entry") {
+      args.shift();
+      entry = args.shift();
+      if (!entry) throw new Error("--entry requires a name argument");
+    } else {
+      remainingArgs.push(args.shift());
+    }
+  }
+
+  const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
+  const programInput = resolveProgramInput(remainingArgs);
+  const inputPath = remainingArgs.shift();
+  if (remainingArgs.length > 0) throw new Error("Too many arguments");
+
+  const inputBuffer = await readAll(inputPath == null ? stdin : fs.createReadStream(inputPath));
+  let inputEnvelopePattern = null;
+  if (inputBuffer.length > 0) {
+    try {
+      const decoded = decodeWire(inputBuffer);
+      inputEnvelopePattern = decoded.pattern;
+    } catch {
+      // Not a valid wire buffer or empty
+    }
+  }
+
+  const artifact = await compileProgramInput(programInput, {
+    libraries,
+    exportSpecs,
+    inputEnvelopePattern,
+    entry
+  });
+
+  const output = runARM64Artifact(artifact, inputBuffer, { json });
+  if (json) {
+    stdout.write(output);
+  } else {
+    stdout.write(output);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message || String(error));
+  usage();
+  exit(1);
+});

package/backends/arm64/scripts/run-tests.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const node = process.execPath;
+const tests = [
+  ["tests/test-arm64.mjs", node, ["tests/test-arm64.mjs"]],
+  ["tests/integration.sh", path.join(root, "tests/integration.sh"), []]
+];
+
+function formatDuration(milliseconds) {
+  if (milliseconds < 1000) return `${milliseconds.toFixed(0)} ms`;
+  return `${(milliseconds / 1000).toFixed(2)} s`;
+}
+
+const suiteStarted = performance.now();
+for (const [name, command, args] of tests) {
+  console.log(`\n==> ${name}`);
+  const started = performance.now();
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: "inherit"
+  });
+  const duration = formatDuration(performance.now() - started);
+
+  if (result.error) {
+    console.error(`<== ${name} FAILED (${duration})`);
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    console.error(`<== ${name} FAILED (${duration})`);
+    process.exit(result.status ?? 1);
+  }
+  console.log(`<== ${name} passed (${duration})`);
+}
+
+console.log(`\nAll ARM64 tests passed (${formatDuration(performance.now() - suiteStarted)})`);