MEP 0 — Index of Mochi Enhancement Proposals

Field	Value
MEP	0
Title	Index of Mochi Enhancement Proposals
Author	Mochi core
Status	Active
Type	Process
Created	2026-05-08

What is a MEP

A Mochi Enhancement Proposal is a design document that records a decision about the language. It is modeled on the Python PEP process. Every change to the language surface, the type system, the runtime, or the tooling that would benefit from a written record lives as a MEP.

A MEP is the place where we explain what the language does, why it does it that way, and what we would change. The implementation is in the repository. The MEP is the contract.

Status values

Status	Meaning
Draft	Under discussion. Content may change.
Active	A process MEP that is in effect.
Accepted	Approved. Implementation is in progress or pending.
Provisional	Approved with a trial period. Behavior may be revisited based on real-world use.
Final	Implemented and stable. Changes require a new MEP.
Informational	Documents the language as it stands. No proposal embedded.
Withdrawn	The author retracted the proposal.
Rejected	The proposal was not adopted. The MEP stays so the discussion is searchable.
Superseded	An older MEP that has been replaced. The replacement is linked.

Type values

Type	Meaning
Standards Track	Adds, changes, or removes a language feature, type rule, or runtime behavior.
Informational	Describes the language without proposing change.
Process	Describes a process: how we test, how we release, how we write MEPs.

Index

The current series covers the soundness initiative for v0.11.0. Numbering follows the PEP convention: four-digit padded MEP numbers, status and type recorded in each file's header.

MEP	Title	Status	Type
0	Index of Mochi Enhancement Proposals	Active	Process
1	Lexer	Informational	Informational
2	Grammar	Informational	Informational
3	Abstract Syntax Tree	Informational	Informational
4	Type System	Informational	Informational
5	Type Inference	Informational	Informational
6	Type Checker	Informational	Informational
7	Soundness	Active	Process
8	Test Strategy	Active	Process
9	Fixture Catalogue	Informational	Informational
10	Known Gaps and Weakness Review	Informational	Informational
11	Subtyping and Variance	Draft	Standards Track
12	Parametric Polymorphism	Draft	Standards Track
13	Algebraic Data Types and Match	Draft	Standards Track
14	Query Algebra	Informational	Informational
15	Effects, Mutability, and Purity	Draft	Standards Track

Workflow

A MEP starts as a draft on a branch. The author opens a pull request titled mep: <short title>. The PR includes the MEP file under website/docs/mep/ and any related code changes. Once the team reaches a decision the status field is updated and the PR is merged.

Steps:

1. Pick the next available MEP number. Update the index above and the new file's header.
2. Write the MEP. The default sections are listed in the next section.
3. Open a PR with the draft. Solicit review.
4. Update the status to Accepted, Rejected, or Withdrawn based on the outcome.
5. After implementation lands, update the status to Final and link any follow-up MEPs.

Required sections

Every MEP after the index uses these sections, in this order. Sections that do not apply may be left out, but the headings should not be renamed.

1. Header table with the metadata fields.
2. Abstract. A short paragraph that summarises the proposal.
3. Motivation. Why we need this. Reference concrete code paths or fixtures.
4. Specification. What the language does or will do. The technical core.
5. Rationale. Why this design over the alternatives.
6. Backwards Compatibility. What existing programs break and how we handle migration.
7. Reference Implementation. Links to source files and lines.
8. Open Questions. Things we have not decided yet.
9. References. External material we built on.
10. Copyright. Public domain dedication.

Why we do this

Mochi is small and fast moving. The parser, type checker, interpreter, and bytecode VM all evolve in lockstep. Without a written record, a syntactic change in parser/parser.go can outrun the matching type rule in types/check.go, or a runtime detail can drift away from what the checker promised. The MEP series is the contract that catches drift before it ships.

The 1800-series internal notes that lived under ~/notes/Spec/1800/ were the seed for this index. They are now MEPs and will be maintained here.

Status snapshot at v0.10.82

• Parser fixtures: 52 valid pairs and 10 error pairs.
• Type fixtures: more than 30 valid pairs and more than 45 error pairs.
• The RUN_TYPE_VALID=1 gate on the valid type-check suite was removed in the v0.11.0 soundness PR.
• 86 distinct error codes registered in types/errors.go covering roughly T000 through T046 with gaps.
• Known parser quirks: int | nil is not parseable as a type, and unary minus on the right hand side of == requires parens.

Working agreement

When a language change touches a typing rule, the author updates:

1. The relevant MEP in this directory.
2. At least one valid fixture under tests/types/valid/ proving the accepted shape.
3. At least one error fixture under tests/types/errors/ proving the rejected shape.
4. A short note in MEP 10 if the change closes or opens a soundness hole.

The next contributor should be able to read these MEPs, plus parser/README.md, plus the fixtures, and onboard onto the soundness work without reading every line of the type checker.

Copyright

This document is placed in the public domain.