> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# The charter

> The thesis, the phases, and the explicit non-goals. The Mzizi Research Charter, v0.4, “Mzizi: a general-purpose programming language” — a direction and a phasing, not a sprint plan.

<Note>
  **Charter v0.4 is on `main`.** Its title is *"Mzizi: a general-purpose programming
  language"*, and it opens with the owner's tagline: *"Mzizi is built to make Rust better, the
  way TypeScript makes JavaScript better."* It states that as the goal Phase 0 exists to test,
  not a result: *"Nothing in this charter has been measured against it yet."* What Mzizi can do
  today is tracked in [`LANGUAGE-TRACKER.md`](/tracker), not in the charter.
</Note>

Mzizi's direction is set by a single document:
[`CHARTER.md`](https://github.com/mzizi-dev/mzizi/blob/main/CHARTER.md), the project's
**Mzizi Research Charter, v0.4**. Its own status line reads *"charter draft — defines direction and
phasing, not a sprint plan"*, and this page summarises it rather than replacing it.

## What v0.4 changed

Version 0.4 records five owner-directed changes of 30 September 2026. The charter's own
summary: *"The gate, the kill criterion and the benchmark settings are unchanged, and nothing
is claimed before it is measured."*

1. **Mzizi is a general-purpose programming language**, not a framework. Rust is its
   platform, the way JavaScript is TypeScript's, and Mzizi Roots is its component model, the
   way React is JavaScript's.
2. **One goal.** The language repository's goal, and Phase 0's only goal, is building Mzizi as
   a language that stands against the best existing language for each kind of task:
   TypeScript, Python, C++, Go and Rust.
3. **The harness is the core of the language:** what an agent reads, and what the toolchain
   and plugins attach to. It lives in the language repository, and its design is
   [RFC-0012](/rfcs), a draft.
4. **The toolchain and the components support the language; they are not the language.**
5. **Phase 0 is scoped to the goal.** The component tasks against Dioxus and Leptos, the pilots
   among them, are tests within it, and the 29 September amendment to §4 is folded into the
   main text.

## The 29 September changes, still in force

The charter's previous revision recorded four owner-directed changes of 29 September 2026,
and v0.4 keeps all of them:

1. **The backend goal.** Mzizi builds Mzizi's entire backend infrastructure in Mzizi. None of
   it is today: `api.mzizi.dev` is a Hono Worker in TypeScript. It is the target, not the
   state, and nothing is ported until the `backend` task family passes the kill criterion.
2. **Two frontend paths.** Astro with the Mzizi UI (Mzizi Roots) underneath, or pure Rust end
   to end. Both are authored in Mzizi; they differ in host and lowering target.
3. **Everything has a contract.** Components, language functions, handlers, services and the
   standard library, specified in
   [RFC-0010](https://github.com/mzizi-dev/mzizi/blob/main/design/RFC-0010-contracts-everywhere.md).
   Components' and services' contracts run today; the rest is proposed, not built.
4. **The kill criterion is Mzizi against the best existing language for each kind of task**,
   and every benchmark run is published
   ([RFC-0009](https://github.com/mzizi-dev/mzizi/blob/main/design/RFC-0009-comparison-benchmark.md)).
   Not yet measured.

**Owner:** Mzizi — 100%. The Mzizi language, its toolchain, its components and its logic
are Mzizi IP. The Mzizi
console ("Fundi") and active cyber testing are adjacent and run under Nyuchi. Copyright
notices name the Bundu Foundation as the parent copyright holder; Mzizi is not a separate
legal entity.

## The thesis

The charter opens with how languages and frameworks win: by being unmistakably better at one
thing first. *"TypeScript did not replace JavaScript: it made JavaScript better to write, and
it still compiles to JavaScript and runs wherever JavaScript runs."*

What Mzizi is, in v0.4's words:

> A general-purpose programming language, with Rust as its platform, the way JavaScript is
> TypeScript's.

Mzizi is designed to lower to Rust, with no borrow, lifetime or ownership concept at the
surface: the compiler is to own that plumbing in the Rust it emits, so an agent never has to.
The aim is that Mzizi does Rust better: you write Mzizi instead of TypeScript, Python or C++,
and get Rust underneath. The charter is explicit: *"That is the design and the goal, not the
state."* Its §1 still says `mz` emits no Rust; since the backend slice merged (language PRs
\#29–#33), `mz build` lowers a `service` to a local Rust + axum package, and nothing else lowers.
[The tracker](/tracker) is the fact.

Mzizi's single sharp edge:

> Its syntax, type system, and compiler feedback loop are designed for machine authorship,
> not just human ergonomics.

The charter's argument for why the field is open: every existing language, Rust, TypeScript,
Python or otherwise, was designed assuming a human is typing, reading docs, and holding
context in their head. None of them are designed for an agent iterating against a compiler
thousands of times, where compile speed, error density and token-efficient representation
are first-order metrics.

**The harness is the core of the language.** It is what an agent reads and works through: the
language's agent-facing definition, the agent protocol (`mz check --agent`, its diagnostics
and fixes) and the plugin host 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. Of it, only the agent protocol and the IR exist today.

Everything else — cross-platform reach, ML integration, edge deployment — is Mzizi
*integrating* with what already exists well, not out-building specialists at their own game.

## What that has to cash out as

Five measurable design goals, not a slogan:

<AccordionGroup>
  <Accordion title="Low syntactic ambiguity">
    Fewer distinct-but-equivalent ways to express one intent. Every degree of freedom in
    "how you could have written this" is a degree of freedom a model can get subtly wrong.
  </Accordion>

  <Accordion title="Dense, high-signal compiler errors">
    The loop is generate → compile → read error → fix → recompile, and its quality is
    bounded by how much *actionable* information is packed into the compiler's output per
    character. A compiler UX problem aimed at a machine reader.
  </Accordion>

  <Accordion title="Fast incremental compilation">
    Humans tolerate a few seconds per iteration. An agent iterating hundreds of times per
    session treats compile latency as the dominant cost of the whole workflow. Compile speed
    is a Phase 0 success metric, not an optimisation to defer.
  </Accordion>

  <Accordion title="Everything has a contract">
    Every component, language function, handler, service and standard-library function
    carries an in-language contract the toolchain checks. A contract may constrain only a value
    the program renders or returns, never a declared copy of it: pilot 2 caught a touch-floor
    contract checking a number the component does not render. Components and services carry
    contracts today; the rest is [RFC-0010](/rfcs).
  </Accordion>

  <Accordion title="Token-efficient representation">
    A codebase that fits more real logic into a context window per token spent is one an
    agent can reason about more completely, with less summarisation loss. Applies to the
    syntax surface *and* any intermediate representation the tooling exposes.
  </Accordion>
</AccordionGroup>

## What is novel and what is borrowed

The charter is precise about which layer is the research contribution, which matters because
it bounds what Mzizi is claiming to have invented. Version 0.2 widened the scope from web UI
to general-purpose software for the agentic world, the 29 September revision added Mzizi's
own backend, and v0.4 calls Mzizi a general-purpose programming language; the UI component tasks in Phase 0 are the
first, smallest, most measurable slice of that claim, not the whole of it.

| Layer | Approach |
| - | - |
| **The language, with the harness at its core** | **Novel.** The syntax, the type system, the semantics and the contracts, and the harness an agent reads them through. The research contribution. The toolchain is not the language: the compiler, CLI, MCP server and plugins support it. |
| **UI layer** | **`mzizi-ui`, Mzizi's own component registry, is first-class.** Dioxus is a compatible third-party rendering target for it, as any Rust UI registry adopting the same contract would be — not the UI strategy itself. |
| **Full-stack (UI + server)** | A component and the handler that serves it ship from the same Mzizi source. The server half is lowered per target, and handlers reach target-specific facilities only through declared capabilities. |
| **Edge: Workers and Containers** | **First-class from day one.** Workers lower to `workers-rs` (wasm32); Containers lower to a native Rust HTTP server (axum-class) packaged as a container image and reached from a Worker through the Container binding. |
| **ML workloads** | **Native integration with Candle.** Components declare and consume inference as a first-class capability; Mzizi does not build a competing tensor runtime. |
| **Native mobile** | Two tracks: `mzizi-ui` through a compatible mobile engine (Dioxus today) near-term; native Swift/ArkTS/Kotlin codegen from the same Rust core later, separately scoped. Named, not designed. |
| **Hardware / embedded** | A named future direction, unscoped until Phase 1 has a real deployment. |
| **Compiled artifact** | WASM, and native for desktop and compatible-renderer mobile. A real native-per-platform artifact belongs to the later native-mobile track. |
| **Post-quantum cryptography** | **Explicitly deferred.** A future research thread, named so it does not dilute Phase 0. |

## The phasing

<Steps>
  <Step title="Phase 0 — show that Mzizi can stand against the best existing language for each kind of task" icon="flask-conical">
    **The goal (v0.4 §4):** show, on a real measurement, that Mzizi can stand against the best
    existing language for each kind of task, in RFC-0009's gating families: UI components
    (against Dioxus, Leptos and React/TypeScript) and backend handlers and services (against
    TypeScript, Python, Go, C++ and Rust), with downstream work gated per family. Phase 0
    builds Mzizi as a programming language to that end, and it is the language repository's
    only goal.

    As v0.1 first wrote it, the charter titled this phase "prove the core claim, no
    rendering attached": a standalone compiler/syntax prototype, and a benchmark where an
    agent authors N equivalent components in Mzizi versus raw Dioxus/Leptos, measured on
    tokens consumed, iterations to a clean compile, and defect rate. v0.4 says so outright:
    *"The component tasks are tests within Phase 0, not its goal."*

    ***"If this doesn't show a measurable advantage, nothing downstream matters — don't
    build Phase 1 until Phase 0 has a real number attached to it."***

    This is where the project is. The gating run has not happened. See [Status](/status) and
    [the benchmark](/benchmark).
  </Step>

  <Step title="Phase 1 — full stack: mzizi-ui plus Cloudflare Workers and Containers" icon="box">
    A Mzizi-authored full-stack application, actually deployed to Cloudflare: UI through
    `mzizi-ui` rendered by a compatible engine (Dioxus today), server and API from the same
    source, as a Worker or a Container depending on the workload. This merges what v0.1
    called Phase 1 (rendering interop) and Phase 2 (edge deployment).

    The UI output must also ship as a **self-contained artifact** usable without the Phase 1
    Worker — an ES module or custom element with its WASM bundle, loadable from a plain
    `<script type="module">`, a WebView or a WASM host. That is what "standing alone" means.
    Building a native renderer or a bespoke edge runtime here is scope creep.
  </Step>

  <Step title="Phase 2 — Candle integration" icon="brain">
    First-class support for declaring ML inference inside components, backed by Candle. The
    `use ml` capability parses today and is specified to error as "not yet available".
  </Step>

  <Step title="Phase 3 — native mobile: interop first" icon="smartphone">
    `mzizi-ui` through a compatible mobile engine first — the same interop bet as Phase 1.
    Generating idiomatic native Swift/ArkTS/Kotlin from the same Rust core is real and named
    but needs its own RFC before it is a phase with a deliverable.
  </Step>

  <Step title="Phase 4 — distribution adapters" icon="package">
    Once Phase 1's self-contained artifact stands alone, framework-specific adapters are thin
    packaging layers rather than new compiler work. Astro is one such adapter, using the
    Custom Element pattern. Since 29 September, Astro with Mzizi Roots underneath is one of the two
    frontend paths, so that integration is a packaging task that can ship as soon as Phase 1's
    self-contained artifact exists, without waiting for the rest of this phase.
  </Step>

  <Step title="Phase 5 — hardware and embedded" icon="cpu">
    Named, not designed. Revisit once Phase 1 has shipped a real full-stack deployment.
  </Step>
</Steps>

## Explicit non-goals

* Not building a competing tensor or ML runtime. Candle is the dependency.
* Not building a bespoke rendering engine before proven interop is tried and found
  insufficient. Owning the component contract (`mzizi-ui`) is not the same claim as owning the
  renderer underneath it.
* Not addressing post-quantum cryptography in this charter.
* Not committing to hardware or embedded specifics in this version.
* Not blocked by, or blocking, Nyuchi/Mukoko revenue-phase work — different org, different
  clock, per Mzizi's non-revenue research mandate.

## What the charter still leaves open

The charter's open-questions section now carries a dated status line on each item.

**The reference-implementation half of the defect metric.** `mz contract` evaluates a
component's assertions against the component itself. The benchmark harness
(`benchmarks/harness/` in `mzizi-dev/mzizi`) now reads the `.rs` reference and scores a
candidate against it, as RFC-0006 §10.1 resolved.

**Benchmark harness mechanics.** Specified and implemented in the `mzbench` runner and the
kill-criterion driver. Two pilots were scored on 2026-09-27, one frontier-only and one with a
\~7B open-weight arm, and neither showed an advantage for Mzizi. Neither is the Phase 0
number. The held-out task set is still open. See [the pilot results](/pilots).

**The backend measurement slice.** Settled: the minimum language work to author, check, lower
and run the backend tasks locally counts as Phase 0 measurement work (RFC-0009 §6.4). It covers
no deployment and no port of a live service. It is now mostly built as
[RFC-0011](/rfcs): a `service` is checked, run in process and lowered to a local Rust + axum
package, and the `mzizi-be` arm exists. No backend episode has run. See
[the roadmap](/roadmap).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.