Developers / Codebase development standards

Codebase development standards

Good compiler work should be easy to read, easy to test and hard to misinterpret. These references cover implementation style, test design and the validation gates.

All of these must be followed by all contributors to meet the criteria for an acceptable PR.

Codebase style guide

This document owns implementation style for new and refactored compiler code.

Test strategy and test construction guide.

Final technical gates and completion checks guide.

Priorities:

1. Readability
2. Modularity
3. Correctness and diagnostics

No user-input panics

• Active frontend stages must reject unsupported syntax and malformed input with structured diagnostics, not panic!, todo! or user-data-driven .unwrap().
• Panic paths are only for proven internal invariants that indicate a compiler bug.

Diagnostics

• Use CompilerDiagnostic for normal user-facing source, config, import, syntax, type, rule, borrow and deferred-feature diagnostics.
• Use CompilerError only for internal compiler, filesystem, backend, dev-server and tooling infrastructure failures.
• Diagnostic payloads and reason enums should carry typed DiagnosticPayload facts and stable diagnostic codes, not pre-rendered prose.
• Include a SourceLocation in every user-facing diagnostic and preserve source labels wherever they add useful context.
• Type diagnostics should carry semantic TypeIds and context enums and render through DiagnosticRenderContext, not cloned DataType values or formatted type names.
• Use DiagnosticBag for stage-local accumulation and CompilerMessages only at build/render boundaries.

For test assertion policy, see testing.mtf.

Naming

• Use descriptive full names. Avoid abbreviations except simple iterators such as i and j.
• Functions should be self-describing. Compiler passes should use explicit names such as build_ast, generate_hir and emit_wasm.
• Outside tiny scopes, prefer function_signature over sig, expression over expr, data_type over ty and a specific context name over ctx or env.

format! and printing

Use the saying library macro say!() for user-facing stdout that may need colour styling. Use variables directly in format! strings whenever possible.

Imports

Use inline imports only when they are one level deep and improve local reasoning. Import long paths at the top, including types used once in signatures.

// ACCEPTABLE: terse and locally clear.
let type_id = builtin_type_ids::BOOL

// BAD: import this long path at the top.
let type_id = crate::compiler_frontend::datatypes::ids::builtin_type_ids::BOOL

Avoid aliasing unless it clearly improves readability.

Code style and organisation

• Maintain clear separation between compilation stages.
• Each module should have one clear responsibility. Do not mix concerns.
• Split files by task category. Aim for files under ~2000 lines where practical.
• mod.rs should be the module entry point and structural map. It exposes the public surface, shows the module flow and points to the files that contain the implementation.
• Keep mod.rs focused on orchestration, re-exports and documentation rather than core implementation.
• A reader should understand the module's responsibilities and important files by opening mod.rs first. Its documentation should explain structure and data flow and state what the module owns, important exclusions and why the pieces are arranged that way.
• Prefer context structs for shared state instead of noisy or repetitive parameter lists.
• Keep new abstractions small, stage-local and easy to justify.
• Avoid .unwrap() unless it is blatantly safe and tied to an internal invariant.
• Avoid .to_owned() and .clone() whenever possible, prefer borrowing when possible and find patterns that avoid copies.

For test-file placement, see testing.mtf.

Readable Rust style

Compiler code should optimise for fast review. Dense code is harder to scan and easier to extend badly.

Prefer code that reads as a sequence of named steps and makes data flow obvious before every detail is understood. The main function for a module or pass should also read as a sequence of named steps.

Use named intermediate values, short single-purpose functions, explicit multi-step control flow, narrow helpers, context/input structs, enums for meaningful states, comments as landmarks and visible spacing. Avoid dense expression chains, clever iterator nesting, large inline matches and logic compressed into one expression. Brevity is less important than clarity.

Vertical spacing

Use vertical spacing to show structure.

Required:

• one blank line between functions
• one blank line between unrelated statement groups
• one blank line between major control-flow blocks inside long functions
• one blank line between match arms unless the arms are tiny and visually identical
• one blank line before a comment that introduces a new logical step

Prefer this:

let source_file = header.source_file.clone();
let visibility = binding_environment.visibility_for(&source_file)?;

// Resolve type aliases before constants because constant folding may depend on alias-expanded types.
self.resolve_type_aliases(&headers, visibility, string_table)?;

self.resolve_constant_headers(&headers, visibility, string_table)?;

Comments as reading landmarks

Comments must explain non-local intent, not restate the code. Write for programmers reading the codebase for the first time so they can understand local code without first reading distant owners. Stay comment-positive: keep the comments that carry ownership, invariants and failure context, and drop the ones that only narrate syntax.

File-level docs are the primary place for subsystem role, ownership, exclusions and detailed WHAT/WHY context. A reader should learn the architecture from the file header and mod.rs map, then use item comments only where local code is not enough.

Detailed item comments belong on complex functions, stage joins, ordering constraints, invariants, unusual diagnostics and non-obvious data flow. Tiny accessors, constructors, fields, forwarding methods and obvious private helpers need no comment, or at most one short sentence.

WHAT/WHY headings are optional landmarks, not a required template. Use them when they make a non-local contract easier to find. Do not add them to every item.

Keep comments aligned with the current design. Migration history belongs in Git. Do not justify obsolete adapters, compatibility wrappers or deleted owners in comments.

Test-only implementation belongs with tests. Production files must not grow test-only constructors, mutators, semantic variants or convenience lookups just to support fixtures.

Be grammatical and readable. Do not narrate syntax, repeat a descriptive name or paraphrase a clear signature.

// Register same-file declarations before dependencies so aliases cannot shadow local names.
for declaration in same_file_declarations {
    visible_names.register_same_file_declaration(declaration)?;
}

// Prelude names are registered as reserved names first, then inserted only if not shadowed.
for symbol in external_package_registry.prelude_symbols() {
    visible_names.reserve_prelude_symbol(symbol)?;
}

Production layering and stage ownership

