RFC index

The RFCs are the design record. They live in design/ in mzizi-dev/mzizi, and the repository’s own README says to read them first. Two things to know before reading any of them. They argue with each other, on purpose. RFC-0002 opens by declaring RFC-0001’s design target wrong and inverting three of its conclusions. RFC-0003 records a claim its own test suite falsified mid-implementation. RFC-0004 opens by correcting the premise it was commissioned on. That is the intended shape of the record, not disorder in it. RFC-0005 is reserved, not missing. The number was reserved for a catalogue-and-language RFC in the private tooling repository before RFC-0006 was written, and it is left free rather than reused. Two RFCs set the owner’s 29 September direction. RFC-0009 is the benchmark across languages and the new kill criterion; RFC-0010 is contracts on everything built. Both status lines still say nothing in them is implemented; parts of each have since been built, and their sections below say which. Two more are new on 30 September. RFC-0011 is handlers, the backend measurement slice, and most of it is built. RFC-0012 is the language harness, the spine of the language and what the agent reads; a first slice of it is built. RFC-0013, the core language, followed on 7 October, and its first waves are built. This index takes every capability claim from LANGUAGE-TRACKER.md, and lists what is on main. The status headers are historical. RFC-0001 and RFC-0002 both say “nothing here is implemented”. That was true when written. The front end now exists — see Status for where the documents and the code have since diverged.

---

​

RFC-0001 — Surface syntax, canonical form, and the agent protocol

The nine failure modes an agent hits writing Rust UI code, and the syntax that answers each. end <kind> <name> with a cross-checked name echo; one construct per intent; enum data columns instead of parallel maps; contract blocks in the language; capability declarations at the top; no ownership surface at all. Also specifies canonical form (the compiler owns formatting, no configuration) and the mz check --agent protocol: whole-program NDJSON in deterministic order, at most one diagnostic per real error, messages written for a reader with zero file context, and fixes as machine-applicable data tagged exact / guess / none. Its own method rule: “If a decision doesn’t trace to a failure mode, it doesn’t belong in the language.” Leaves open: local state; the grammar formalism; the IR; whether component name must match file name. → Syntax · The compiler

---

​

RFC-0002 — The design target, the runtime as the product, and what to mine

The correction that reshaped the project. RFC-0001 was written by a frontier model reasoning about its own experience, which optimised for the author rather than the population. The design target is small models — a 7B open-weight model running locally — and that inverts three conclusions: token efficiency is permanently first-order, the end echo is an error-correcting code for weak long-range attention rather than parser elegance, and a small closed grammar beats a familiar open one. Also establishes that the runtime is the product (“shared logic, written once, running everywhere”), commits to the content-addressed IR, and surveys thirteen languages for what to borrow — Elm’s error design, Roc’s platform/application split, Gleam’s tiny keyword set, Unison’s content-addressed codebase, Zig’s no-hidden-control-flow rule, Tree-sitter’s error-tolerant parsing — each with an explicit licence note. The licence discipline is stated once and is unambiguous: design ideas are free; code carries obligations; GPL/AGPL sources must not be copied into the project at all, and anything borrowed as code must be recorded in a NOTICE file. §3.1 names what is genuinely missing everywhere, which is the defensible research contribution: contracts in the language checked by the toolchain; a diagnostic protocol designed for a machine reader; a content-addressed IR wired to an agent-facing patch API; and a grammar whose ambiguity budget is deliberately near zero. Leaves open: local state; the IR’s concrete shape; effect-system depth; how far contract expressiveness should go before it becomes a proof assistant. → Overview · Syntax

---

​

RFC-0003 — The content-addressed IR and the agent’s read/write surface

The other half of the loop: eight barriers an agent hits reading a codebase, and the content-addressed IR that answers seven of them from one decision. The node model, the length-prefixed canonical serialization, hand-rolled SHA-256 verified against NIST vectors, structural sharing, mz outline, and the query/patch surface. Contains the project’s most instructive paragraph: §7.1, where the measured suite falsified the RFC’s own claim that structural paths are “stable across edits”, and the claim was narrowed to what is true rather than defended. Leaves open: local state under content addressing; the patch API’s conflict model; store persistence; contract evaluation semantics. → The content-addressed IR

---

​

RFC-0004 — Test topology: what stays public, what goes private, and why

