OCaml to MoonBit Migration

Port behavior, data invariants, and public contracts first. Translate syntax only after the source semantics are classified. The most common porting bug is silently coercing OCaml string (a byte sequence) into MoonBit String (UTF-16 text); classify every field by meaning before choosing a type.

When in doubt, probe with moon run -c '...'. Probes in this guide were verified on moon 0.1.20260512-class toolchains; rerun the relevant probe if the local toolchain is newer and the behavior is load-bearing.

Migration Workflow

1. Inventory the OCaml module boundary: public types, functions, exceptions, optional arguments, mutable state, lazy/deferred state, C/Unix/filesystem dependencies, and existing tests or golden fixtures.
2. Classify every OCaml string by meaning before choosing a MoonBit type. Do this field by field, even inside the same OCaml record.
3. Choose MoonBit package boundaries and imports before coding. Add imports to moon.pkg; MoonBit source files do not use OCaml-style open.
4. Port one behavioral slice at a time with tests. Prefer a thin public API skeleton, then fill parser/serializer/algorithm internals behind it.
5. Probe uncertain language or library behavior with moon run -c and, when needed, a small OCaml toplevel probe. Keep probes minimal.
6. Finish each slice with moon check, moon test, moon info, and moon fmt. You can add more warnings moon check --warn-list +... to be more strict.

Type-Mapping Cheatsheet