Constants and compile-time behaviour

# marks a compile-time constant binding.

    site_name #= "Moth"
    major_version #Int = 1
    names #{String} = {"Ana", "Bo"}
    maybe_name #String? = none
    

Declaration forms

    name #= value
    name #Type = value
    

• Every constant must have an initializer.
• A constant is immutable.
• A mutable marker cannot be combined with #.
• Without an annotation, the initializer supplies the type.
• An explicit annotation supplies a compile-time receiving type.
• The initializer must fully fold.
• A constant may reference only compile-time values.

# controls compile-time evaluation. It does not control visibility.

Top-level constants follow ordinary module and public-surface visibility rules.

Body-local constant declarations remain local to their scope.

A top-level runtime binding without # belongs to entry-selected start code rather than the importable constant surface.

A constant initializer must fully evaluate during AST construction.

    base #Int = 4
    larger #Int = base + 2
    label #= [: size [larger]]
    

Allowed dependency shape

A constant may depend on:

• literals
• earlier same-file constants
• imported constants
• foldable operators
• foldable casts
• foldable struct construction
• foldable templates
• other compile-time values accepted by the current language surface

It may not depend on:

• runtime bindings
• runtime function calls
• host calls
• runtime-only template content
• mutable state

Ordering

Same-file constant evaluation follows source order.

A same-file forward reference is invalid.

Cross-file constant dependencies are represented in the top-level dependency graph and evaluated in dependency order.

Circular constant dependencies are compilation errors.

Compile-time and runtime agreement

Folding must preserve runtime language semantics.

Examples:

• a statically known checked-numeric failure is a compile-time diagnostic
• String -> Int and Float -> Int enforce the signed 32-bit range
• String -> Float rejects non-finite materialization
• Float -> String uses Moth's stable formatter
• compile-time and runtime template interpolation use the same Float formatting

The compiler must not accept one result during folding and produce another at runtime.

Advisory const facts

The compiler may discover private const facts for optimization.

Those facts do not:

• change source semantics
• create importable declarations
• participate in header dependency sorting
• turn a runtime binding into a source constant

A fully folded struct instance stored in a constant may become a const record.

    Defaults = |
        title String,
        year Int,
    |

    defaults #= Defaults("Moth", 2026)

    page_title #= defaults.title
    

Contract

A const record is a data-only compile-time member group.

Every constructor argument must fold.

Const-record field projection may participate in another constant expression.

The complete const record cannot be used as an ordinary runtime value.

It cannot be:

• assigned to a runtime binding
• passed as a runtime argument
• returned from a runtime function
• stored in a collection or map
• used through a runtime receiver method

Use one folded field when runtime code needs the value.

    io.line(defaults.title)
    

Const records preserve their struct-backed field names and types.

They do not introduce structural typing or anonymous runtime record identity.

A template can be required to finish during compilation.

Named const templates

A normal constant binding can hold a folded template string.

    site_name #= "Moth"

    heading #= [$md:
        # [site_name]
    ]
    

This creates a compile-time String value.

It does not contribute a page fragment by itself.

Direct top-level const fragments

In an active HTML module root, the direct top-level const-template form contributes a compile-time page fragment.

    #[$md:
        # Compile-time heading
    ]
    

The direct form:

• is valid only as top-level entry-selected fragment syntax
• must fully fold
• records its position relative to entry-selected runtime fragments
• is handed to the project builder
• never becomes HIR runtime code

Const template if

    #[if show_heading:
        Visible heading
    [else]
        Hidden heading
    ]
    

A const-required template if validates every branch body.

The selected result must fold completely.

Const template loops

    #[loop items |item|:
        [item]
    ]
    

Const range and collection loops may use structural break and continue controls:

    #[loop items |item|:
        [if item.done:
            [break]
        ]

        [item]
    ]
    

They use the project config guard:

        template_const_loop_iteration_limit
    

The default is 10_000.

The maximum accepted configured value is 1_000_000.

The configured value must be a positive folded Int. Zero, negative values and values above 1_000_000 are rejected.

A const conditional loop folds to no-output only when its condition is compile-time false.

A compile-time true condition and a runtime or unknown condition are rejected because the compiler does not prove loop termination.

Runtime template control flow remains owned by Template control flow.