Foluone/yoruba-hfst-numerals

# Yoruba Vigesimal Numeral System — HFST Reimplementation A compiled finite-state transducer for Yoruba numeral morphology (cardinal, adjective, ordinal, numismatic forms), covering the full 1–20,000 range. Built to replace an earlier Python-only reference implementation (`hfst_impl/reference/phase4.py`) with a genuinely compiled, machine-verifiable finite-state artifact, per `DESIGN.md`. This README lives at the repo root; all code is under `hfst_impl/`. ## Status H0–H3 complete and exhaustively validated (every value in 1–20,000, all 4 form classes — no sampling). See `hfst_impl/IMPLEMENTATION_NOTES.md` for the full account, including two independently-built backends that agree exactly with each other and with the Python reference. Outstanding: CDEL/COAL/ASSI (blocked on a dead-code question — they're defined in the reference but never actually called by anything), ELIS/TSAN (the `mú`-prefix tonal sandhi context), a formal autosegmental tone specification, and the parse (surface text → integer) direction. All tracked as milestones H4+ in `DESIGN.md`. ## Two backends, same validated behavior This repo intentionally contains **two** independent implementations of the same rule set, kept side by side rather than one replacing the other: - **Pynini backend** (`arithmetic.py`, `phonology.py`, `pipeline.py`, `surface.py`, `validate.py`) — OpenFST-based, installs cleanly via pip, fast to iterate on. Built first; kept as a reference/fallback. - **Real HFST backend** (`arithmetic_hfst.py`, `phonology_hfst.py`, `pipeline_hfst.py`, `surface_hfst.py`, `validate_hfst.py`) — the literal Helsinki Finite-State Toolkit. Built second, once the toolkit was confirmed obtainable without root (see Setup below). This is the one that satisfies a literal "compiled with HFST" requirement. Both pass the identical exhaustive validation suite with identical results. This cross-validation — two different underlying libraries agreeing on every one of 80,000+ generation cases and 20,000 …