Which test infrastructure stays public (nearly all of it, permanently), which is held out (a benchmark task set), and the dependency rule that keeps forks working: private consumes public, public never consumes private. Opens by rejecting the reason it was commissioned on. Private tests are close to worthless as a security control; the one legitimate reason here is measurement validity, because a public benchmark task set gets scraped into training data and a contaminated benchmark looks exactly like a successful one. Leaves open: held-out set rotation policy; a path for third-party verification of a published benchmark claim. → The Phase 0 benchmark

---

​

RFC-0006 — Contract evaluation

What a contract block means: the clause grammar, a fixed subject-resolution order, what the evaluator checks and what it deliberately does not, and why contracts participate in the IR hash. It also argues why evaluation is its own subcommand rather than part of mz check: the Phase 0 defect metric counts what gets past the compiler wrong, so the two exit codes must stay apart. §10.1 specifies the reference comparison that the benchmark harness now does. Leaves open: lowering contracts to Rust tests (Phase 1); contract predicates over collections and records. → The compiler

---

​

RFC-0007 — What the language is missing for the scope the charter claims

Written after the first pilot. It lists every piece of language and toolchain infrastructure the charter’s v0.2 scope needs and the code does not have, checks each claim against the code, and proposes an order. Tier 0 is what the benchmark itself needs: name and type checking, lists, records, options and iteration. Leaves open: the one-way design doors it names in §4, and the order past Tier 0. → Direction and roadmap

---

​

RFC-0008 — Types, collections, records, and a checker that can say no

RFC-0007’s first five Tier 0 gaps: name and type resolution for everything the syntax tree models, list(T), record, option(T) and for each. It also makes else real, which RFC-0001 always listed and the parser used to reject. Every 7B badge episode in the second pilot stalled on that. Leaves open: collection and record contract predicates, enum payloads, modules and cross-file checking, local state, and lowering. → Syntax

---

​

RFC-0009 — The comparison benchmark

Built since: the runner’s arm.toml and spec.md input, the react arm (never run, its pins from the registry’s lockfile) and the mzizi-be arm with the probe crate and task B1 (never run) (benchmarks/READINESS.md). Nothing has been measured. Every language arm, every task family, and a gate against the best incumbent. It opens with six ways a cross-language comparison goes wrong, such as handing a React arm a React spec to “port”, or pooling UI and backend results so a win hides a loss. It then defines the arms (adding React, TypeScript, Python, Go, C++ and plain-Rust backends), the task families, what “compile or check” means per arm, and the fairness rules. §6 is the kill criterion: within each gating family, Mzizi must beat the best incumbent on at least two of three metrics, on the ~7B model, on held-out tasks, with a bootstrap 95% interval that excludes zero. Phase 0 passes only when both the UI and the backend families pass, and §6.4 counts the minimum language work for a Mzizi backend arm as Phase 0 work. §6.5 says, before the run, that a loss is the likely outcome on today’s compiler. §7 makes every run published, with a PLAN.md registered before it. Leaves open: Java and plain JavaScript arms; a Workers-runtime family; a variant where every arm runs its own tests in the loop; Astro pages as a family; the held-out rotation fraction. → The benchmark · What remains before the run

---

​

RFC-0010 — Contracts everywhere

Built since: through RFC-0011, a service’s contracts run in process. mz contract sends each example as one request and tests each ensure over a generated set of requests, which is tested, not proven. Contracts for functions and records are not built. The owner’s direction that everything built carries a contract: functions, handlers, services, records and the standard library, not only components. It sets the clause forms, which are checked statically, which by generated tests once code lowers and which at runtime in debug builds, how they lower to Rust, and what an agent sees when one fails. Its first failure mode was measured in pilot 2: a contract that checks a value the author declared rather than the one the program renders (FM-14). A missing contract becomes one lint, MZ0613, with two levels, warn and required. It is proposed, not built. Its grammar for functions depends on function declarations that no RFC has designed yet; RFC-0011 has since designed the handler declarations. Leaves open: mutation scoring of contract strength; release-mode checks; relational properties; cross-file contracts; whether mz outline carries contracts. → Direction and roadmap

---

​

RFC-0011 — Handlers: the backend measurement slice

