Language Guide

The language surface you should teach today is the conservative subset that appears repeatedly in examples, tests, and the current checked artifact. This page is a map of that stable teaching surface, not a promise that every historical syntax form or research DSL in the repo is equally available.

What belongs in the stable teaching surface

• Local bindings with let and var.
• Functions, blocks, return types, and explicit with ... effect annotations.
• Control flow such as if, while, for, and match.
• Core algebraic and epistemic ideas that can be demonstrated with checked fixtures instead of only with design documents.

Where the implementation lives now

• Parsing and grammar work is concentrated under self-hosted/lexer/ and self-hosted/parser/.
• Name resolution lives under self-hosted/resolve/.
• Type checking and semantic checks live under self-hosted/check/, including dedicated modules for effects, epistemic checks, units, ownership, traits, and refinements.
• The older Rust-side compiler docs are still useful as historical architecture references, but they are no longer the best primary map of the active source tree.

Representative syntax

let value = 5
var count = 0

fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() with IO {
    if value > 0 {
        println(add(value, count))
    }
}

How to stay accurate when documenting syntax

• Prefer examples that can be validated immediately with souc check.
• Cross-check advanced claims against tests/run-pass/, tests/compile-fail/, and the feature snapshot in the docs.
• If a language feature is only described in a large architecture note or an old guide, document it as design intent unless you have a current fixture or artifact-backed proof.