The Mzizi Cookbook

git clone https://github.com/mzizi-dev/mzizi && cd mzizi
cargo build --release -p mzizi-lang-compiler    # builds target/release/mz
export PATH="$PWD/target/release:$PATH"

​

1. Write and check a component

component separator

  enum separator_axis
    horizontal  class "h-px w-full"
    vertical    class "w-px self-stretch"
  end

  prop axis: separator_axis = horizontal
  prop decorative: bool = true

  view
    rule
      slot = "separator"
      axis = axis
      decorative = decorative
      class = "shrink-0 bg-border {axis.class}"
    end
  end

  contract
    separator_axis.horizontal class contains "w-full"
    separator_axis.vertical class contains "self-stretch"
    slot is "separator"
  end

end component separator

mz check --agent file.mz    # NDJSON diagnostics, then a summary line
mz fix file.mz              # apply every exact fix, then re-check
mz contract file.mz         # evaluates the contract against the component
mz outline file.mz          # the signature view an agent can read cheaply

​

2. Write a service and run its contract

service registry

  record health
    field status: text
  end

  route health_check
    get "/v1/health"
    respond 200 json health status "ok"
  end

  fallback
    respond 404 json health status "not found"
  end

  contract
    example get "/v1/health" status is 200
    example get "/v1/health" body.status is "ok"
    example get "/nope" status is 404
    ensure status in 200 204 308 404 405
  end

end service registry

mz check examples/registry.mz      # mz: 0 errors (0 exact-fixable)
mz contract examples/registry.mz   # 22 contract clauses, 0 failed, tested over 61 generated requests

​

3. Build a service and run it in a container

mz build examples/registry.mz --out ./registry-svc

# Not run for this page: it is a recipe built from the generated package's behaviour.
FROM rust:1 AS build
RUN rustup target add x86_64-unknown-linux-musl
WORKDIR /svc
COPY registry-svc/ .
RUN cargo build --release --target x86_64-unknown-linux-musl

FROM scratch
COPY --from=build /svc/target/x86_64-unknown-linux-musl/release/mz-registry /mz-registry
COPY --from=build /svc/fixtures /fixtures
ENV HOST=0.0.0.0 PORT=8080
EXPOSE 8080
ENTRYPOINT ["/mz-registry"]

​

4. Write a program and mz run

program hello

  fn main
    print("hello, world")
  end fn main

end program hello

mz run examples/hello.mz         # prints: hello, world
mz run --release examples/fib.mz # a release build

{"code":"MZ0923","severity":"error","span":[4,5,4,6],"say":"`x` is assigned before it is bound — a binding starts with `let`: `let x = 2.pow(3)`","fix":{"span":[4,5,4,5],"replace":"let ","confidence":"exact"}}
{"code":"MZ0910","severity":"error","span":[4,11,4,13],"say":"`**` is not a Mzizi operator — a power is the method `x.pow(n)`, with an int `n`","fix":{"span":[4,9,4,15],"replace":"2.pow(3)","confidence":"guess"}}
{"summary":true,"errors":2,"warnings":0,"exact_fixable":1,"ms":8}

​

5. Add a diagnostic, with its fix and harness entry

1. Name the failure mode the diagnostic removes (an idiom another language brings, a cascade of errors that hides the cause). If it cannot be named, it does not belong.
2. Emit the code in compiler/src, with a say text that tells the reader what to write, and a fix whose confidence is exact only when the fix is certain. A fix that needs an operand it does not have is not exact (RFC-0006 §8.2 was corrected on exactly this).
3. Register it in compiler/src/harness.rs: one Code in CODES with a trigger source that emits it, and the feature’s entry in FEATURES with tested examples (including their output, for a program).
4. Test it: compiler/tests/harness.rs enforces that every construct and code is registered, and the example’s trigger must fire the code.
5. Check what an agent will read: mz harness entry MZ0923 prints the entry. For MZ0923 it showed "fixes": ["exact","guess"], the programs that raise it, and its trigger source.
6. Update LANGUAGE-TRACKER.md if a row’s status changes, and add a CHANGELOG.md entry under ## [Unreleased], in the same pull request.
7. Regenerate the docs table. The MZ09xx table on The compiler is mz harness definition at the commit it names; do not hand-edit it.

​

6. Add an RFC

1. Take the next free number. Numbers are never reused, and RFC-0005 is reserved. Check open issues and open pull requests as well as design/.
2. File: design/RFC-NNNN-kebab-case-topic.md, with the H1 # RFC-NNNN — <what it settles>.
3. Header block, three bold fields and a rule: Status (state implementation precisely; there is no “accepted”), Author, Scope (what it settles and what it defers).
4. Design against named failure modes and cite them in the headings.
5. Use real examples (a component with a reference, or a primitive). Measure any number with a test, and label a prediction as one.
6. Record corrections in place: an amendment note on the earlier RFC, and a struck-through, answered open question.
7. End with open questions, addressed to the next RFC by number.
8. Open the pull request with the implementation in the same branch where you can, and the tracker, harness and changelog updates that go with it.

​

7. Run a benchmark episode

cargo build --workspace
EP=$(mzbench episode start --task benchmarks/tasks/button --arm mzizi \
       --model-label <label> --out results --seed 1)
# give the author "$EP/prompt.md"; it writes candidate.mz and submits it:
mzbench episode submit "$EP" candidate.mz    # exit 0 clean, 1 errors, 2 refused
mzbench episode finish "$EP"                 # only after the author has reported
mzbench summarize results

• Finish an episode only after its author has reported. Pilot 3 finished one early and had to revert the premature line, and says so.
• Register a PLAN.md before the first episode (mzbench plan) and do not change it afterwards. Then publish the raw episodes, the run record and every departure.
• Say what the run is not. A pilot on public tasks declares no pass or fail. Only a run that applies RFC-0009 §6 on held-out tasks with the ~7B model can test the kill criterion.
• Do not name a model in a docs page. Say “a frontier model” and link the write-up, which names it.

​

8. File a good issue

• Names the repository that owns the problem, and the file or command. A language bug goes in mzizi-dev/mzizi; a component in mzizi-dev/mzizi-registry; a docs error in mzizi-dev/mzizi-docs.
• Gives a reproduction that runs: the exact .mz file, the command, the output it printed, and what you expected. Say which commit of mz you built.
• Separates tested from designed: say whether you saw a thing happen, or read it in an RFC.
• For substantial work, holds the goal, the owner’s decisions verbatim, the plan, acceptance criteria and owner-only steps, so another session or person can pick it up. Every pull request then references it with Refs #n.
• Never contains a secret, a credential’s status, or exploitable detail on a public repository. Security reports go to security@nyuchi.com, not an issue.