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 harness, the core of the language and what the agent reads, and it is a design. This index lists only what is merged, and takes every capability claim from LANGUAGE-TRACKER.md. 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 provisional) 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 harness: the core of the language

The harness is the core of the language: what the agent reads. It has three parts: the language as an agent reads it (grammar, types, contract forms and canonical form, as one machine-readable definition), the agent protocol (mz check --agent, mz fix, mz contract and the RFC-0003 read surface), and the plugin host that the toolchain, the CLI, the MCP server and plugins attach to natively. It lives in the language repository; mzizi-cli, mzizi-mcp and fundi are its clients. It also plans how the agent skills fold into it. It is a different thing from benchmarks/harness/, which is always called the benchmark harness. Exists today (§2): the agent protocol and the read surface (mz outline, mz ir, mz hash). Design only: the language as one machine-readable definition, the plugin host, and mz harness. Leaves open: the implementation language, the shape of the language definition, dynamic plugin discovery, whether the skills are retired or generated, protocol versioning, and the plugin sandbox. → What still has to be built

---

​

Reading order