Stage separation is a dependency rule, not only a naming preference. Production code must respect these directions.

• compiler_frontend must not depend on build_system, project builders or the project tool's configuration containers to perform local semantic compilation. It receives compiler-owned option and input values instead.
• build_system/create_project_modules must not assemble interface binding, declaration ordering, AST, public-interface or borrow stages. It builds one compiler input, calls the compiler's module compilation service and handles the returned outcome.
• Build and project code must not mutate compiler semantic state. No build-owned function installs call summaries, rewrites HIR or reruns a compiler analysis.
• A build or project client that needs a shorter compiler path must call a named compiler service, such as project config compilation or direct Moth template compilation. Composing raw stage functions to make a new short path is not allowed.
• Values whose meaning is "the compiler produced this semantic result" belong to the compiler owner, even when the build system stores, remaps and publishes them. Project aggregation, entry assembly and output records stay build-owned.
• Moving a stage owner means moving its data contracts and deleting the old owner. Do not leave forwarding wrappers, aliases or parallel payload types behind.
• Exceptions are documented on the canonical architecture boundary in docs/compiler-design-overview.md or docs/build-system-design.md. Do not introduce a local exception in a comment.

Prefer narrowed Rust visibility for these rules wherever the module tree can express them. Use a repository source check only for dependency directions Rust visibility cannot encode.

Tests may target stage-local APIs from their owning module. Later build, link and backend code may still consume completed HIR, function IDs, link facts and borrow results where the architecture documents that handoff. The rule bans external orchestration of the stages, not legitimate consumption of their final data.

Refactor moves

When moving code across compiler stages, do not copy the old module shape unchanged. Use the move to correct ownership, names, APIs, comments and data flow.

Moved code must:

• replace long parameter lists with context/input structs where useful
• split mixed-responsibility modules
• update file-level documentation to match the new owner
• delete the old owner once the new path is wired

Do not preserve a bad API shape because it already exists.

API breakage

• Moth is pre-release. Backward compatibility isn't a priority.
• When APIs change, thread the new shape through the compiler and remove the old one.
• Don't add compatibility wrappers, forwarding shims, parallel structs or defaulted legacy entry points just to preserve an older interface.
• Prefer one current API shape, not transitional layers.

Type ordering

Order types in a file from higher-level abstractions to lower-level supporting types.

Iterators versus loops

• Use iterators for simple transformations.
• Use explicit loops for complex multi-stage logic where control flow is clearer.

Function size

Functions should usually stay under ~200 lines. Longer functions are fine when they still represent one coherent operation, such as a compiler transformation, state machine or tightly coupled sequential process.

Split functions when they mix unrelated responsibilities, are hard to test or no longer match their name.

Match readability

Large matches should be grouped by meaning.

Use blank lines and short comments to make each group obvious. If a match grows too large, extract branch handling into named helpers.

Prefer:

match resolution {
    // Constants create dependency edges.
    ConstantReference::SourceConstant { path, source_file } => {
        add_constant_dependency(header, path, source_file)?;
    }

    // Type names are valid to resolve but do not create value dependency edges.
    ConstantReference::SourceTypeAlias { .. } => {}

    // These are structurally invalid in constant initializers.
    ConstantReference::SourceNonConstant { path }
    | ConstantReference::ExternalNonConstant { .. } => {
        errors.push(non_constant_reference_error(path, location.clone()));
    }

    // Unknown names may produce better diagnostics during AST expression parsing.
    ConstantReference::Unknown => {}
}

Avoid long ungrouped matches where every branch looks equally important.

Avoid clever Rust

Don't use advanced Rust features just to make code shorter.

Avoid:

• nested iterator chains with side effects
• clever Option / Result combinator pipelines for validation logic
• large closures with mutation
• broad generic helpers that hide compiler-stage ownership
• macro abstractions for ordinary compiler flow
• boolean-heavy APIs where an enum would explain the state
• tuple-heavy returns where a named struct would explain the result

Prefer named types and straightforward flow:

pub(crate) struct DependencyResolution {
    pub(crate) target: ResolvedDependencyTarget,
    pub(crate) local_name: StringId,
    pub(crate) location: SourceLocation,
}

Instead of:

Result<(ResolvedDependencyTarget, StringId, SourceLocation), CompilerError>

A few more lines are fine when the result is easier to inspect and harder to misuse.

Macros

Keep macro usage minimal. Use small declarative macros only where they clearly reduce repetition and avoid creating procedural macros.

Warnings and lints

• Use clippy and the default Rust formatter.
• Keep unused variables and dead code to a minimum.
• Any lint suppression must be justified and documented. Use allow(dead_code) only for clearly identified planned work or test-only code.

Section banners

Use section banners only for real phase boundaries in long functions, large files or complex orchestration such as parsing, lowering, template folding, dependency resolution, diagnostic rendering or build flow.

Use exactly this format:

// ------------------------
//  Resolve template slots
// ------------------------

The banner has three lines. The title starts with // and uses title case or a clear imperative name. The top and bottom start with // and their dashes extend equally beyond the title on both sides. Do not use banners around small helpers or to hide a file that should be split.

Returning errors

The diagnostic lane rules above apply to every local error boundary.

• New user-facing diagnostics must use typed CompilerDiagnostic constructors in compiler_diagnostic.rs. Do not add CompilerError variants for syntax, type, rule, import, borrow or config failures.
• Use return_compiler_error! only for internal compiler bugs or broken invariants.
• When a local Result boundary carrying CompilerDiagnostic or CompilerError triggers result_large_err, box the payload inside that boundary enum or use a stage-local boxed diagnostic result alias.
• Keep DiagnosticBag and CompilerMessages owning plain CompilerDiagnostic values at accumulation and render/build boundaries.
• Prefer Option<CompilerDiagnostic> over Result<(), CompilerDiagnostic> for predicate-only validators that report one diagnostic or continue.
• Prefer explicit loops when iterator closures would infer Result<_, CompilerDiagnostic>.
• Keep paths interned until render time. Do not duplicate them as owned PathBufs.
• Centralise repeated diagnostic construction in the owning typed constructor or narrow helper instead of duplicating it across branches.
• Include exact tokens, types or names and suggest practical corrections where possible.

