Reporting a bugalpha

What makes a moxzi bug report actionable?

An actionable moxzi bug report is one that someone else can turn into a failing gate. The project's whole verification model is executable — 32 gates, two corpus sweeps, 81 native tests — so the most useful thing a report can contain is a reproducer small enough to become one more of those.

What every report needs#

Item	How to get it
Which of the four products	CLI `moxzi`, server `moxzid`, browser `moxzi-web`, or the on-chain builder
Version and build	`moxzi --version` / `moxzid --version` / `GET /version` — all print `0.1.0-alpha.1 (<git sha>)`
The compiler and linker identity	`moxzi info` — prints both wasm paths and their SHA-256s
A reproducer	one `.mo` file if at all possible; a `mops.toml` too if the bug needs a package
The exact command and its full output	including the diagnostic text, not a paraphrase of it

The compiler's SHA-256 matters more than it looks: byte identity is the product, so a report against a compiler wasm nobody else has is a report about an unknown artifact.

Rule out the observer first#

Six times in this project's history, a difference between two observers was read as a difference between two systems. Before reporting a divergence, check:

Suspicion	Check
A stale binary	is the `moxzi`/`moxzid` on your `PATH` the one you just built? An A/B of two different builds coming out identical is an alarm, not a result
An orphaned server	`lsof -i :7000` — an old `moxzid` still holding the port will serve a whole test run
A truncated log	actor logs are a ring buffer bounded at 4096 lines
Query output	query prints are not replicated on a real replica
A swallowed error	a fetch or a subprocess whose failure was discarded reads as "no difference"
A cached artifact	`moxzi cache clear`

A wrong-bytes bug#

The compiler produced a different artifact than it should have. This is the highest-value class of report.

moxzi info                                # the compiler that produced them
moxzi build repro.mo -o out.wasm
moxzi build repro.mo --no-link -o out.unlinked.wasm

Send both artifacts' SHA-256s, and say what you compared against — another moxzi build, a reference moc build, or an on-chain build. --no-link separates a compiler bug from a linker bug and is worth doing before filing.

A wrong-behaviour bug#

The program compiled fine and did the wrong thing. State the expected result and where the expectation comes from — a real replica, moc's own corpus, or the specification.

moxzid -m actors.json -s ./state --log-json
curl -s localhost:7000/history/<actor>      # recent messages, outcomes, arg previews
curl -s localhost:7000/logs/<actor>
curl -s localhost:7000/inspect              # per-actor stats and candid interface
curl -s localhost:7000/metrics

If the difference is browser-versus-native, say which one you believe. The native runtime is the oracle for the browser sweep, and it was itself validated against a replica — so a browser-only difference is usually the more interesting half.

A crash, a hang, or a trap#

Symptom	Include
A trap	the full `IC0502`/`IC0503` line — the message text is the diagnosis
`unimplemented: <what>` (M9000)	the code that triggered it. This is a compiler gap, always worth reporting
A trap naming a `GAP`	likewise — the compiler is built to announce its own gaps rather than emit wrong code
A hang in a compile	`MOXZI_TRACE=1` for the self-call engine; `MOXZI_FUEL=1` makes `performance_counter` a real instruction count instead of a stub
A hang in a server	whether `/health` answers, and what `/health/ready` says
A stack overflow in a tab	how deeply nested the expression is; see limits

Switches worth knowing#

Switch	Effect
`MOXZI_COMPILER` / `MOXZI_LINKER`	point at specific wasm artifacts
`MOXZI_TRACE=1`	trace the self-call drain
`MOXZI_FUEL=1`	real instruction counting, at a cost in speed
`MOXZI_WASM_STACK` / `MOXZI_NATIVE_STACK`	change the stacks the compiler runs on
`MOXZI_MOPS`	name the `mops` binary outright when it is not on `PATH`
`--default-persistent-actors`	rewrite bare actors while porting, instead of hand-editing to reproduce
`moxzid --log-json`	structured logs
`moxzid --instruction-limit 0`	disable the per-message cap, to tell a real hang from a bounded one

What not to send#

Not useful	Instead
A whole project when one file reproduces	reduce it; `test/selfhost/probe-pending/` is full of examples of the shape wanted
A screenshot of a diagnostic	the text — codes and regions are matched programmatically
"It works with moc" without moc's output	paste both outputs
A report against an unreleased local compiler build	say so explicitly, and give the SHA-256
Anything you cannot share	the on-chain builder's operator can read uploaded source; the same caution applies to a reproducer attached to a public issue

A note on where to file#

The repository is rivvirtech/moxzi, and every manifest in the tree now names it. It is private during alpha, so its issue tracker is not open to the public yet — until it is, send reports to the address on moxzi.ai with the details above. The moxzi info output identifies the exact build, which is the part a report cannot do without.

Next#

Known differences — check here before filing; it may be intended.
Error and diagnostic codes — what the code in your output means.
The differential corpus — the shape a good reproducer eventually takes.