The smallest language surface that lets a Mzizi program answer the HTTP probes of RFC-0009’s backend tasks: a service declaration with route blocks, handler bodies (when, header, respond), boundary data, the error model for handlers, handler contracts, and the lowering to Rust and axum. It opens with named failure modes (HD-) predicted from the incumbents and from the API gateway, such as an Allow header nobody updates. Built (§12, language PRs #29–#33): the front end, checked by mz check; the evaluator, so mz contract runs a service in process (examples/registry.mz, 22 clauses, its ensure clauses tested over 61 generated requests); the lowering, so mz build writes a local Rust + axum package, which CI compiles, tests and serves; and the mzizi-be arm, the probe crate mzprobe and task B1, whose Mzizi and axum references both hold all 59 of its facts. Not built: request bodies, and the runner scoring an episode with probes. No component lowers, and there is no Workers, Containers or WebAssembly target. Leaves open: state for B4; the text operations B3 needs; top-level routes once modules exist; property tests in the lowered crate. → The compiler · What still has to be built

---

​

RFC-0012 — The language harness: the spine of the language

The language harness is the spine of the language: every feature is defined once, as a harness entry inside the compiler (§1.1: name and kind, grammar, a teach paragraph, type rules, diagnostic codes with their say text and fix kinds, and tested examples), and mz harness definition, the agent skills and the benchmark guides are meant to be generated from or checked against those entries. §1.2’s registration rule: a pull request that adds or changes a feature adds or updates its entry, and a test fails when the compiler emits a code that has no entry and is not on the pending list, or builds a construct with no entry. It lives in the language repository; mzizi-cli, mzizi-mcp and fundi are its clients. It is a different thing from benchmarks/harness/, which is always called the benchmark harness. Exists today (§2, on main since 8 October 2026): the agent protocol and the read surface (mz outline, mz ir, mz hash), and a first slice of entries in compiler/src/harness.rs, served by mz harness version, definition [--agent] and entry <name>. Some facts have one source (command dispatch, operator spelling, precedence and types); some are parallel copies held by tests (severities, fix kinds, examples); and say and teaching text are written by hand and not compared with the checker. Design only: the plugin host, mz harness plugins, and generated skills and guides. §8, prior art (extended 7 October 2026) compares the design with the Language Server Protocol and rust-analyzer, Roslyn, the TypeScript language service, rustc and cargo JSON output, MCP servers for languages, Unison’s codebase manager, and Go’s go/analysis, and finds that none of them specifies its machine interface as part of its language. §9 decides question 3 (the definition comes from the compiler’s own entries, not a hand-written file) and adds question 9: whether an agent taught by the language harness does better is a hypothesis for the benchmark to test, not a result. Leaves open: dynamic plugin discovery, whether the skills are retired or generated, protocol versioning, and the plugin sandbox. → The language harness · What still has to be built

---

​

RFC-0013 — The core language (Tier 1)

One design for all of Tier 1 of the tracker (C1–C10), as the owner decided on 7 October 2026: one RFC per tier. It designs a program file kind with an entry point and printing; expressions and operators; bindings; functions; control flow in function bodies; int and float; the text and collection operations the language needs; methods on records; a result type and its propagation; how a program is run; how each construct lowers to Rust; a new range of diagnostic codes, MZ09xx; and the canonical form. Generics, interfaces and traits are deferred past M1. Its amendments (mzizi#81) take changes from the language survey below, and its §20 holds 29 questions for the owner. Q20 (the text operations’ “Done when”) was decided on 8 October 2026. Built (released to main on 8 October 2026): Wave 0 (mzizi#80), float and the numeric methods (#83), control flow (#89), errors (#87), collections and records with methods (#99, #101, #102) in the third release, and the text operations (#98 and #106) in the third and fourth. Programs documents them. Design only: options in function bodies (option(T) as a type, and narrowing it), named arguments beyond range’s to, slice’s to and fold’s step, try … via, a program’s contract block, mz test, mz run --agent and fn … changes self. The language survey (design/LANGUAGE-SURVEY.md, mzizi#75) is design input, not an RFC. It surveys the top 10 languages feature by feature, marks each of 63 features adopt, improve, already-has or reject for Mzizi, and says what RFC-0013 and the Tier 2 and Tier 3 RFCs must decide. Nothing in it is built, and it measures nothing. → Programs · M1: the plan

---

​

RFC-0014 — Tier 2 (a draft)

The design of Tier 2 of the tracker, the M2 goal: modules and imports across files, with module, import and public (P1); the standard library as a closed list, with std-only modules and one crate for HTTP (P2); lowering and runnable builds (P3, P4); errors mapped back to .mz by markers in the generated Rust (P5); and Rust crates through an exact pin and a hand-written companion checked by rustc (P6). It opens the MZ1001–MZ1099 range, proposes six waves with their tests, and asks the owner nineteen questions. Designed, not built. mz check does not accept import, module, public or extern today, and no test reads the draft. Its rows on the tracker are still ❌, 🟡 or 📝.

​

Reading order