// Typed diagnostic constructor.
return Err(CompilerDiagnostic::invalid_assignment_target(
    InvalidAssignmentTargetReason::ImmutableVariable,
    variable_name,
    location,
));

// Internal bug path.
return_compiler_error!(
    "Unsupported AST node type: {:?}",
    node_type; {
        CompilationStage => "AST Processing",
        PrimarySuggestion => "This is a compiler bug - please report it"
    }
);

Codebase documentation

This section covers codebase doc comments and small requested documentation edits. For substantial documentation work, follow the task's dedicated writing guidance and the surrounding source.

• @page.moth owns website title, introduction, navigation, composition and layout.
• overview.mtf owns compact routing and contract reference and must not be imported by @page.moth.
• Topic-named .mtf files own detailed design content, remain useful when read directly and may be imported by website pages. Pages should make subjects easy to explore while compact references reach the contract quickly.

For small edits:

• Follow the surrounding style and use British English.
• Prefer direct, active constructions and concrete verbs. Keep only information-carrying prose.
• Remove filler, hollow intensifiers, hedging, vague qualifiers, generic transitions, redundant preambles or recaps, restatement, over-description, clichés and dated cultural references.
• Do not add redundant end-of-section summaries.
• Avoid semicolons, Oxford commas and em dashes. Use straight ' apostrophes and contractions. Reserve hard must and must not wording for deliberate emphasis.
• Vary sentence rhythm naturally. Preserve exact quotes and code syntax even when they break prose rules.
• Use "Priya" as the first choice for example names.

Testing standards

This document owns test selection, test structure, assertions, fixture design and test pruning for compiler work.

It does not define the final validation command. For completion gates, read docs/src/developer-docs/style-guide/validation.mtf.

The primary goal is end-to-end language and artifact correctness. Prefer real usage patterns and complete Moth snippets over narrow implementation-shaped tests.

Task-reading guide

Heading paths use > to name nested sections. Read the selected heading through the next heading of the same or higher level, including nested subsections unless the route narrows further. Read this document in full for test infrastructure, suite policy, broad fixture cleanup or audits.

Default testing preference

Integration tests written in Moth are the default for user-visible language behaviour. They exercise the real compiler path and usually provide the strongest regression coverage.

• Prefer integration coverage for user-visible language behaviour
• Add or update unit tests only where subsystem-local behaviour genuinely benefits from them
• Avoid redundant fixtures that assert the same behaviour in slightly different forms
• Prefer meaningful end-to-end cases over brittle implementation-shaped assertions
• When backend or runtime behaviour matters, strengthen artifact assertions where goldens alone are too vague

Supporting rules

• Prefer externally observable behaviour over implementation detail.
• Use unit tests for hidden invariants that integration output cannot inspect.
• Use one clear primary test owner per behaviour.
• Do not create multiple fixtures that prove the same contract without a distinct stage or backend reason.
• Prefer realistic end-to-end snippets.
• Tests should remain understandable without reading the implementation first.
• Do not make exact internal layout contractual unless that layout is the invariant.
• When tests compare or report paths, use the shared portable_path_text normalisation helper instead of raw or native path strings. Keep Path or PathBuf values for filesystem operations, converting to portable text only at assertion or display boundaries so tests remain robust across platforms.

Test ownership

Each behavior should have one primary owner. Secondary coverage is justified only when it protects a distinct boundary, target, diagnostic lane or internal invariant.

Test location and module layout

• Tests do not live in production implementation files.
• Module-specific tests belong under the module's test directory, for example:

src/compiler_frontend/hir/tests/

• End-to-end or multi-module Rust harness tests belong under:

src/compiler_tests/

• Language and project integration cases belong under:

tests/cases/

• Test-only utilities should live with the tests that own them.
• Do not create broad shared test utility modules for one or two callers.
• Split cross-stage test support only when actual ownership boundaries justify it.

Unit tests

Retain unit tests for:

• pure data invariants
• impossible states
• side-table facts
• transfer rules
• backend planning policy not observable from artifacts
• narrow parser or formatter algorithms

Prefer integration tests for user-visible behavior. Once a subsystem is stable, prune superseded unit tests. Rewrite obsolete tests rather than preserving old API shapes. A unit test should name the invariant it protects. Do not use unit coverage as a substitute for an end-to-end case when user behavior changed.

Integration cases

• moth tests runs the integration test runner.
• Use real Moth snippets.
• Each canonical case is one self-contained scenario directory.
• Keep helper source files inside the owning case's input/ directory.
• Do not let helper files become unintended standalone cases.
• Add strong output assertions where behavior is visible.
• Prefer top-level templates to simulate output.
• Avoid io.line(...) unless console behavior is itself under test.

Successful backend intent

Every successful HTML and HTML-Wasm backend run applies its universal backend baseline. The baseline protects harness and target invariants. It is not the case's authored semantic contract.

Use success_contract = "acceptance_only" only when that backend has no stronger case-specific semantic, artifact, golden, absence or expected-warning assertion.

[backends.html]
mode = "success"
warnings = "forbid"
success_contract = "acceptance_only"

Acceptance-only intent does not disable the baseline. The audit records both baseline_applied = true and acceptance_only = true, with backend_baseline and acceptance_only in assertion_kinds.

Do not combine acceptance-only intent with artifact assertions, golden mode, rendered-output assertions, artifact-absence assertions or an authored expected-warning contract. A whole case whose backends are all acceptance-only uses role = "smoke". A mixed-backend case may use a boundary or backend role when another backend owns a stronger contract.

A successful backend with only the universal baseline is invalid. Typed fixture loading rejects it before policy evaluation, listing, audit, or execution.

For new type-system syntax, include:

• positive usage
• value/type namespace misuse
• binding visibility
• duplicates
• cross-file resolution
• target/backend rejection where relevant

