Build a Product Compiled Ahead of Time

What AOT means here

AOT is short for ahead of time. Native compiles the rule before you run it and produces a product with no Lispex source inside it. The Native pipeline is explicit.

exact Lispex source
  -> lispex.core-ir/v1
  -> lispex.bytecode/v1
  -> readable generated Topaz + source map
  -> exact installed Topaz 5.11 compiler
  -> topaz.artifact.v1
  -> source-free Native product

The generated program contains a static control graph. It does not read Lispex source or bytecode at runtime and does not embed the Rust virtual machine, the built-in interpreter that reads your source directly, or the separately installed Topaz virtual machine.

Prepare the rule

Save refund-window.lspx.

(define (decide days)
  (if (<= days 30) 'refund 'review))

(decide input)

Save the input datum as request.lspx.

14

Select the build tools explicitly

Compiling ahead of time is currently a Native macOS ARM64 feature. Use absolute paths to the installed topaz-lang@5.11.0 compiler and its Rust tool directory.

lispex routes fetch \
  --route aot-compiler \
  --target aarch64-apple-darwin \
  --out /absolute/tools/lispex-aot-compiler

TOPAZ_BIN=/absolute/tools/lispex-aot-compiler/product/bin/topaz-bin
RUST_TOOL_BIN=/absolute/path/to/rustup/bin

Fetch checks the exact closed Topaz package and release manifest but does not register or select the compiler. At build time Lispex checks the compiler, npm wrapper, installer, and separately supplied Rust tool proxies again. It never searches PATH, a repository checkout, the network, an older toolchain, or a cached alternate product.

Build without overwriting

lispex aot build \
  --source refund-window.lspx \
  --topaz-compiler "$TOPAZ_BIN" \
  --rust-tool-bin "$RUST_TOOL_BIN" \
  --out refund-window-aot

The destination must not exist. Lispex builds in a private staging area under fixed limits, strictly validates the compiler-emitted Topaz artifact and every managed file, then removes path-sensitive local linker symbols and replaces the linker signature with one fixed ad-hoc Lispex AOT signature. The product manifest records the exact /usr/bin/strip and /usr/bin/codesign hashes, and the final Topaz artifact is rebound to the finalized executable. Lispex writes its manifest last and atomically publishes the closed product.

The installed directory contains only these files.

lispex-aot-product.json
lispex-source-map.json
topaz-artifact.json
target/debug/program
LICENSE
NOTICE
GENERATED-OUTPUT-NOTICE.txt

Generated Topaz and original Lispex source are not required to run it.

Inspect and validate without execution

lispex aot inspect --product "$PWD/refund-window-aot"
lispex aot validate --product "$PWD/refund-window-aot"

Both commands require an absolute product root. They verify the closed file inventory, the source, Core IR, bytecode, and product identities, the source map, the exact compiler and macOS finalizer lineage, Topaz artifact, executable hash, target, and zero fallback counters. Neither command starts the executable.

Run the installed product

lispex aot run \
  --product "$PWD/refund-window-aot" \
  --input request.lspx

refund

run revalidates the installed product and starts only its recorded executable. It never compiles and never retries the built-in interpreter, the Rust virtual machine, the Topaz virtual machine, the bytecode parser, the network, or another installation.

For a machine-readable result, add --json.

lispex aot run \
  --product "$PWD/refund-window-aot" \
  --input request.lspx \
  --json

The result binds the product manifest, source, Core IR, bytecode, generated Topaz bundle, source map, Topaz artifact, executable, input, requested resources, observations, and five zero fallback counters.

Set resource limits

lispex aot run \
  --product "$PWD/refund-window-aot" \
  --input request.lspx \
  --machine-transitions 1000000 \
  --output-bytes 1048576 \
  --control-frames 10000 \
  --json

All three values are unsigned 64-bit decimals in one fixed written form. Leading zeroes, signs, overflow, mismatched accounting, or an impossible success/diagnostic combination fail closed. Different engines can charge different resource models, so compare like-for-like requests rather than treating equal numbers as a proof of semantic equivalence. A reached resource limit remains a typed fault result with its diagnostic and observed counters. The Native parent does not discard that JSON merely because the compiled process exits unsuccessfully.

Compare all four ways of running it

After building the compiled product, you can run the Rust tree, the built-in Rust virtual machine, the exact installed Topaz virtual machine, and the compiled executable for one source and input.

lispex compare-routes \
  --topaz-vm /absolute/path/to/aarch64-apple-darwin \
  --aot-product "$PWD/refund-window-aot" \
  --receipt four-routes.json \
  --input request.lspx \
  refund-window.lspx

Lispex parses and normalizes the source once, derives one Core IR and bytecode artifact, proves that the prebuilt AOT product binds those exact identities, validates both installed Topaz products, and then runs each of the four explicitly. It never retries one that failed.

The no-clobber receipt keeps semantic mismatch axes separate from comparable resource mismatch axes. The Rust virtual machine, the Topaz virtual machine, and the compiled product share the bytecode cost model and must agree on transition, output, control-frame, and completed-root counts. The tree reports its different depth model honestly, so unavailable tree transition and frame counts are not invented. Exit 0 means all four completed and every checked axis agreed. Exit 1 means a checked mismatch. Exit 2 means an execution or product failure. Exit 3 means the receipt could not be published.

Security boundary

A compiled executable, product manifest, source map, inspection, validation, or run report, together with the four-way receipt, is execution-material-only or local diagnostic evidence. None is Vouch authentication evidence, a request-bound re-execution result, or a gate grant. The current Vouch chain continues to use exact external source and input, with its boundary drawn around the tree run, the meaning record, and the Rust virtual machine.

The Rust tree run and the Rust virtual machine remain independently available as recovery paths. A failure of the compiled product is visible and does not select either of them automatically.

Product support

The current path produces an unoptimized, correctness-first product. Its byte-identical rebuild claim is limited to the recorded compiler, Rust, and macOS finalizer identities on the current host, and it is not a cross-host reproducible-build claim. It does not promise smaller binaries, faster execution, cross-compilation, a stable binary interface, formal equivalence, publisher authenticity, or Vouch authority.

Run Verified Bytecode · Native CLI · Runtime and Backends