Codebase / Design scope

Design scope

Moth is deliberately small. The compiler is allowed to be clever only when the source model stays simple and explicit.

The central bias

Keep the source language small, explicit and statically inspectable.
Compiler complexity is acceptable when it makes source code simpler.
Prefer constrained built-in mechanisms over general metaprogramming.
Prefer static resolution over runtime dynamism.
Keep backend optimisations hidden behind stable source semantics.
Avoid features that need pervasive solver-heavy reasoning.

Deferred implementation versus outside scope

A surface can be unimplemented for two different reasons.

Deferred implementation fits the accepted design but has not landed yet or is incomplete. The progress matrix reports whether a deferred surface works today.

Outside scope conflicts with the intended language model. It needs an explicit design change before it can be implemented.

This page explains whether a surface belongs in the language at all.

Preferred constrained mechanisms

Need	Preferred Moth mechanism
Compile-time generation	Templates, constants and builder directives
Static reuse	Generic functions and explicit trait bounds
Runtime heterogeneity	Choices
Expected failure	`Error!`, postfix propagation and `catch`
Platform integration	Builder packages, external packages and source-backed packages
Memory safety	GC baseline plus mandatory borrow validation
Mutation	Explicit exclusive access rather than implicit mutation
Ownership	Compiler-inferred transfer rather than source-visible move or lifetime syntax
Performance	Hidden compiler and backend optimisation

Static reuse

Use generic trait bounds when code should be reused statically across types.


    render type Item is DISPLAY_TEXT |item Item| -> String:
        return item.display()
    ;

Generic trait bounds are compile-time static reuse, not dynamic trait values.

Runtime heterogeneity

Use choices when a value should carry one of several concrete runtime shapes.


    Renderable ::
        LabelItem | value Label |,
        ButtonItem | value Button |,
    ;

Choices are the intended runtime heterogeneous value mechanism.

Questions to ask during design review

Does this add a new source-language category when an existing constrained mechanism is sufficient?
Does it make behaviour more implicit?
Does it need whole-program or solver-heavy reasoning?
Does it introduce runtime type or erased-dispatch machinery?
Does it leak backend representation into source semantics?
Does it expose optimisation mechanics through source syntax?
Is it merely unimplemented, or explicitly outside scope?
Would the feature make code harder to inspect locally?