Canonical fixture shape:

tests/cases/
├── manifest.toml
└── case_name/
    ├── input/
    │   ├── main.moth
    │   └── helper.moth
    ├── expect.toml
    └── golden/
        ├── html/
        └── html_wasm/

• manifest.toml is the authoritative case order. Every case declares a unique canonical id, unique fixture path and at least one non-empty tag.
• Manifest case paths are relative and may not contain absolute, platform-prefix, parent or current-directory components. Canonicalised fixture roots must remain inside tests/cases/, including through symlinks.
• IDs, paths, tags, contracts, roles and configured entries reject leading or trailing whitespace. Tags within one case must be unique.
• Every canonical case declares a role. Supported roles are primary, boundary, backend, adversarial and smoke.
• Every non-smoke case declares a contract. A whole-case acceptance-only smoke may remain contractless because it has no case-specific semantic owner. Do not invent a contract for it.
• A primary case requires a contract, and one contract may have at most one primary case.
• A contract family without a primary is reported once in manifest order. Backend-only and adversarial-only families are deliberate advisories. Mixed or ordinary secondary-only families remain visible for ownership review.
• Case IDs, tags, contracts and roles are retained as typed runner metadata. Do not reconstruct them from display text or fixture paths.
• One case folder owns all inputs and expectations for that scenario.

Manifest entry shape:

[[case]]
id = "borrow_conflict_resolved_by_reordering"
path = "borrow_conflict_resolved_by_reordering"
tags = ["integration", "borrows"]
contract = "language.bindings.alias_final_use_allows_mutable_rebinding"
role = "primary"

Focused integration selection and inventory

Use the canonical case ID and retained metadata for local iteration:

cargo run --quiet -- tests --case arithmetic_operator_precedence --backend html
cargo run --quiet -- tests --tag borrows --tag diagnostics --backend html
cargo run --quiet -- tests --contract <contract-id>
cargo run --quiet -- tests --list --tag borrows

• --case and --contract are exact matches.
• Repeatable --tag filters compose as logical AND.
• Case, tag, contract and backend filters compose and preserve manifest/backend order.
• --list accepts selection filters and reports canonical ID, selected backend blocks, tags, contract and role without compiling cases.
• Duplicate singleton options, duplicate tag values, missing values, unknown flags and positional arguments are errors.

Use the audit mode to validate and inventory the complete canonical suite without compiling cases:

cargo run --quiet -- tests --audit

Audit writes its JSON inventory before returning hard-policy failure. Normal listing and execution use the same policy evaluator and reject hard findings before compiling a case. Missing roles, missing contracts on non-smoke cases, primary cases without contracts and duplicate primary owners are hard findings. Contractless whole-case acceptance-only smoke cases are valid.

Audit cannot be combined with filters or --list. It writes the reporting-owned JSON inventory to target/test-reports/integration_suite_inventory.json, including canonical metadata, backend expectation facts, hard-policy violations and primary-less contract-family advisories. The report is review input only; it never deletes, merges or rewrites fixtures.

The schema 8 inventory reports acceptance-only, rendered-output, artifact, golden, absence and expected-warning backend counts, plus the zero baseline-only invariant. It reports exact, ordered and exact-once runtime contracts separately. Per-backend fields keep baseline_applied, acceptance_only, assertion_kinds, golden_present, golden_mode, every rendered-output form, exact warning codes, diagnostic match mode and any contains-mode reason separate so the report matches what ran.

Schema 7 added the weak-contract review fields. smoke_role_cases, warning_ignore_backend_blocks and diagnostic_contains_backend_blocks count the three legal weak contracts, and weak_contract_review_backend_blocks counts blocks carrying at least one of them. Every backend block lists its own weak_contract_reviews. These are review fields, not policy: a smoke case, an ignored warning contract and a contains-mode failure all remain valid. The canonical suite currently declares none of them, so any non-zero count is a new weaker contract to review rather than an inherited one to explain.

Schema 8 added report identity. Every report carries run — a run id, the command, the host OS and architecture, the features the binary was built with, the runner thread count and whether the run finished — and the inventory replaced repository_commit with repository_revision, which reports a discovered commit, not_a_repository, or unknown with the reason discovery failed. A failed discovery and a genuine absence are different facts, and a report that names neither its command nor its build cannot be told apart from a stale one.

Reports are written to a sibling temporary file and renamed into place, so a reader never sees a partial file. Before the work begins, each report is replaced by one whose run says `completed: false`; an interrupted run therefore leaves a report that says it did not finish rather than the previous run's passing output.

Hard policy has one suite-policy owner. Missing roles, missing non-smoke contracts, duplicate primary contracts, a primary without a contract and a whole-case acceptance-only fixture without role = "smoke" are hard findings. Normal list and execution modes reject hard findings before selection or compilation. Audit still writes the complete JSON report, then returns failure. Primary-less contract-family advisories remain non-fatal.

Runtime output assertions

Runtime assertions use one Node harness. It records console output and HTML fragment inserts in one event array when each event happens, then joins their text with newlines in that same order. Channel views are derived from the event array. They never reconstruct chronology after execution.

The harness runs only when a backend declares a rendered-output assertion. It executes the emitted page scripts and waits for one documented microtask tick so scheduled reactive updates can flush. Do not make extra scheduler turns or incidental microtask counts contractual.

Choose the narrowest field that owns the behaviour:

• rendered_output_exact protects the complete combined output. It is mutually exclusive with the other rendered-output fields. Exact comparison normalizes line endings only and preserves every other whitespace difference.
• rendered_output_contains_in_order protects the relative order of two or more fragments.
• rendered_output_contains_exactly_once protects activation, mounting and helper output from duplication.
• rendered_output_contains and rendered_output_not_contains protect required and forbidden fragments when complete output isn't the contract.

