Skip to content
Bundu Foundation

Research

··3 min read

The language harness: a programming language that describes itself to agents

In Mzizi, every feature registers in the language harness, so the whole language can be printed as one document an agent reads. Why we made it part of the build, and what is enforced.

By Bryan Fawcett

A model learns a mainstream language from millions of examples. A new language has none of that. If an agent is to write Mzizi well, the language has to tell it what Mzizi is: precisely, completely and in a form it can read.

That is the job of the language harness (RFC-0012). It is the spine of the language: every built feature registers in it.

What an entry holds

Each entry in the harness records:

  • the feature's grammar and its types;
  • every diagnostic code it can raise, with a trigger program that raises it, its severity and the kind of fix it offers;
  • examples, which are run as tests;
  • teaching text for an agent.

mz harness definition prints every entry as one JSON document. mz harness entry let prints one. mz harness version prints the protocol version, the language version and the definition's SHA-256, so a tool can tell when the language under it has changed.

On main today (v0.8.0), the harness holds 197 entries, 80 of them diagnostic codes.

Part of the build, not documentation that drifts

Documentation drifts because nothing fails when it is wrong. The harness is wired so that something does. cargo test in CI fails when:

  • a code the compiler can emit has no entry, and is not on a frozen pending list;
  • a trigger no longer raises its code, at its severity, with its declared fix kind;
  • an example no longer checks, or no longer prints what it says it prints;
  • a lexed operator has no entry.

Some facts come from one source, so they cannot disagree: command dispatch, each operator's spelling, precedence and operand types, and the type and method lists. In one case that single source found a real bug. The harness and the checker disagreed about where not sits in operator precedence; making both read one definition fixed it.

What is not enforced yet

We say this as plainly as the rest. Each code's short explanation and each feature's teaching text are written by hand, and the tests do not compare them with the checker. Keeping them true depends on reading the code. component and service are registered at the level of the file kind only. The plugin host, which would let tools attach to the harness, and the skills and guides generated from it, are designed and not built.

Why it matters for the research

Our September pilots showed a ~7B model stalling on idioms Mzizi had no form for, with diagnostics that did not say what to write instead. The harness is the structural answer: one place where the language says what exists, what each error means and what to write, kept honest by the build. Whether that measurably helps a small model is a question for the kill-criterion run, which has not happened yet.

Back to newsroom