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 executes a static control graph directly. Lispex source, bytecode, the Rust virtual machine, the source tree interpreter, and the separately installed Topaz virtual machine stay on their named build and execution routes.

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 stages the exact closed Topaz package and checks its release manifest. The build selects the compiler through the absolute path you provide and checks the compiler, npm wrapper, installer, and Rust tool proxies there. Its discovery set is exactly those supplied paths.

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 its recorded executable. The result stays on that explicit AOT route with zero fallback attempts.

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. Equal counters record resource agreement, while the four-way receipt records semantic agreement separately. A reached resource limit remains a typed fault result with its diagnostic and observed counters. The Native parent preserves that JSON with the compiled process exit status.

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. Each result stays on its selected route.

The atomically published 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 own depth model and leaves unrelated transition and frame counts absent. 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.

Product roles

A compiled executable, product manifest, source map, inspection, validation, run report, and four-way receipt provide execution-material-only and local diagnostic evidence. Vouch adds publisher authentication, recipient trust policy, exact external source and input, request-bound current replay, and the local gate decision across the tree run, the meaning record, and the Rust virtual machine.

The Rust tree run and the Rust virtual machine remain independently selectable recovery paths. Each route keeps its result and route identity.

Product support

The path records exact source, Core IR, bytecode, compiler, Rust, macOS finalizer, and host identities in one Native product lineage. Rebuilds made with the same recorded host and tools can be compared byte for byte. Topaz owns execution performance, binary size, cross-compilation, and interface evolution. Vouch owns publisher authentication, trust policy, and the local grant.

Run Verified Bytecode · Native CLI · Runtime and Backends