[backends.html]
mode = "success"
warnings = "forbid"
rendered_output_contains = ["active-root"]
rendered_output_not_contains = ["imported-root"]
rendered_output_contains_in_order = ["before-loop", "after-loop"]
rendered_output_contains_exactly_once = ["active-root", "mounted"]

Use exact output for small deterministic behaviours such as loop or map operation results. Use ordered and exact-once fragments when unrelated output may coexist. Prefer these runtime contracts over generated JavaScript text or a whole-page golden when execution is the real owner.

An exact mismatch is reported escaped, post-normalization, with the byte offset of the first difference, so a whitespace-only difference does not print as two identical lines.

What the harness will execute

The harness parses the emitted page for a supported script shape and rejects everything else rather than guessing:

• a classic inline script is executed
• type="module" is rejected as unsupported. The harness materializes no emitted glue, provider or runtime module and no import map, so it cannot run the module graph the HTML backend emits when a bundle import preamble is present. Executing it as a classic script would report a failure that did not happen
• an external src, an unknown type, nomodule, async, and a malformed or unterminated tag are each rejected by name
• the page script include must appear exactly once inside the body

Harness failure classes

A harness problem is never reported as a case failure. RenderHarnessError names which boundary broke: Artifact, Workspace, Spawn, Timeout, ExitStatus, OutputDecoding, OutputProtocol, ScriptShape or Cleanup. Execution is bounded by a 30-second deadline with kill-and-reap, stdout and stderr are drained on their own threads under a 4 MiB bound, and a stderr decode failure never replaces the boundary that actually failed.

Goldens carry their own artifact kind

A golden file's extension decides the artifact kind it expects, and a cross-kind match is rejected before content is read. Identical bytes emitted as a different artifact kind do not satisfy a golden. Text goldens require strict UTF-8; invalid UTF-8 is a harness failure, not a rewrite.

Concurrency and repetition

A test that waits for a thread to reach a state must observe that state, not guess how long reaching it takes.

• Use a condition variable or a channel for an expected transition.
• Use a bounded wall-clock deadline only as deadlock protection, never as the thing being measured.
• A deadline failure must name the observed state, so the report says what did not happen.
• Join every spawned worker, so a panic inside one is the reported cause rather than a discarded result.
• Do not make an arbitrary sleep, a yield count or a machine-speed threshold part of a contract.

Stateful owners — the timing collector, the frontend counter stores, output writes, current-directory guards and the Node harness — only misbehave under a thread schedule or a repeat that one default-parallelism run never produces. That schedule has an owned command:

just stress

It repeats the unit and integration suites at one thread, default parallelism and sixteen threads, and keeps running after a failing lane so the whole matrix is visible.

Diagnostics assertions

• Ordinary source/config/import/type/rule/borrow failures should assert stable diagnostic_codes.
• diagnostic_codes is an exact unordered multiset by default. Repeat a code when the diagnostic must occur more than once.
• Add rendered message fragments only when wording or rendered labels are part of the contract.
• Infrastructure-boundary tests may assert infrastructure ErrorType.
• Preserve source location assertions where location behavior is important.
• Do not use full rendered diagnostic snapshots when a stable code and structured assertion are sufficient.
• Do not weaken a diagnostic case into a generic "must fail" assertion.

[backends.html]
mode = "failure"
warnings = "forbid"
diagnostic_codes = ["MOTH-RULE-0033", "MOTH-RULE-0033"]

Use diagnostic_assertions when a broad code needs a compiler-owned reason or when source remapping is part of the contract. Each table selects one diagnostic by stable code and one-based occurrence. A unique code may omit occurrence. Repeat the code in diagnostic_codes to preserve its exact multiplicity.

[[backends.html.diagnostic_assertions]]
code = "MOTH-RULE-0057"
reason = "invalid_generic_instantiation.recursive_function_instantiation"
path = "input/@page.moth"
line = 3
count = 1

[[backends.html.diagnostic_assertions.secondary_labels]]
occurrence = 1
path = "input/helpers.moth"
line = 2

• Reason keys come from the compiler payload identity. The runner must not invent a parallel reason taxonomy or derive identity from rendered text.
• Paths are normalized relative to the owning fixture and lines are one-based display lines.
• Assert columns only when exact token-span precision is the contract.
• A secondary-label occurrence is one-based among that diagnostic's secondary labels in emitted order. Assert only the labels whose location or ordering is the behaviour owner.
• Keep message_contains only when rendered wording or label prose is itself contractual.

Use diagnostic_match = "contains" only when intentional independent recovery or cascades make additional diagnostics part of the accepted current behaviour. Every contains-mode block needs a substantive diagnostic_match_reason. The suite audit reports the reason and treats a missing or blank reason as a hard policy finding.

diagnostic_match = "contains"
diagnostic_match_reason = "Independent recovery may emit additional diagnostics from another source unit."

Warnings use a separate backend-local contract:

• warnings = "forbid" rejects every warning and accepts no warning_codes field.
• warnings = "ignore" deliberately makes warnings non-contractual and accepts no warning_codes field.
• warnings = "exact" requires warning_codes as an exact unordered multiset. Repeat duplicate codes to preserve their required count.

[backends.html]
mode = "success"
warnings = "exact"
warning_codes = ["MOTH-RULE-0022", "MOTH-RULE-0022"]
rendered_output_contains = ["warning-contract result=one"]

Backend matrices and artifact assertions

Use one expect.toml per case with backend-specific assertion blocks.

entry = "."

[backends.html]
mode = "success"
warnings = "forbid"
artifacts_must_not_exist = ["unexpected.html"]

[backends.html_wasm]
mode = "success"
warnings = "forbid"

[[backends.html_wasm.artifact_assertions]]
path = "page.wasm"
kind = "wasm"
validate_wasm = true
must_export = ["memory", "moth_str_ptr", "moth_str_len", "moth_release"]

• Use backend-specific blocks within one case.
• entry = "." is the one supported current-directory sentinel and selects the case's input/ directory. Every other entry is a relative contained path with no absolute, platform-prefix, parent or current-directory component. Its canonical path must remain inside the owning input/ directory, including through symlinks.
• Store strict goldens in:

