Maturity Matrix
Monad is in alpha. This chapter says, area by area, what actually works today — so you can tell the parts you can build on from the parts that are still a sketch.
This rates the self-hosted compiler, the monad binary written in Monad
that compiles itself. That is the language. Where the Rust
bootstrap host differs it is called out, because the
difference currently matters.
Every row here was checked against the compilers' own source and tests at the commit this book ships with, not inferred from intent.
How to Read This
| Level | Meaning |
|---|---|
| Solid | Production quality for its scope. Well tested, unlikely to change under you. |
| Working | Does its job. Rough edges, but you can build on it. |
| Partial | Real, but incomplete. Read the note before depending on it. |
| Experimental | Works, but the shape will change. |
| Stub | Present in name only. Do not depend on it. |
| Planned | Does not exist yet. |
| Host only | Works in the bootstrap host; the self-hosted compiler does not. |
Language
| Area | Level | What that means |
|---|---|---|
| Syntax & parser | Working | Stable and well covered. Every def needs a type annotation — there is no top-level inference. |
| Type checker | Working | Bidirectional, with implicits and holes. Catches most errors; see the instance caveat below. |
| Type classes & instances | Partial | Resolution and superclass constraints work. But instances resolve at run time, so a missing instance type-checks and then fails with unresolved global:. Empty instance bodies do not parse, so class defaults cannot be inherited wholesale. Resolution keys on the type head, so an instance whose head is a variable (MonadLiftT m m, Monad (M I I)) type-checks and never dispatches. |
| Inductive types | Working | Parameters, recursion, indexed families, and the strict-positivity rule — a constructor field of a function type from the type being declared is rejected. |
| Pattern matching | Partial | One constructor level deep. No nested patterns, no literal patterns, no guards, no or-patterns, and no exhaustiveness checking. |
| Structs | Partial | Records, field defaults, { s with … } update, keyword construction, and field destructuring all work. Generic structs are effectively unconstructible — use a type with a positional constructor. |
| Dependent types | Partial | Pi and forall types, implicits, Sort N universes, Prop, and length-indexed Vec all work. match elaborates to the core Elim form and dependent pattern matching checks for non-indexed cases (a result type that is a type-level function of the scrutinee; proofs/src/dependent.mo), and a Vec match is refined per constructor (impossible arms are not required, a wrong-length constructor is rejected), but Eq index refinement, field-pattern arms, implicit type arguments, and a type application used as a value are still missing. An explicit type argument executes: sigma_snd I64 (fn (a : I64) => I64) (Sigma.dpair 1 2) compiles and returns 2. Propositional Eq type-checks but cannot be eliminated — Eq.rec's native is unimplemented and matching on refl fails at run time. Universe polymorphism is partial: Sort u and level variables work self-hosted (generalized per def, usable at Prop and Type), but there is no {u : Universe} binder, no max/+1 level syntax, no level instantiation at call sites, and the host has concrete levels only. |
| Macros | Working | defmacro, quote, and reflection-as-data. Term macros work here and not on the host — the one divergence in that direction. |
| Modules & visibility | Working | pub/priv/package-private enforced at every reference by both compilers (mote and module boundaries, instances included), explicit import filters, unused-import warnings. Resolution is mote-based — a mote's own root first, the directory cascade as the script-mode fallback — and check/test take --workspace or the mote you are standing in (compile takes an explicit path). |
| Tuples, raw strings | Working | Both real and stable. |
| Optics | Working | Lens and Prism in init.optics. |
| Indexed monads | Experimental | IndexedMonad, IndexedMonadState and IndexedMonadLift exist and type-check, and examples/indexed_monads.mo exercises them. The Monad (M I I) bridge instance in the prelude does not dispatch (variable head), so an indexed monad still needs its own Monad instance written out. |
| Termination checking | Working | A structural subterm check, run once per module over that module's own declarations by both compilers, with the same message either way. Recursion over an inductive type is accepted; counting down an I64 needs #[terminating], #[decreasing ...] or #[partial]. |
| Linear & affine types | Partial | The affine default is enforced on every check/compile path: an unannotated binder is ≤1 unless Copy A resolves (per-mote [affine] mode = "warn" while a mote migrates, and a single def can opt out with #[allow_non_affine "<reason>"]). There is no annotation syntax — the !/?/% prefixes were parsed but never enforced and have been removed; linearity is declared on the type (#[linear], #[proof]). Freeing is experimental: the default build emits no drop glue (Boehm reclaims), and MONAD_OWNERSHIP=1 frees a narrow Owned class (see Memory Model). |
#[derive BEq BOrd Debug Lens Copy Clone] |
Working | Both compilers bridge the attribute to the same std/derive.mo macros. The backend must be imported — #[derive BEq] dispatches to derive_beq by name. Copy/Clone are monomorphic-only: a generic type is rejected because the generated instance cannot carry the constraints it would need. |
Char literals 'M' |
Working | Parse, type-check and compile, escapes included, \u{...} on both. Char itself is a stub: no operations, no BEq, no ToString — you can write, type and pass one, not inspect it. |
_ holes in term position |
Partial | In type position ((x : _)) it works. In value position both compilers accept it and both lower it to a value that is not what you meant (I64.beq _ 0 fails under each) — write the value. A hole in infer position, where no expected type reaches it (def k : I64 := (fn x => x) _), is rejected by both, with the host's own "cannot infer the type of a hole"; that divergence used to open the other way and closed on this branch. |
| Named instances | Partial | instance Name : Class Type { … } parses on both, bare or dotted (instance My.Greet : Greet I64). Nothing selects an instance by name in either implementation. |
| Brace-form params with defaults | Working | The declaration parses and the default is applied at call sites by both compilers: omit factor in scale { p := 4 } and the declared := 2 stands in. |
Multi-binding let x := 1; y := 2 in |
Working | The ; separator parses on both. Write it: self-hosted, an omitted ; lets the binding's value swallow the next statement as an argument (see the appendix), so the binder never scopes. Nested let … in still works everywhere. |
UFCS method calls (x.f args) |
Planned | An earlier host type checker desugared these; neither does now. x.f is field access only. |
Backtick infix (`f`) |
Planned | The parser recognises the token; the expression parser never reduces it. |
for loops |
Planned | for is reserved with no grammar rule. |
| Reading stdin | Planned | IO can print and touch files; there is no getLine. |
Implementation
| Area | Level | What that means |
|---|---|---|
| Self-hosted compiler | Working | ~64k lines of Monad in lang/. It compiles itself, and the result type-checks the compiler's own source. CI runs this on every push. The bootstrap has reached a fixpoint. |
| LLVM native backend | Partial | Arithmetic, strings, file I/O and the seven concurrency natives are wired. A program reaching an unwired native fails to compile rather than miscompiling — one of four fail-fast gates. |
monad check |
Working | The corpus checks clean, and the check phase of CI's sweep carries no exclusion list. check takes explicit paths, --workspace, or the mote you are standing in. |
monad run |
Working | Compiles the file and executes the binary in one step. The binary is always named run_out, so there is no -o. |
monad eval |
Partial | A self-hosted interpreter over the pure native table (integer arithmetic/comparison/conversion and the String operations). IO, files, processes, env and concurrency are not wired, so it cannot run a hello-world; print Eval result <value>. |
monad repl |
Partial | The same evaluator, interactively: expressions print value : type, declarations and use persist in a session, :help/:quit/:reset/:type and multi-line defs work. Pure programs only; no line editing, history or interrupt handling. |
monad version |
Working | Prints the git commit baked in at link time. |
monad test |
Working | Runs the whole corpus, including the concurrency tests, with no exclusion list: a compiled driver per file, per-test timing, module::test_name names, and a failure COUNT the driver reports through a result file (no longer an 8-bit exit code, so a file's test count is no longer capped at 255). Takes explicit paths, --workspace, or the mote you are standing in. |
monad pretty |
Working | Parses and pretty-prints. |
| Memory management | Partial | Compiled binaries use the Boehm conservative GC, explicitly a stopgap. The compiler still emits no monad_retain/monad_release calls for ordinary values, so the refcount is only load-bearing for fiber and scope handles (see below). A MONAD_OWNERSHIP=1 build opts into deterministic freeing: monomorphic, non-Copy constructors are calloc'd and freed by generated drop glue at definition exits (unused binders only), while closures, generic data and region-owned values continue to leak. The mode refuses motes still in [affine] mode = "warn". |
| Concurrency | Experimental | Real concurrency on 1:1 pthreads: forkIO starts a thread, await_fiber waits for it and returns Result FiberError A, scope_* keeps handles alive through the atomic refcount. Cancellation is recorded rather than preemptive, and awaiting a cancelled fiber is an error. The host is still the lazy/cooperative one, so only compiled code can actually interleave. |
| Error messages | Partial | Source spans and useful text for most failures. Parse errors report "did not fully parse (stopped before end of file)" with the remaining text, which locates the line but not the construct. |
Ecosystem
| Area | Level | What that means |
|---|---|---|
| Standard library | Partial | ~440 public definitions, 35 classes, 132 instances. Strong: the numeric tower (10 widths, fully instanced), strings, lists, HashMap/BTreeMap, a native-backed Array, a pure-Monad SHA-256. Thin: no Iterator, zero Traversable instances, duplicate Semigroup/Monoid. |
Assertions (std.test) |
Stub | Test.assert is the identity function on Bool. No assert_eq, no failure messages. |
| Distribution | Partial | A nightly prerelease is published on every push to main, and monadup — a Monad-written binary mote, not a shell script — installs and switches between them. Three artifacts per platform: the compiler, monadup-<platform> itself, and a tarball of the init/std/llvm/runtime sources, which monadup unpacks into the same directory so an installed toolchain can compile a mote that lives outside a checkout. Four platforms — x86_64-linux and aarch64-darwin built and verified natively, aarch64-linux and experimental riscv64-linux cross-built and verified under QEMU. Linux binaries are fully static and the macOS one links only libSystem, so they run on a plain machine; compiling a program still needs llc, clang, pkg-config and Boehm GC, which monadup doctor checks. monadup env, doctor --json, and new are part of the same binary. |
| Packages | Working | Manifests are read: a module path resolves from the mote doing the use, and check/test/compile take --workspace or the mote you are standing in. Script modules declare theirs inline with #![mote { … }]. No search-path flag, and no lockfile or registry — those stay host-only. |
| Editor tooling | Host only | The LSP server, MCP server, REPL, and organize-imports all live in the host. No syntax highlighting for any editor, and no tree-sitter grammar. |
| CI | Working | Lint, full test sweep, and a self-hosting bootstrap check on every push. The release build runs inside the test and bootstrap jobs, not as a separate gate. The sweep runs the self-hosted runner against a freshly self-compiled binary, so monad test itself is covered. |
| Documentation | Partial | This book. Every code block is type-checked; prose is not. |
| Formatter | Working | monad fmt canonicalizes whitespace, indentation and blank runs through a lossless tokenizer; it preserves comments and author line breaks and never rewrites tokens. The whole corpus is formatted and CI gates it with scripts/check-fmt.sh. No line-width reflow yet. organize-imports, in the host, remains the only codemod. |
| Package registry | Planned | |
| Doc generator | Planned | Docstrings are parsed and retained, but nothing renders them. |
| Debugger integration | Planned | DWARF is emitted by default now (--release opts out) and carries a distinct location per term, not one per top-level definition — but nothing consumes it yet. |
Scale
For context on what "alpha" means here:
Monad source (.mo) |
~81,500 lines, of which lang/ is ~64,500 |
| Rust source (bootstrap host) | ~56,400 lines |
Monad tests (#[test]) |
2,112 run by CI's sweep — every one through the self-hosted runner |
| Native functions | 137 declared in init/+std/; 3 unimplemented everywhere; the backend wires a subset |
| Standard library | ~440 public defs, 35 classes, 132 instances (excluding test modules) |
The Short Version
Monad is a real, self-hosting language: the compiler is written in Monad, compiles itself, and reaches a fixpoint. The type checker, the class system, the module system, and a genuine macro system all work.
What it is not yet: safe by construction (the affine usage rule is enforced
and #[linear] types are used exactly once, but nothing frees memory yet —
compiled binaries still need a garbage collector), scalable in concurrency
(fibers are 1:1 pthreads with 128 MB stacks, real but not the design that
ships), or distributable (nightly binaries exist; a lockfile and a registry
do not). Its test runner compiles and runs a driver binary per test file, and
covers the whole corpus with no exclusion list — every file that used to be
reported as a gap now runs self-hosted.
The single largest gap is deterministic memory management — the affine rule is the precondition for it, and freeing is the milestone that replaces the collector.