This page tracks the current implemented compiler surface.
It is an implementation matrix, not a full language specification. The wider language docs may describe intended or aspirational syntax. This page should describe what the compiler currently supports, rejects cleanly, or keeps experimental.
Use this together with tests/cases/manifest.toml when changing language features.
The supported Alpha target is:
A policy for the repo is all tests must pass before each commit. So all tests on all platforms can be assumed to be green for the current state of the compiler unless specifically noted here.
| Status | Meaning |
|---|---|
| Supported | Implemented for the Alpha surface and expected to compile, type check, lower, and run through the JS / HTML pipeline. |
| Partial | A useful subset is implemented, but some sub-surfaces are intentionally deferred or still being shaped before Alpha. |
| Experimental | Present in the repo, but not part of the Alpha stability promise. |
| Deferred | Not part of Alpha. Syntax should either be reserved or rejected with structured diagnostics. |
| Coverage | Meaning |
|---|---|
| Broad | Multiple focused cases exist, including success and failure coverage. |
| Targeted | Dedicated coverage exists, but not across all important edges. |
| Thin | Coverage exists indirectly or through only a small number of cases. |
| None | No clear canonical coverage found. |
| Surface | Status | Coverage | Runtime target | Watch points |
|---|---|---|---|---|
| Entry files and implicit start | Supported | Broad entry-start, dependency-sort, non-entry top-level rejection, imported-start, and fragment-order coverage. | Frontend / HTML builder | Only the module entry file runs top-level runtime code. Non-entry top-level executable code and runtime templates are rejected. The implicit start function is build-system-owned and is not an importable/callable user declaration. |
| Variables, assignment, and scoped blocks | Supported | Broad declaration, reassignment, mutability, scope, shadowing, undefined-mutation, block-scope, and diagnostics coverage. | JS / HTML | Mutable writes require mutable places. block: creates a lexical/control-flow scope. Bare labeled scopes remain rejected. |
| Control flow | Supported | Broad parser, HIR, integration, dispatcher, and structured-lowering coverage. | JS / HTML | Keep loops, break / continue, match lowering, and branch-heavy CFG cases covered. |
| Functions and calls | Supported | Broad function declaration, call validation, parameter passing, external-call, and return coverage. | JS / HTML | Keep named and positional call semantics strict. External and builtin calls remain positional-only. |
| Templates and style directives | Supported | Broad template parsing, slot, directive, const-fragment, and runtime-fragment coverage. | HTML / JS | This is one of the main Alpha surfaces. Keep fragment ordering and slot composition heavily tested. |
| Structs, records, and receiver methods | Supported | Broad integration coverage with targeted parser and receiver-catalog unit coverage. | JS / HTML | Field mutation, nested field mutation, nominal mismatch, constructor named arguments, receiver borrow behavior, scalar receiver methods, and cross-file exported receiver use are covered. Keep Wasm receiver behavior experimental. |
| Choices | Supported | Broad parser, declaration, constructor, match, import, assignment, return, JS carrier-shape, and payload coverage. | JS / HTML | Unit variants use `Choice::Variant`. Empty constructor calls are invalid. Record-body payload declarations are parsed and type-checked. Payload constructors support positional and named arguments. Payload match extraction uses constructor-like patterns with original field names or `field as local_name` aliases. Const choice values are supported for unit and payload variants. Payload shorthand is rejected. Payload structural equality is deferred. Generic choices, recursive choices, and direct payload field access remain deferred. Choices, Options, and Results share a unified HIR variant construction representation while retaining distinct semantic type kinds. |
| Pattern matching | Partial | Broad literal, choice-match, and payload-capture coverage, including exhaustiveness and diagnostics. | JS / HTML | Literal patterns, choice variant patterns (including payload captures with `field as local_name` aliases), relational ordered-scalar patterns, guards, and else are supported. Wildcard in case arms is not supportedāuse else => instead. General capture/tagged patterns and nested payload patterns remain deferred. `as` in non-choice match patterns is rejected with a structured diagnostic. |
| Collections | Supported | Broad collection literal, mutation, builtin method, indexing, loop, result, and JS helper coverage. | JS / HTML | Collection helper runtime contracts should remain JS-owned for Alpha. HTML-Wasm collection behavior is experimental only. |
| Results, options, multiple returns, and multi-bind | Supported | Broad result, option, fallback, propagation, handler, cast, and multi-bind coverage. | JS / HTML | Multi-bind is limited to explicit multi-return function calls. It is not general destructuring. |
| Constants and compile-time folding | Supported | Broad constant declaration, const-only validation, cross-file soft dependency, folding, overflow, const-template, and const-record coverage. | Frontend / HTML builder | Runtime expressions and host calls in constants are rejected. Module constants remain compile-time metadata rather than runtime top-level statements. |
| Type aliases | Supported | Broad alias declaration, collection/option/import/external target, visibility, cycle, duplicate, value-misuse, constructor-misuse, and import-alias interaction coverage. | Frontend-owned | Type aliases are transparent and annotation-only. Imported aliases are file-local; exporting an imported type under a public name requires declaring a real exported type alias. |
| Arithmetic, numeric casts, and explicit copy | Supported | Broad arithmetic, precedence, integer division, contextual numeric promotion, compound assignment, builtin cast, runtime fallback, explicit copy, and JS helper coverage. | JS / HTML | Regular / returns Float. // requires Int. Int(...) and Float(...) return Result values and must be handled. ^ exists in frontend/JS lowering but has thin coverage; Wasm exponent support remains outside Alpha. |
| Type checking and coercion | Supported | Broad type compatibility, contextual promotion, strict expression typing, call argument, and declaration coverage. | Frontend-owned | Keep strict expression typing separate from contextual declaration / return coercion. |
| String coercion and IO/template boundaries | Supported | Broad valid string-content coercion plus IO/template rejection coverage for structs, collections, options, results, and multiple-return values. | Frontend / JS | Template heads and io accept only supported string-content values. Complex values must be handled, extracted, or converted before string-boundary use. |
| Borrow validation and ownership analysis | Supported | Broad borrow, aliasing, mutable/exclusive access, use-after-move, branch merge, loop, short-circuit, lifetime, drop-site, and adversarial coverage. | HIR analysis / JS GC baseline | Borrow validation enforces exclusivity and move-safety, while ownership/drop facts remain advisory for GC-only JS. Do not make ownership semantic; GC fallback remains the language baseline. |
| Paths and imports | Supported | Broad import syntax, relative path, root folder, circular dependency, multi-file module, single-symbol aliases, grouped aliases, nested grouped aliases, collision, and file-local coverage. | Frontend / HTML builder | Path rendering is golden-sensitive. Keep normalized output and platform-stable diagnostics covered. Single-symbol source import aliases, grouped source import aliases, and nested grouped source import aliases are supported. Aliases are file-local and not re-exported. Alias collisions are hard errors across same-file declarations, source imports, external imports, type aliases, prelude symbols, and builtins. Alias case mismatches warn. Grouped import aliases reject group-level trailing aliases, invalid local alias names, and duplicate alias syntax with structured diagnostics. |
| External platform packages | Partial | Broad package-scoped import and visibility coverage, with targeted external constant, Float/F64 ABI, core libraries, prelude, duplicate-name, non-imported-symbol, and alias diagnostics. | Frontend / JS | Functions, opaque types, and compile-time external constants are supported through Rust-side registry metadata.
|
| Core prelude libraries | Supported | Targeted coverage for prelude symbol registration and collision rejection. | Frontend / JS | Every builder must provide `@core/prelude`. `io` and `IO` are registered as bare prelude symbols. Prelude collision rejection is enforced: explicit imports cannot shadow prelude names. |
| Core math package | Supported | Targeted success and diagnostic coverage for direct, grouped, and aliased imports; aliased constants such as PI as pi; aliased functions such as sin as sine; const-context constants; arity errors; type errors; missing symbols; and non-imported access. | JS / HTML | @core/math exposes PI, TAU, E, and Float functions backed by JavaScript Math.
|
| Core text package | Partial | Targeted runtime, JS helper, type-error, unsupported-builder, and Wasm-unsupported coverage. | JS / HTML | @core/text exposes length, is_empty, contains, starts_with, and ends_with. It is JS-backed, explicit-import only, and optional by builder. Wasm support is deferred. |
| Core random package | Partial | Targeted import, JS helper, runtime smoke, arity, and type-error coverage. | JS / HTML | @core/random exposes random_float() and random_int(min, max). random_int is intended for the inclusive range min <= value <= max when min <= max. Seeded random and min > max runtime diagnostics are deferred. |
| Core time package | Partial | Targeted import, JS helper, runtime smoke, and arity-error coverage. | JS / HTML | @core/time exposes now_millis() and now_seconds(). Full date/time/timezone objects, formatting, durations, and monotonic clocks are deferred. Wasm support is deferred. |
| Source library roots | Partial | Targeted coverage for filesystem-based source library root resolution, prefix collision detection, and `#mod.bst` facade enforcement. | Frontend / HTML | Project-local libraries under `/lib` are discovered automatically and resolve through the path resolver. Builder-provided source library roots are plumbed through `LibrarySet`. Prefix collisions between builder-provided and project-local libraries produce a hard config error. Every source library root must contain a `#mod.bst` facade file. Cross-library imports are gated through the facade: external importers can only import symbols explicitly exported by `#mod.bst`. |
| Builder-provided source libraries | Partial | Targeted coverage for builder-provided source library root registration and HTML builder library. | Frontend / HTML | Builders expose source libraries through `LibrarySet.source_libraries`. The HTML builder provides `@html` as a default source library with basic HTML tag helpers and formatting utilities. Other builders may provide their own libraries. Prefix collisions between builder-provided and project-local libraries produce a hard config error. |
| Project-local libraries | Partial | Targeted coverage for `/lib` auto-discovery, import resolution, and facade gating. | Frontend / HTML | A `/lib` directory at the project root is scanned for subdirectories, each treated as a source library prefix. Imports like `@helper/utils` resolve to `lib/helper/utils.bst`. Every library must declare a `#mod.bst` facade that exports its public surface with `#`. Cross-library imports bypassing the facade are rejected. |
| HTML project builds | Supported | Broad routing, document shell, metadata, tracked asset, config, and page-fragment coverage. | HTML / JS | This is the release-critical project backend. HTML-Wasm cases must not be treated as Alpha support requirements. |
| Logical expressions | Supported | Broad precedence, grouping, invalid operand, not, comparison, and JS operator mapping coverage. | JS / HTML | Keep short-circuit behavior covered through artifact-shaped tests. |
| If statements and conditions | Supported | Broad condition validation, nested condition, Bool requirement, and JS lowering coverage. | JS / HTML | No major Alpha gap if current control-flow coverage remains green. |
| Char | Supported | Broad success coverage with targeted diagnostic coverage. | JS / HTML | Additional malformed-char diagnostics are useful cleanup, not a core Alpha blocker. |
| Named arguments and call-site mutability | Supported | Broad function-call, constructor-call, duplicate, unknown, missing, ordering, and tilde diagnostics coverage. | JS / HTML | Fresh rvalues can satisfy mutable parameters without ~. Existing places still require explicit ~. |
| Surface | Status | Coverage | Runtime target | Watch points |
|---|---|---|---|---|
| Collection methods | Supported | Broad JS helper, mutation, indexed write, out-of-bounds, and explicit-mutable-receiver coverage. | JS / HTML | get, set, push, remove, and length are compiler-owned surfaces. |
| Error helper methods | Supported | Targeted coverage for with_location, push_trace, and bubble. | JS / HTML | Keep emitted helper contracts pinned through JS backend tests. |
| Receiver methods | Supported | Broad method call, export, same-file restriction, unsupported receiver, and mutable receiver diagnostics coverage. | JS / HTML | User-defined struct methods must stay statically resolved and same-file with the struct for Alpha. |
| Result suffix handling | Supported | Broad propagation, fallback, named handler, handler fallthrough, and template-boundary coverage. | JS / HTML | Keep __bs_result_propagate and __bs_result_fallback contracts covered by artifact assertions. |
| Builtin Error type | Supported for current runtime surface | Reserved symbol diagnostics and helper runtime coverage exist. | Frontend / JS | Further Error enrichment is deferred. Do not expand this before Alpha unless required by supported result handling. |
These are useful and may have tests, but they are not part of the Alpha stability contract.
| Surface | Status | Current role | Alpha rule |
|---|---|---|---|
| HTML-Wasm | Experimental | Backend experiment and integration path for future Wasm output. | Keep behind --html-wasm. Tests may pin current behavior, but Alpha support is JS / HTML. |
| Wasm backend | Experimental | Long-term backend direction. Current lowering/runtime support is partial. | Do not count Wasm support as an Alpha blocker except for clean diagnostics or no-panic guarantees on covered paths. |
These are intentionally not counted as supported Alpha features. If syntax exists, it should fail with a structured diagnostic rather than panic or lower incorrectly.
| Surface | Status | Canonical diagnostic direction | Notes |
|---|---|---|---|
| Traits / interfaces | Deferred | trait_declaration_reserved, trait_this_reserved | Syntax is reserved for future design work. |
| Async / concurrency scopes | Deferred | async_block_reserved, async_keyword_declaration_rejected | Future async syntax is design-only. Current async statement and declaration positions are rejected with structured diagnostics. |
| Checked scopes | Deferred | checked_block_reserved, checked_keyword_declaration_rejected | checked is reserved and rejected cleanly until checked/effect semantics are designed. |
| Labeled scopes | Rejected / Reserved | labeled_scope_rejected | Bare label: syntax is not supported. Use block: for ordinary scoped blocks. |
| Legacy / foreign-language syntax | Rejected / Reserved | typescript_style_declaration_rejected, diagnostic_statement_keyword_fn, diagnostic_statement_keyword_let, diagnostic_statement_keyword_match, diagnostic_statement_comment_slash_slash, diagnostic_expression_double_equal, diagnostic_expression_bang_equal, diagnostic_expression_and_and, diagnostic_expression_or_or, diagnostic_expression_bang_negation | These are diagnostic-quality fixtures only. Do not treat compatibility syntax as planned Alpha surface. |
| Choice unit variants | Supported | choice_basic_declaration_and_use, choice_unit_constructor_call_rejected, choice_imported_unit_constructor_call_rejected | Unit variants are constructed as `Choice::Variant`. Empty constructor calls are invalid. |
| Choice record payload variants | Supported | choice_payload_record_declaration_success, choice_payload_imported_field_type_success, choice_payload_empty_record_rejected, choice_payload_duplicate_field_rejected, choice_payload_mutable_field_rejected, choice_payload_field_default_rejected, choice_payload_shorthand_rejected | Only `Variant | field Type, ... |` syntax. Payload shorthand is rejected. |
| Choice constructor use | Supported | choice_payload_constructor_positional_success, choice_payload_constructor_named_success, choice_payload_constructor_mixed_success, choice_payload_constructor_missing_field_rejected, choice_payload_constructor_unknown_field_rejected, choice_payload_constructor_duplicate_field_rejected, choice_payload_constructor_positional_after_named_rejected, choice_payload_constructor_type_mismatch_rejected, choice_payload_constructor_without_args_rejected, choice_unit_constructor_call_rejected, choice_imported_unit_constructor_call_rejected, choice_imported_payload_constructor_success | Unit variants use `Choice::Variant` without parentheses. Payload variants use `Choice::Variant(...)` with positional and named arguments. Empty constructor calls on unit variants are rejected. Missing constructor args on payload variants are rejected. |
| Choice const values | Supported | choice_const_unit_success, choice_const_payload_success | Unit and payload choice variants can be used in top-level `#` constant declarations. |
| Choice payload matching | Supported | choice_payload_match_capture_success, choice_payload_match_qualified_capture_success, choice_payload_match_guard_uses_capture_success, choice_payload_match_import_alias_success, choice_payload_match_exhaustive_tag_level_success, choice_payload_match_wrong_capture_name_rejected, choice_payload_match_too_few_captures_rejected, choice_payload_match_too_many_captures_rejected, choice_payload_match_duplicate_capture_rejected, choice_payload_match_capture_shadowing_rejected, choice_payload_match_rename_success, choice_payload_match_rename_guard_success, choice_payload_match_rename_wrong_original_rejected, choice_payload_match_rename_duplicate_binding_rejected, choice_payload_match_rename_shadowing_rejected, choice_payload_match_rename_missing_alias_rejected, choice_payload_match_rename_non_symbol_alias_rejected, choice_payload_match_rename_original_not_visible_rejected, choice_payload_match_rename_self_alias_success, choice_payload_match_named_assignment_rejected, choice_payload_match_missing_payload_rejected, choice_payload_match_unit_parens_rejected, choice_payload_match_duplicate_variant_rejected, choice_payload_match_guard_requires_else | Constructor-like patterns support declared payload field names and `field as local_name` aliases. Field matching remains positional and validated against declared field names. Exhaustiveness is tag-level. |
| Choice payload field access | Deferred | choice_payload_direct_field_access_deferred | No `value.field` until variant narrowing/refinement is designed. Use pattern matching to extract payload fields. |
| Choice payload capture renames | Supported | choice_payload_match_rename_success, choice_payload_match_rename_guard_success, choice_payload_match_rename_wrong_original_rejected, choice_payload_match_rename_duplicate_binding_rejected, choice_payload_match_rename_shadowing_rejected, choice_payload_match_rename_missing_alias_rejected, choice_payload_match_rename_non_symbol_alias_rejected, choice_payload_match_rename_original_not_visible_rejected, choice_payload_match_rename_self_alias_success | `case Variant(original_name as local_name) =>` binds the payload field to a different local name visible in the guard and arm body. |
| `as` keyword outside supported domains | Rejected / Reserved | as_in_expression_rejected, as_in_variable_declaration_rejected, as_in_function_signature_rejected, as_in_non_choice_match_pattern_rejected, as_in_match_pattern_lead_rejected | `as` is only valid in three contexts: type aliases (`TypeAlias as ExistingType`), import clauses (`import @path/symbol as local_name`), and choice payload captures (`case Variant(field as local_name)`). All other uses are rejected with targeted diagnostics. |
| General pattern binding renames | Deferred | No canonical case yet. | Non-choice capture renaming and nested payload pattern renaming remain deferred. |
| Choice nested payload patterns / exhaustiveness | Deferred | choice_nested_payload_pattern_deferred | Exhaustiveness is tag-level for now. |
| Import re-exports | Supported | Targeted coverage for single, aliased, grouped, nested grouped, external function, external type, duplicate, collision, no-local-binding, and invalid-location diagnostics. | `#import @...` is valid only in `#mod.bst` source-library facades. It re-exports source or external package symbols through the facade export map without creating a local binding in `#mod.bst` or sibling implementation files. Namespace and wildcard imports remain deferred. |
| Source-library HIR caching | Deferred | No precompiled source-library cache. | Source libraries are compiled from `.bst` source each build. HIR caching is deferred until the library system is stable. |
| Package manager | Deferred | No package manager, remote registries, or dependency resolution. | The library system plan explicitly defers package management, versioning, lockfiles, and remote fetching. |
| Namespace / wildcard imports | Deferred | Unsupported syntax should fail cleanly. | No `import @pkg.*` or namespace-import syntax is planned for Alpha. |
| Choice recursive types | Deferred | choice_recursive_direct_declaration_deferred | Requires layout/indirection design. |
| Choice generic declarations | Deferred | choice_generic_declaration_deferred | Syntax ideas live in docs/src/docs/generics.md; do not implement here. |
| Choice payload structural equality | Rejected / Reserved | choice_payload_structural_equality_deferred | Payload structural equality is deferred. Use pattern matching and compare fields inside the matching arm. |
| Choice tagged/default declarations | Deferred | No canonical tagged-declaration case yet; choice_default_decl_deferred covers default declaration rejection. | These belong to the fuller tagged-union design, not the current Alpha subset. |
| Choice default variant values | Deferred | choice_default_decl_deferred, choice_variant_default_value_deferred | If field defaults are inherited, document separately from variant defaults. |
| Wasm payload layout for choices | Experimental | No canonical case yet. | JS is the supported Alpha backend. Wasm backend lowering for choice payloads remains experimental. |
| Negated match patterns | Deferred | diagnostic_match_negated_pattern | Should wait until the match exhaustiveness model is deliberately extended. |
| General capture / tagged match patterns | Deferred | diagnostic_match_deferred_capture_pattern | Choice payload capture patterns are now supported. General capture/tagged patterns and rename captures remain deferred. |
| Rich numeric redesign | Deferred | Unsupported syntax should fail cleanly. | Includes arbitrary precision compile-time arithmetic, decimal type work, and more specific numeric widths. |
When a language feature changes shape:
The goal is to keep the Alpha surface small, honest, and fully exercised.