golden/<backend>/

• Use artifact assertions for structure: file presence, Wasm validity, exports, imports, expected snippets, absence of forbidden output.
• Use artifacts_must_not_exist for success cases whose contract requires an exact normalized output path to be absent. Paths reported as NotBuilt are ignored because they were never emitted.
• Use strict goldens only where exact emitted text is contractual.
• The canonical suite currently has no file-backed golden blocks. A future golden needs an explicit exact-artifact rationale that a runtime or narrow artifact assertion cannot express.
• Golden discovery recursively counts actual files. Empty or directory-only golden trees do not create a contract. Nested files do.
• golden_mode without at least one discovered file is invalid. When files exist, strict is the default if no mode is authored. When no files exist, audit reports golden_present = false and golden_mode = null.
• Prefer semantic or rendered-output assertions for behavior-first cases.
• Strengthen artifact assertions when a golden can pass while structural behavior is wrong.
• Do not require unsupported backends to succeed merely for matrix symmetry. Assert the intended rejection contract.

HIR and internal-IR assertions

• Assert semantic relationships rather than incidental indexes.
• Prefer branch joins, merge-local relationships, jump arguments, region ownership, side-table keys, stable call targets and required operation kinds.
• Avoid exact block IDs or vector offsets unless exact layout is the invariant.
• Do not make temporary lowering order part of the public test contract.
• For HIR validation, distinguish malformed-HIR invariant tests from user-facing source diagnostic tests.

Feature and platform lanes

A feature-gated test that no command runs is not a test. Every declared Cargo feature belongs to a lane. Standard lanes run in the feature matrix. Deliberately expensive developer systems may use an opt-in lane with its own named command:

just test-feature-matrix

Lanes are package-scoped, and that is not a stylistic choice. Cargo unifies features across one resolve graph, and xtask depends on moth with features = timers, so cargo test --workspace always builds the compiler with timers enabled. It can never run the default configuration, and --features benchmark_counters on a workspace command is really timers plus counters. Only cargo test -p moth with an explicit feature list configures the crate the way a lane claims.

Feature coverage is checked mechanically, without running a lane:

just feature-lane-check

The check reads Cargo.toml and every cfg attribute in src and xtask/src, then fails when a declared feature has no lane, when a lane names a feature its package does not declare, or when a cfg names a feature that does not exist. A misspelled feature name in a cfg is a test that can never compile and never reports, which is why the check reads the tree instead of a list in prose. It writes target/test-reports/feature_lane_coverage.json, which names, for every feature, its standard lanes, opt-in lanes and the files whose cfg attributes mention it. That report is a coverage map and states no lane outcome, because the check that writes it runs no lane. Running the standard lanes is just test-feature-matrix, which writes their outcomes to target/test-reports/feature_matrix_results.json. The opt-in boracle and boracle-campaign lanes run only through their named just boracle and just boracle-campaign commands, not through the standard lane set.

Adding a Cargo feature means adding it to a standard or opt-in lane in the same change. The gate fails otherwise.

Platform-gated tests are owned by the platform that has the API:

CI runs every gate on Linux, macOS and Windows, so a platform-gated owner executes wherever its API exists. A platform-specific test may be absent only when the underlying API does not exist there; an equivalent portable policy test should still run everywhere. Windows results are currently non-blocking — validation.mtf owns that status and the conditions that end it.

Source-text assertions

A test that reads source text and asserts on it proves what the text says, not what the code does. An alias, a reformat or an equivalent reimplementation all pass it.

• Do not make a source-text assertion the only evidence for runtime or semantic behaviour.
• A ban whose scope is "no file anywhere may contain this" belongs to just source-audit, which walks the tree once and reports typed findings. validation.mtf > Source audit owns it.
• Reading a non-Rust asset a test then parses or executes is not a source-text assertion. The asset is the input, and the behaviour under test is the parse or the execution.

Fixtures and temporary files

• Prefer tempfile::tempdir() for temporary directories and files.
• Use unmanaged paths only when the test intentionally owns cleanup.
• Keep fixtures local to their owner.
• Do not commit generated dev/ or release/ outputs from test or benchmark projects.
• Avoid shared fixture builders that hide important source shape.

Pruning and duplicate coverage

• Remove tests tied only to deleted implementation paths.
• Avoid several fixtures that differ only cosmetically.
• Preserve duplicates only when they protect different stages, diagnostic reasons, backends, source locations or artifact contracts.
• Localize one-caller fixtures.
• When two tests overlap, identify the primary owner and either merge them, narrow each to a distinct invariant or delete the weaker one.
• Do not preserve obsolete fixtures for historical compatibility.

Benchmarks are not correctness tests

Benchmark fixtures are performance evidence, not correctness coverage.

Do not use benchmark coverage as a substitute for unit or integration tests. Negative diagnostics belong in tests/cases, not benchmark fixtures.

Use bench-check to detect broad performance regressions after correctness has already been established by ordinary tests.

Testing checklist

Before considering test coverage complete, check:

• The behavior has one clear primary test owner.
• User-visible behavior has end-to-end integration coverage.
• Internal-only invariants have focused unit coverage where needed.
• Failure cases assert stable diagnostic codes.
• Rendered text is asserted only when it is contractual.
• Backend behavior uses the narrowest useful artifact assertions.
• Goldens are used only where exact output is a contract.
• HIR tests avoid incidental block and local numbering.
• Multi-file fixtures remain inside one case directory.
• Temporary files use owned cleanup.
• No benchmark fixture is being used as a correctness substitute.
• Redundant or obsolete coverage has been removed.
• Every new Cargo feature was added to a lane in the same change.
• Every platform-gated test names the API that makes the gate necessary.
• No source-text assertion is the only evidence for a behaviour.
• No concurrency test waits on a sleep or a machine-speed threshold.

Validation gates

This document defines the technical gates a completed compiler or documentation slice must pass.

The required final gate depends on whether the slice changes implementation or is strictly documentation-only.

