Glossary

What does this word mean in moxzi's documentation?

These are moxzi's terms of art, defined once so the rest of the documentation can use them without hedging. Where a word also has a general meaning in Motoko or on the Internet Computer, the definition below is the narrower one this project uses.

Byte-identical — two compilations produced the same bytes, compared with cmp. It is the project's central claim and its exit criterion: not "equivalent", not "passes the same tests", the same file. Byte identity is what makes an on-chain build reproducible and what makes a browser build trustworthy.

Byte-neutral — a change to the compiler that alters no emitted byte on any corpus program. Performance work, refactors and resumability seams are all required to be byte-neutral; scripts/compiler_byte_neutral.sh is the guard on that class of change.

Fixed point (C2 == C3) — the compiler compiling itself until the output stops changing. A compiler C1 compiles its own sources to C2; C2 compiles the same sources to C3. When C2 and C3 are byte-identical the compiler is at a fixed point, which is the strongest self-hosting claim available: the artifact reproduces itself exactly. moxzi reaches this on-chain, at mainnet limits.

The corpus — the collection of Motoko programs the toolchain is measured against, drawn from moc's own test suite rather than written for moxzi. Two sweeps use it: 221 programs for two-compiler byte parity, 160 for browser-versus-native behaviour. A corpus program is not a unit test; it is a third party's program that must behave the same everywhere.

A gate — an executable shell script that asserts one property and exits non-zero when it stops holding. The gates in scripts/ are the behaviour contract: the claim is the script, not a design note, and make alpha-check runs all of them at once. A gate that cannot run (no Chrome, no compiler wasm) skips loudly rather than silently passing.

A step — one call to the on-chain compiler's step method, which does a bounded amount of compilation and returns. A build is a sequence of steps; the counts quoted for on-chain builds (2,345 for the compiler, 4,138 for evm_engine) are step counts. Each step is bounded by onchainStepUnitBudget, onchainStepInstrBudget and several memory valves so that it ends before the replica's per-message instruction cap does.

The replica — the Internet Computer's node software, always as an external system in these docs: the thing a deployed canister runs on, the reference moxzi's behavior is measured against, the authority phrases like "the replica would refuse this" report on. moxzid is not a replica and contains no replica code — see Provenance and clean room.

The management canister — the interface specification's name for the virtual canister aaaaa-aa (create_canister, install_code, canister_status, …). When these docs say a moxzi runtime "has" one, they mean it answers that interface through its own implementation, written from the spec.

A round — one Internet Computer consensus round, roughly one block. On-chain compile time is message count multiplied by block time, not instruction count, which is why the optimisation target for on-chain builds is fewer messages rather than fewer instructions.

Resumability — the property that a compilation phase can stop at a message boundary and continue in the next message with no change to what it emits. It is what lets a compiler that needs far more than 40 billion instructions run inside a canister at all. Resumability must be byte-neutral by construction: a seam that changed the output would be a bug, not a feature.

The drain — the runtime loop that delivers a canister's queued messages, including the self-calls Motoko's async/await lowering generates. Both the native and browser backends delegate to the same drain through a shared Machine trait, which is why a self-call chain refused in one is refused in the other with the same message and at the same depth (512).

A frame — one activation record on the native stack. In moxzi's stack analyses the binding quantity is frame size, not recursion depth: wasm allocates every local on function entry, so a function holding thousands of locals costs kilobytes per level of nesting whether or not it uses them. Two separate stack-overflow investigations — one on-chain, one in a browser tab — resolved to a single oversized function each.

The work-stack — an explicit heap-allocated stack that replaces native recursion in the compiler's descent, so that stack depth stops tracking the input program's nesting depth. It is how deeply nested expressions become a memory question instead of a stack-overflow question.

EOP (enhanced orthogonal persistence) — Motoko's persistence mode in which the actor's whole heap survives an upgrade, rather than being serialised through stable variables. In moxzi it also selects the 64-bit target: Flags.isMemory64() is defined as persistence() == #enhancedOrthogonalPersistence. It is the mode the compiler itself is compiled in.

An unlinked artifact — the wasm the compiler emits before the linker runs: it still has link-only exports, still lacks the runtime system, and is not deployable. An on-chain build returns an unlinked module by design, so moxzi link is a real step and not a formality — validation failing on an unlinked artifact is expected, not a symptom.

The linker — the second canister-shaped wasm in the toolchain, which turns an unlinked module into an installable one. It ships beside the compiler and is run the same way in all four places.

mops — the Motoko package manager, and by extension a package's published version. moxzi resolves mo: imports through one resolver shared by the CLI, the server and the browser, which is why an in-tab compile of a program with package imports is byte-identical to a CLI compile of the same program.

A mops tag — a (package, version) manifest pinned to content-addressed blobs already stored in the build canister. Building from a tag uploads zero bytes, which is both cheaper and the only way to build on-chain without disclosing your sources to the canister's operator.

Escrow — the on-chain build payment model: the CLI quotes a cycles amount from the source size, approves that much ICP at the CMC's live rate, the canister pulls it, measures what the build actually burned, charges three times that, and refunds the rest. It exists because a build's cost is unknown before it runs and a customer should not fund the worst case permanently.

Provenance — the record of which compiler produced an artifact, printed as a SHA-256 on every build. It is deliberately printed and never embedded: an embedded stamp would have to be byte-identical between the local and on-chain paths for the parity proofs to survive, so the claim is kept outside the bytes it is about.

A divergence — a corpus program that behaves differently under two runtimes or compiles to different bytes under two compilers. The count is the score: the browser sweep's current figure is zero. Historically, most reported divergences were differences between two observers rather than two systems — a truncated output, a ring-buffered log, a stale binary — which is why a divergence is investigated before it is believed.

Next#

• Known differences — the differences that are real and intended.
• Limits — every number these terms refer to.
• The differential corpus — how the sweeps above are actually run.