muro-lang.dev / docs

For agents

In brief: two jobs. Do not mix them. This page is the operational contract. Humans can read it. You must.

Job A — write a Muro program

Do

  • Write a .muro file against Grammar.
  • Put new programs in examples/ unless asked otherwise.
  • Check with mix muro.check path.muro. If the answer is out of fuel, the checker gave up reducing; it is not a type error. Retry with mix muro.check --fuel 20000 path.muro.
  • Read every error. The checker reports each definition that fails, in book order, separated by a blank line. Parse and check errors start with line:col. Conversion prints surface types (Fin n, not #0). A ? prints expected and context; fill it.
  • Copy syntax from examples/, not from memory.
  • Keep every binder typed. Write every motive.
  • pred, plus, inj-suc, plus_suc, sym, and cong are already in scope (lib/muro/prelude.muro). Defining one of those names replaces it, and drops any prelude definition that refers to it.
  • Use only tags run, run internal, spec, evidence.
  • Write a library for many environments with param entries, and check it through a file that supplies them with def or data of the same names and tags (Params). mix muro.check on the library itself names the params it is missing.
  • Leave ? only while a term is unfinished. A hole always fails and is not in the finished book.

Do not

  • Edit agda/.
  • Edit lib/muro/*.ex.
  • Edit lib/mix/tasks/.
  • Add a third representation (no raw HOAS as inductive syntax).
  • Invent tags, implicits, metavariables, or tactics.
  • Promote a spec to evidence or evidence to run.
  • Treat this manual as ExDoc. Elixir API docs are @moduledoc / mix docs.

A definition is in the book as soon as Muro.Parser.parse/1 returns it. The checker sees the whole book. Forward references are allowed. Emit keeps run only.

Skeleton:

-- comments start with --
def plus : run Π (n : Nat) → Π (m : Nat) → Nat :=
  λ (n : Nat) → λ (m : Nat) →
    match n motive (λ _ → Nat)
      | 0 => m
      | suc np => suc(plus np m)
mix muro.check examples/your_file.muro

Emit (after check):

{:ok, src} = Muro.emit_file("examples/your_file.muro", Foo)
IO.puts(src)

Job B — change the type theory

Read Extending the kernel. Order is mandatory: Agda syntax → subst → check → make agda → Elixir mirror → mix test and mix muro.check.

Users still only run Mix. If you are doing Job A, you are not doing Job B.

Authority

Question Answer
What is the language? This manual, especially Grammar
What does the parser accept? lib/muro/parser.ex
What does the checker accept? lib/muro/check.ex, specified by agda/Muro/Check.agda
Is Agda a certificate for a .muro file? No. mix muro.check is.
Canonical book? examples/half_ok.muro = Muro.Example.book/0 = agda/Muro/Example.agda

File map

manual/                 this book (muro-lang.dev). Not ExDoc.
examples/*.muro         programs
examples/cshrl/         CSHRL: lib/ on params, envs/ supply them
lib/muro/parser.ex      .muro → named FOAS
lib/muro/ast.ex         named FOAS, to_db
lib/muro/print.ex       surface syntax, locations, hole messages
lib/muro/subst.ex       de Bruijn subst
lib/muro/check.ex       Elixir mirror of ⊢
lib/muro/session.ex     session / conform, mirror of decide and finishes; `rec X. S` unfolds one action and a repeated head conforms
lib/muro/prefix.ex      a list of directed moves is a legal prefix of a session from a position; the finite forms follow the Agda derivation; recursion, a named continuation, a dependent payload, an evidence bound, an indexed bit, a case, and the numeric position are this checker
lib/muro/fail.ex        a party of a two-party meeting may stop; a receive from that party has a failure arm; OTP and fsm emit it; other backends are `c:mayfail`
lib/muro/talk.ex        one description of an exchange, mirror of seen
lib/muro/choreo.ex      a global type projected to each role pair, mirror of project
lib/muro/place.ex       place / scheme / move, mirror of decide
lib/muro/prelude.ex     book behind every checked file
lib/muro/prelude.muro   pred, plus, inj-suc, plus_suc, sym, cong
lib/muro/load.ex        import: a relative path, pkg:, and std:
lib/muro/std.ex         the ordinary library, embedded at compile time
lib/muro/std/*.muro     bool, le, list, maybe, ord, suc_bin
lib/muro/emit.ex        run → Elixir source
lib/muro/repr.ex        a repr: check the host shape and emit decode/1, decode/2, and encode/2. Not a kernel term.
lib/muro/emit/equations.ex closed equations shared by the ExUnit and pytest suites
lib/muro/emit/exunit.ex closed equations → one ExUnit module (`--backend exunit`, `kind: :exunit`)
lib/muro/emit/pytest.ex closed equations → one pytest module (`--backend pytest`, `kind: :pytest`)
lib/muro/emit/otp.ex    a conformance, and a reading, is a GenServer; a marked peer is monitored and a `:DOWN` that is not a halt takes the failure arm; a book with no mark emits the previous module (`--backend otp`)
lib/muro/emit/fsm.ex    a session endpoint is a state machine; a marked book has `down/1` and `down/2` for a failure arm; a book with no mark emits no `down`; a keyed family that checks is a child with `new/0`, `arrive/4`, `resolved/2` (an open instance leaves), `withdraw/2` (a held instance resolves without opening), `finish` (`:resolve` or `:rerun`), and `check_trace/1` (arrivals, resolutions, withdrawals, reruns, and `{party, id, send|recv|down}`). A rule is `never held`, `held while earlier unresolved`, or `held while any unresolved`. `earlier_resolved k kind` names the earlier instances of that key and kind; each meeting end has `finish`, and `:rerun` when one family uses that end; two families on one end name `finish` on the family child; the transport stays with the host (`--backend fsm`)
lib/muro/emit/c_session.ex a session endpoint is a pure step written as C; the actions are the ones the state machine takes, init takes `uint64_t`, and `down` is not emitted (`--backend c`)
lib/muro/emit/node.ex   a cross, and a cross reading, is one call and one monitor (`--node`)
lib/muro/emit/mbi.ex    exactly one exported run as an .mbi image (`--backend mbi`); a run it calls is a definition in the image; muro-beam loads it; not a manifest target
lib/muro/example.ex     same book as Agda
lib/muro/mutate.ex      mutants of run definitions (`mix muro.mutate`)
lib/muro/synth.ex       version-space search on an emitted step (`mix muro.synth`)
lib/muro/synth/procedure.ex  one search the command can run: generate, evaluate, rank
lib/muro/synth/procedure/traces.ex  the version-space search (`--on traces`)
lib/muro/fill.ex        one definition body by search (`mix muro.fill`); the checker decides
lib/mix/tasks/muro.check.ex
lib/mix/tasks/muro.mutate.ex
lib/mix/tasks/muro.synth.ex
lib/mix/tasks/muro.fill.ex
agda/Muro.agda          public re-export
agda/Muro/Syntax.agda   Tm n (de Bruijn)
agda/Muro/Subst.agda    wk, sub, inst
agda/Muro/SubstLemmas.agda  renaming / substitution algebra
agda/Muro/Env.agda      Sig, Ctx, uses, mode order (shared by Check and ⊢)
agda/Muro/Check.agda    the decision procedure: structural on the term, fuel only where it reduces
agda/Muro/Session.agda  affine session judgment; a payload is a nat, a bit, unit, a pair, a record, a vector whose length is a received nat, a nat at most a bound the sender owes evidence for, or a non-indexed declared data type; a received bit selects one of two arms; a name is a session declared earlier, opened on the declaration prefix with no fuel; a parameter is a nat; %1 must finish; decide searches, skel is the OTP actions
agda/Muro/Prefix.agda   a legal prefix of end, send, recv, choose, and branch; a derivation is the prefix; the decision procedure accepts a list only when that list has a derivation; completeness is not claimed; recursion, a named continuation, and the numeric position are not this theorem; `--safe`; not a Tm
agda/Muro/Rec.agda      equi-recursive `rec X. S` unfolded to a guarded coinductive protocol (`--safe --guardedness`); a guarded self-call of a parameterised session is the same coinduction (`stream`); `dual∞`, conformance, and meet are bisimulations; a declared data payload inside `rec` meets when `sent` holds; `Finishes` stays finite, so a jump is not `%1`. `agda/Muro.agda` imports it, so that file carries the same pragma
agda/Muro/Dual.agda     the other end of a session; send swaps with recv, a dependent receive swaps with a dependent send, an evidence send swaps with an evidence receive, an indexed bit keeps its index and each arm dualises, and the payload type stays; `session name := dual name` follows it
agda/Muro/Meet.agda     two processes on one channel; a send meets a receive of the same payload type and the value inhabits it; a received nat instantiates a vector length; an evidence payload meets as a nat; a literal bit meets the arm of that bit; a variable meets a receive at its innermost binding; `meet name : left with right` follows it
agda/Muro/Talk.agda     one description of an exchange; say names one payload and one continuation; `session name := seen party with party in talk` follows it
agda/Muro/Choreo.agda   a global type; `g ↾ r / s ≡ b` is the binary session of one role with another; `project-sound`, `project-complete`, and `pairwise-dual`; `--safe`; not a Tm
agda/Muro/Seated.agda   a party of a description sits at a place; `seat name : party at place in talk` follows it; the same place stays; two places cross once
agda/Muro/Held.agda     a meeting at the parties' places; the same place stays; two places cross once; a `.muro` file does not write it
agda/Muro/Arrow.agda    %1 on a Π binder must be used; both marks are the affine quantity
agda/Muro/Grade.agda    a grade pair `(c, t)` on a binder; `ungraded-fragment` is the affine check; not a Tm
agda/Muro/Beam.agda     erase a core term to the grade judgment; `GTm` and `decide` are unchanged; not a Tm
agda/Muro/Linear.agda   multiplicity on a session endpoint; λ¹ must be used once; ⊸ accepts or returns it; the protocol is `SExp`, so `rec` and a declared data payload are endpoints; `dualS` keeps both; `--safe --guardedness`; not a Tm
agda/Muro/Place.agda    placement coeffect; ambient by default; one boundary; run has no seat
agda/Muro/Family.agda   keyed-family hold rule, any number of keys; a signal opens against the instances of its key that had already arrived; the generator is not this proof; `--safe`; not imported by Muro.agda
agda/Muro/Located.agda  a session at a place; `endpoint` and `read` follow the sitting; `--node` follows a cross reading; `--backend otp` follows the process
agda/Muro/Tag.agda      constructor tags (Check compares tags before structure)
agda/Muro/Spine.agda    application spines (constructor / dty applications), spine views
agda/Muro/Frag.agda     the ⊢ fragment as a predicate on terms, signatures, contexts
agda/Muro/Reduction.agda  parallel reduction ⇛, confluence
agda/Muro/Convert.agda  whnf strategy ⟶ and conversion ≈ for ⊢
agda/Muro/Data.agda     IsData, InstParams, BrTy: what the data rules are stated with
agda/Muro/Judgement.agda  inductive ⊢ with uses (core fragment, with data / match / ν)
agda/Muro/Typing.agda   declarative ⊨ (no uses); substitution, preservation
agda/Muro/Wall.agda     mode wall lemmas
agda/Muro/Consistency.agda  Empty-nf, progress, preservation at Empty; Empty-evid is not proved
agda/Muro/Soundness.agda  Check says yes → ⊢ derives it, on the fragment
agda/Muro/Soundness/Conv.agda   whnf-sound, conv-sound
agda/Muro/Soundness/Views.agda  views, isData-sound, GoodSig, instParams / index clashes on a telescope
test/muro_check_test.exs

Install

mix muro.check, mix muro.mutate, mix muro.synth, mix muro.fill, mix muro.emit, mix muro.gen, mix muro.init, and mix muro.deps.get run in any directory once the archive is installed, with or without a mix.exs.

A project without Elixir uses the self-contained executable: mise use -g github:murolang/muro@0.22.13. If mise answers No versions found or a 404 from mise-versions.jdx.dev, run mise settings set use_versions_host false first. The commands are muro check, muro emit, muro gen, muro init, muro skills add, muro deps.get, muro mutate, muro synth, muro fill, and muro ui. muro ui path.muro prints how to install muro_visor and does not start the explorer. The page is Visual explorer. The manifest is muro.toml or [package.metadata.muro] in Cargo.toml. The executable page is The executable.

Install it from Hex:

mix archive.install hex muro

Alternatively, from a checkout of this version:

mix deps.get
mix archive.build
mix archive.install muro-0.22.13.ez

From GitHub, Mix fetches the default branch and builds the archive:

mix archive.install github murolang/muro

--force skips the install question.

mix muro --version prints Muro v and the version of the copy that ran. Inside a project that depends on muro, the project’s copy runs after app.start. Inside any other project, or outside a project, the archive’s copy runs and the host is neither compiled nor started. The version line names the copy that ran.

A script run with mix run --no-start does not see the archive. Archives are on the code path only for Mix tasks. Use mix muro.check and mix muro.emit.

mix muro.emit path.muro prints the Elixir module. mix muro.emit path.muro > path.ex saves it. mix muro.emit path.muro --backend exunit prints one ExUnit module for the book’s closed equations, including a library whose params are not supplied. mix muro.emit path.muro --backend pytest prints one pytest module for those same equations. --imports with either backend also collects the files the book imports directly. The pages are Closed equations as tests and Pytest.

--backend zig writes <name>.zig next to the file. zig translates it. The proof stops at the run image.

--backend mbi writes <stem>.mbi next to the file only when the book has exactly one exported run and that body erases, and the binder grades stay. Any refusal, including a book with no exported run and a book with more than one, writes nothing and leaves an image already at that path byte for byte. The file is the image muro-beam loads. It is not Erlang BEAM bytecode. A run the entry calls is a closed definition in the image. A name that is not a run, data, a pair, a word, or a stream is refused. Two definitions that call each other are refused. muro-beam checks the image again. Writing the file is not that check. The page is MBI images.

--backend c writes C. A session in the book is also a pure step, and the host keeps the transport. The Mix task builds a NIF when the working directory is the loaded Mix project. Add {:elixir_make, "~> 0.10", runtime: false} to the project deps, or run the task inside a project that depends on muro. Without elixir_make, that NIF stops and names the dependency. Outside the loaded project the task writes the .h and the .c only, and so does the executable. nx and makeup are optional. Checking and emitting Elixir do not load them.

Committed modules

A project commits the modules muro gen writes. The .muro file is the source. Do not edit the generated file by hand. Change the .muro file and run muro gen.

muro skills add writes this block into AGENTS.md, and into CLAUDE.md when that file already exists. The command lines and the example anchor are filled from the project. The markers are part of the block. Each marker is a whole line. A trailing carriage return is allowed. An inline mention is left as prose. The file’s line endings stay.

Muro has two jobs: spec and evidence. run is what is emitted.

The wall: a spec never becomes evidence. Evidence never becomes a run.

{{commands}}

Every binder is typed and every motive is written.

Generated files are not edited by hand.

Nearest example: manual/examples.md#{{example}}.

muro.exs at the project root, a :muro key in mix.exs, muro.toml, or [package.metadata.muro] in Cargo.toml names each book and the target path. Elixir, fsm, and exunit entries also name the module. A pytest entry names a .py target and may omit the module. An entry may add [kind: :exunit, impl: Adapter, imports: true], [kind: :pytest, impl: "host.rounding"], or [kind: :c], [kind: :rust], [kind: :zig], [kind: :asm], or [kind: :js]. imports: is valid on an exunit entry and on a pytest entry. muro: is the version the books are checked with. muro gen and mix muro.gen --check refuse to run when it differs from the running version. The message names both versions. One invocation type-checks each book once and emits every target of that book from that copy, including both files of a C target. --skip-check does not type-check; --check --skip-check still compares bytes. The default type-checks.

mix muro.init creates muro.exs and priv/muro/. It prints a note that points at muro skills add. It does not write AGENTS.md. muro init --backend stores that backend as the manifest’s top-level backend. muro init writes the one manifest the directory calls for. If muro.exs, muro.toml, or [package.metadata.muro] is already present, it prints a diff of that file in its own format and leaves every file as it is. mix muro.init --ci github writes .github/workflows/muro.yml. The job installs the archive with mix archive.install hex muro <version> --force, with the version from the manifest, and runs mix muro.gen --check. muro init --ci github installs the executable and runs muro gen --check.

The page is Committed modules. Package imports (import "pkg:...", muro_deps:, mix muro.deps.get, muro.lock) are Packages. The ordinary library is import "std:file.muro" (Library). It is compiled into the compiler. It is not the prelude, and it is not a package.

Commands

mix deps.get
mix test
mix muro.check
mix muro.check examples/half_ok.muro
mix muro.mutate examples/half_ok.muro --only half
mix muro.synth path.muro
mix muro.synth path.muro --on traces
mix muro.fill path.muro --def name
mix muro.emit path.muro --backend exunit
mix muro.emit path.muro --backend exunit --imports
mix muro.emit path.muro --backend pytest
mix muro --version
mix muro.init
mix muro.gen
mix muro.gen --check
mix muro.gen --skip-check
mix muro.deps.get  # fetch muro_deps/ and write muro.lock
make agda          # Job B only; needs vendor/agda-stdlib v2.3

On success, mix muro.check prints the version that checked the book, then one line per keyed family and one line per temporal declaration, in book order, then one line per projected pair of each choreography, then:

Muro v0.22.13
All terms check. Evidence never becomes a run.

A book with no keyed family, no temporal declaration, and no choreography prints those two lines and nothing between them. A book that imports packages prints conforms to <name> <version> (sha256 <hash>) after that sentence, one line per package it loaded. A book that imports none, and mix muro.check with no path, print only those two lines. With no path the task checks the built-in book (Muro.Example.book/0), the same book as examples/half_ok.muro. It does not walk examples/.

Muro.Check.check_sig/2 returns :ok on a well-typed book, or {:error, msg} with every definition error in book order. check_sig(book, fuel: n) sets the fuel for each definition. Definitions are checked concurrently; the fuel is the bound, not a wall-clock timeout.

Representations (do not add a third)

Layer Form Where
Parser / pretty / emit named FOAS lib/muro/{parser,ast,emit}.ex
Check / subst de Bruijn lib/muro/{check,subst}.ex, agda/Muro/{Check,Subst}.agda
Examples and metatheory de Bruijn Tm n agda/Muro/Syntax.agda, agda/Muro/Example*.agda

Elixir constraints when you are in Job B: ASCII identifiers only. Do not define local hd/1. Guards cannot call ordinary defp helpers. repr entries are host-side declarations checked by Muro.Repr, not part of the Agda calculus.

What is not in the language

Type : Type, cubical, tactics, implicits, unification, metavariables (a ? always fails; it does not unify; mix muro.fill replaces a ? that is the whole body of one definition), extra quantities, + on Stream or Either, typing raw Elixir, emitting spec or evidence.

Full list: Limits.

Releasing

Merging a version bump to main is the publish. Once the Elixir CI job on that commit is green, the Hex and tag job in CI publishes the mix.exs version to Hex unless that version is already there, pushes the annotated tag vX.Y.Z if it is missing, and then builds the self-contained binaries. A push that does not bump the version succeeds without moving an existing tag and without building the binaries. The publish does not wait for Agda or muro_visor, and the binary job does not delay the Hex publish. muro_visor is not published this way: Hex stages it, and it still needs 2FA.

The first publish through this workflow needs the repository secret HEX_API_KEY. Generate a key with mix hex.user key generate --key-name muro-ci --permission api:write and add it as HEX_API_KEY on murolang/muro. A missing secret fails the publish job with a clear error and does not print the key. The executable page is The executable.

Source on GitHub · fetched from murolang/muro manual/