Task-reading guide

Start every completion decision with Choose the final gate by scope. Heading paths use > to name nested sections. Read the selected heading through the next heading of the same or higher level, including nested subsections unless the route narrows further. Read this document in full when changing validation infrastructure or auditing the complete gate policy.

Compiler invocation

Use an up-to-date release build of the compiler when one is available. The moth command in PATH is the usual direct form:

moth check docs --terse
moth build docs --release

If a suitable release build is not available, run the same operations through Cargo from the repository root:

cargo run --quiet -- check docs --terse
cargo run --quiet -- build docs --release

Choose the final gate by scope

The justfile is the executable authority for the full code-bearing gate.

Code-bearing final gate

A slice is code-bearing if it changes Rust, compiler or build-system sources, libraries, tests, benchmarks, manifests, scripts, configuration or any other non-documentation implementation file.

Before declaring a non-trivial code-bearing slice complete, run:

just validate

What just validate runs

• ci-clippy-native lints the native host only, across every workspace target and the explicit standard feature set. It deliberately excludes the opt-in boracle feature.
• Warnings are denied.
• Cross-target linting is CI's job: the gate matrix runs clippy on Linux, macOS and Windows.
• The workspace test command includes the compiler, CLI and xtask packages.
• That command is not the default configuration. xtask depends on moth with features = timers, and Cargo unifies features across one resolve graph, so cargo test --workspace always builds the compiler with timers enabled. The default configuration and each standard feature configuration are covered by just test-feature-matrix, not by just validate.
• bench-ci preflights every benchmark manifest case once, then measures only the quick CLI and frontend subsets with three iterations.
• bench-ci does not update local history or tracked benchmark summaries.
• bench-scaling answers the question history cannot. Every other benchmark mode compares a case against its own recorded past, so it detects change; a cost that has been superlinear since the day it was written never changes and never reports. The scaling lane measures the same metric at several declared input sizes and holds the fitted exponent to a budget. It writes no history either. benchmarks/README.md > Scaling Series owns the authoring rules.

The integration command loads the complete canonical suite and applies the shared hard-policy evaluator before selection or compilation. This makes missing ownership, duplicate primaries and other hard suite-policy findings part of the normal validation gate.

Test honesty audit

The campaign that hardened this suite is owned by one command:

just test-honesty-audit

It writes the canonical inventory to target/test-reports/test_honesty_inventory.json, and it is the single owner of what that file says. The inventory has four parts:

• Hard findings. Shapes with no honest use in this tree: the retired temp_dir helper, a /tmp literal handed to a call that touches the filesystem, a discarded current-directory or environment restoration, a discarded thread join, an ignore attribute with no reason, and a report written straight to its final path. Every hit fails the audit.
• Review findings. Shapes that can hide a weak contract and are also correct in most of their uses. The audit counts them, names the files, and records the disposition the campaign decided for the category. These never fail the audit. is_err, contains and any are review categories on purpose: a gate that failed on each of them would be turned off within a week.
• The declared ledger, read from docs/roadmap/evidence/honesty_ledger.json. Every entry must carry a severity, a status, a description, a disposition and an owning phase; a duplicate code, a missing decision or an open hard finding fails the audit.
• The composed audits. The source audit and the feature-lane check are run, not read, so the verdict never depends on when somebody last ran them. The integration suite inventory is read, because the compiler binary writes it, and its state is reported as one of absent, unusable or present so a missing report can never be read as a clean one.

The tracked durable copy under docs/roadmap/evidence/ is refreshed by the same owner, never by hand:

just test-honesty-evidence

What a report guarantees

Every machine-readable report is written to a sibling temporary file and renamed into place, so a reader never observes a partial file and a failed write leaves the previous report intact.

Every report also carries the identity of the run that produced it: an id unique within the process without depending on the wall clock, the command, the OS and architecture, the features the linked compiler was built with, a thread count where the command owns one, and whether the run finished.

Completion state is what separates the reports, and the distinction is real:

• test_honesty_inventory.json, source_audit.json and integration_suite_inventory.json are replaced by a completed: false report before their owned work starts. A run interrupted partway leaves a report that says so rather than a previous successful one that looks current.
• feature_matrix_results.json starts with every standard lane pending and is rewritten as each standard lane resolves, so an interrupted matrix reports the lanes it measured and the lanes it never reached. Opt-in lanes are owned by their named commands and do not appear as unmeasured matrix outcomes.
• feature_lane_coverage.json is a coverage map, not an outcome table. It answers which lane covers which declared feature, which just feature-lane-check establishes without running a single lane, so it is complete the moment it is written and never states a lane result. Lane outcomes live in feature_matrix_results.json.

Source audit

An architecture ban whose scope is "no file anywhere may contain this" is not a behaviour claim, and a unit test that reads one file's text and asserts on it is not behaviour evidence. Those bans have one owner:

just source-audit

It walks src and xtask/src once, applies every broad-source rule, and reports typed findings with the file each was found in. Only the audit's own implementation files are exempt, because they necessarily contain the fragments the rules search for; their rules are proved against fixture text instead. A source file that cannot be read is a finding, not a file the audit skips.

Add a broad-source ban here rather than as a test. A ban that lives in a test reads one file, calls that evidence, and stops applying the moment the code moves.

Feature lanes

just validate runs one standard feature configuration. The standard lanes run all standard configurations:

just test-feature-matrix

Eight package-scoped standard lanes cover the default configuration, timers, detailed_timers, benchmark_counters, timers with benchmark_counters, the scoped-block feature lane, every show_* feature and the xtask package. testing.mtf > Feature and platform lanes owns the lane table and what each lane uniquely covers.

The boracle feature is an opt-in developer lane. just boracle owns its formatting check, feature-enabled Clippy and smoke test. The boracle-campaign lane, using boracle_campaign, is a separate opt-in developer lane owned by just boracle-campaign. It was measured at roughly 61 seconds against roughly 8 seconds for the default lane, so it cannot belong in the default lane. Both lanes are intentionally excluded from just validate, just test-feature-matrix and ordinary CI gates.

