Compiler Internals

The current compiler story is self-hosted-first. The repo still contains Rust-side infrastructure, but the active implementation map a contributor should learn now lives primarily under self-hosted/, with the checked souc artifact acting as the executable front door for users and for most docs verification.

Current architecture map

• self-hosted/lexer/ and self-hosted/parser/ handle tokenization and syntax.
• self-hosted/resolve/ handles imports, modules, and package resolution work.
• self-hosted/check/ is the semantic heart of the compiler, covering types, effects, epistemics, units, ownership, patterns, traits, refinements, and more.
• self-hosted/hlir/ and self-hosted/ir/ cover lowering and optimization-oriented intermediate representations.
• self-hosted/native/, self-hosted/wasm/, self-hosted/gpu/, self-hosted/llvm/, and self-hosted/lsp/ cover backend and tooling work.

The artifact-facing view

export SOUC_BIN="$(pwd)/artifacts/omega/souc-bin/souc-linux-x86_64-jit"
"$SOUC_BIN" info
"$SOUC_BIN" --help

How Rust still fits in

• crates/souc/ still exists, but in the current tree it is no longer the best top-level explanation of where most language and backend work is happening.
• The checked artifact you run today was produced through the repo’s build and release machinery, so Rust-side code still matters to artifact production and bridging.
• For docs, the safest contributor narrative is: use the artifact for current behavior, and use self-hosted/ as the primary implementation map.

How to navigate the codebase

• Start at self-hosted/compiler/main.sio for the driver-facing view.
• Then move outward to the dedicated subsystem directories instead of relying only on the thin wrapper files in self-hosted/compiler/.
• Use docs/codebase_overview.md and the implementation docs as orientation aids, but confirm path-level claims against the actual tree.