Lanes use cargo test -p <package> rather than --workspace because Cargo unifies features across one resolve graph. xtask requires moth with timers, so no workspace-wide command can run the default configuration.

just feature-lane-check proves the mapping without running a lane, and is part of just validate. The report distinguishes standard and opt-in lane owners. Adding a Cargo feature means adding it to a standard or opt-in lane in the same change; the check fails otherwise.

CI gates

just validate is the local gate and is deliberately fail-fast: the first failure stops the run.

CI does not work that way. Each validation family is its own job, so one failure never stops another from reporting:

Each gate runs on Linux, macOS and Windows. The workflow result is still failed when any blocking gate fails. The integration, feature-matrix and honesty-audit gates upload target/test-reports/ whether they passed or failed, because a failed run's report is the evidence a reviewer needs most.

unit-tests and feature-matrix overlap on purpose. unit-tests runs the workspace-unified command a developer runs locally; feature-matrix runs the configurations that command cannot reach.

The release workflow keeps the single fail-fast just validate. A tag build only needs to know whether the revision is releasable, and the split gates have already reported on every push to the default branch.

Platform policy

Linux and macOS gates are blocking. Windows gates are non-blocking: a Windows failure is reported but does not fail the workflow or hold back deployment.

Windows becomes blocking when both hold:

• every gate has passed on windows-latest in one run of the default branch
• no Windows-only failure is open in the exposed-failure ledger

The change is then removing continue-on-error from the gate job. Until that happens, a Windows result is evidence to act on, not a gate that can be ignored: a Windows-only failure belongs in the ledger like any other.

A platform-specific test may be absent only when the underlying API does not exist on that platform. An equivalent portable policy test should still run everywhere. `testing.mtf > Feature and platform lanes` owns which gate owns which platform behaviour.

Documentation-only release-build gate

A slice is documentation-only only when every modified file is documentation source or generated documentation.

Allowed examples include:

• files under docs/**
• an explicitly requested root documentation file such as README.md, CONTRIBUTING.md or AGENTS.md
• generated files under docs/release/**

A documentation-only slice must not change Rust, tests, libraries, build configuration, manifests, scripts, benchmark code or fixtures, compiler configuration or other executable project sources.

For a strictly documentation-only slice, run one documentation release build using a current compiler.

The direct release-binary form is:

moth build docs --release

If no suitable release build is available, use cargo run --quiet -- build docs --release instead.

Then:

• inspect every changed route
• inspect the generated diff
• verify links, tables and code examples
• confirm generated output came from source changes
• confirm the changed-file list contains documentation only.

Do not additionally run just validate, Clippy, unit tests, integration tests or benchmark checks for a documentation-only slice. A Cargo invocation of the compiler is an alternative way to run the same documentation gate, not an extra gate.

If any non-documentation file changed, the documentation-only exception does not apply. Use the full code-bearing gate.

Fast iteration commands

Passing one targeted command does not imply a code-bearing slice passes the complete gate.

Formatting

• Run cargo fmt when Rust files changed.
• just validate does not currently format source automatically.
• Do not solve formatting failures through lint suppression.
• Documentation-only changes do not require Rust formatting.

The ship recipe formats before validation, while validate itself does not.

Generated documentation

Do not edit files under docs/release/** directly.

The documentation release build is:

moth build docs --release

A generated diff must result from documentation source changes, not manual HTML edits.

Manual architecture audits

When a code-bearing slice changes stage ownership, frontend boundaries, HIR, diagnostics, types or backend handoff, perform a manual architecture audit in addition to the automated gate.

Audit that:

• stage ownership remains narrow
• AST and HIR type representation still respect TypeEnvironment and TypeId
• user-facing failures use CompilerDiagnostic
• internal and infrastructure failures use CompilerError
• no obsolete API or duplicated path remains
• no backend reparses source syntax
• no analysis mutates HIR when its contract is side-table based
• comments and documentation name the current owner
• no compatibility shim preserves an obsolete path

This full architecture audit is not required for a prose-only documentation change.

Progress-matrix review

Review the progress matrix whenever behaviour, support, rejection, backend coverage or test coverage changes.

Update it when current status changed. Do not make a meaningless edit for a pure refactor or prose-only correction.

Benchmark safety

• just validate uses non-recording bench-ci.
• bench-ci validates every benchmark case before it measures the quick subset. It replaces the full ten-iteration CLI and frontend checks inside the normal validation gate.
• Use just bench-check and just bench-frontend-check for deliberate full-suite performance evidence. Both commands remain non-recording.
• Do not run or commit recording benchmark output unless performance history is intentionally being updated.
• A benchmark fluctuation does not replace correctness evidence.
• Generated benchmark history is outside this standards split.

Failure handling

• Do not ignore or suppress a failed required gate.
• Do not remove tests merely to make validation pass.
• Do not use lint allowances without documented justification.
• If a required command fails for environmental reasons, report the exact command, failure, completed checks and remaining uncertainty.
• Do not claim full validation when only targeted commands or the documentation-only gate ran.

Code-bearing completion checklist

Before declaring a non-trivial code-bearing slice complete, check:

• Rust source was formatted where applicable.
• The changed code follows style-guide.mtf.
• Test selection and assertions follow testing.mtf.
• Relevant architecture boundaries were reviewed.
• Diagnostics remain structured and stage appropriate.
• The progress matrix was reviewed and updated when status changed.
• Documentation was rebuilt when required.
• Generated output was not edited manually.
• Benchmark history was not changed accidentally.
• just validate passes.

Documentation-only completion checklist

Before declaring a documentation-only slice complete, check:

• The changed-file list contains documentation only.
• The documentation release build succeeds.
• Changed routes, links, tables and examples were inspected.
• Generated output was produced from source changes.
• No generated HTML was edited manually.
• No code, test, build, library, manifest, script, benchmark or configuration file changed.