
# SLeeLa Compiler
Max Rupplin - MEARVK LLC - 2026
The `/lib/compiler` package is the SLeeLa-sourced compiler design and implementation layer. It is VM-ready: compiler declarations are written in `.sleela`, and the native C/C++ layer provides a stable implementation boundary for compiler services.
## Multi-language framework
The package also provides a **modular framework for building compilers for any
publicly known programming language** (C, C++, Java, Python, JavaScript, Rust,
Go, …). A developer adds a language by writing one small SLeeLa front end that
extends `SLLanguageCompiler`; many independent front ends register into one
shared `SLCompilerRegistry` with no per-language allow-list. Each front end
lowers its own language toward the common SLeeLa IR and a VM-ready artifact.
See [`MULTI-LANGUAGE.FRAMEWORK.md`](MULTI-LANGUAGE.FRAMEWORK.md) for the full
reference, the per-language front ends under [`frontends/`](frontends/), and
lesson [`tutorials/04-building-a-language-front-end.md`](tutorials/04-building-a-language-front-end.md).
The framework identifies, plans, and reports; it never executes an input
program. Compilation is not execution — a produced artifact runs only later
across an explicit SLeeLa VM/OS and security boundary.
## Authority
The authoritative path is:
`.sleela source -> compiler frontend -> semantic analysis -> SLeeLa IR -> VM lowering -> SLVM/SLJVM artifact`
The compiler does not create a parallel language. Native C/C++ code implements the declared compiler services; SLeeLa definitions describe the compiler model and are the source-level contract.
## Pipeline
1. Source loading
2. Lexing
3. Parsing
4. Declaration/object discovery
5. Name and symbol resolution
6. Type and semantic analysis
7. SLeeLa IR construction
8. Capability and dependency review
9. VM lowering
10. SLVM/SLJVM emission
11. Diagnostics and compile report
## Profiles
- BASIC_COMPLETE: a complete usable compiler path for a declared target.
- ADVANCED_TOTAL: complete pipeline inventory with explicit semantic, capability, dependency, security, provenance, and VM-target checks.
The Compiler Manager in `/lib/vm` remains the completeness gate for VM object declarations. This package supplies the compiler implementation that feeds that gate.
## Native boundary
C provides the stable ABI. C++ may orchestrate compiler objects and pipelines, but cannot bypass the SLeeLa capability, security, resolver, memory, certificate, or VM boundaries.
## Build
`make -C lib/compiler`
or from the repository root:
`make compiler`
No object, module, capability, or VM feature is silently inserted or removed by the compiler.
## Language and format reference
The package uses LANGUAGE.FORMAT.REFERENCE.md as its native reference for language names, producer programs, source forms, IR/object models, binary/executable formats, OS/ABI associations, and safety considerations. These references are identification and planning data only; they never grant execution permission.
## SST and Nordshrift source/compile integration
`/lib/sst` and `/lib/nordshrift` are canonical SLeeLa source-facing packages. They participate in the same recursive `/lib` discovery used by the compiler and loader.
The path is:
`.sst source -> Nordshrift -> /lib discovery -> .sleela source -> SLeeLa Compiler -> SLeeLa IR -> SLVM/SLJVM`
SST remains declarative input. Nordshrift resolves and emits SLeeLa source. The compiler consumes that output through the normal library index; there is no second package allow-list.
## SST symbol intake
SST declarations are not opaque metadata. Nordshrift resolves them as package-qualified compiler symbols against the canonical `/lib` index before emitting SLeeLa. The compiler then consumes the emitted SLeeLa symbols through its normal name-resolution pipeline.
## SST symbol intake
SST declarations are not opaque metadata. Nordshrift resolves them as package-qualified compiler symbols against the canonical `/lib` index before emitting SLeeLa. The compiler then consumes the emitted SLeeLa symbols through its normal name-resolution pipeline.
## Native compiler build
The native implementation is now wired directly to the authoritative `/impl/frontend` compiler build. `make -C lib/compiler all` builds the compiler contract objects, builds `impl/build/sleela`, and runs the recursive `/lib` source + ISA gate. The repository-wide `tools/sleela-build.py compile SOURCE OUTPUT` command performs the same source inventory/ISA gate before emitting a persistent runnable `.sleela` Core artifact.
## Case handling and object construction
- [CASE-HANDLER.md](CASE-HANDLER.md) — case-label validation and selection-branch diagnostics
- [OBJECT-CREATION.md](OBJECT-CREATION.md) — explicit `new Type(...)` and semantically resolved concise `Type(...)`
- [CONSTRUCTOR-SERIES.md](CONSTRUCTOR-SERIES.md) — constructor overload resolution, delegation graph, initialization order, and cycle checks
SLeeLa source-level reference handlers are provided by `SLCaseHandler.sleela`, `SLObjectCreationResolver.sleela`, and `SLConstructorSeries.sleela`. These define the intended compiler contract; integration with the native frontend and passing tests must be verified before describing the feature as production-ready.
## Authoritative language specification — Syntax 3.0
The repository-root [`SLEELA.syntax`](../../SLEELA.syntax) is the single
normative language specification. **Syntax 3.1** is the current edition; the
shared native frontend accepts declared source syntax **1.0–3.1** and defaults
unversioned source to 3.0 with a warning. A source file's `#sleela X.Y`
pragma selects its syntax edition. Compiler/tool release numbers are
independent of that language version.
Syntax 3.0 consolidates the established 1.x and 2.x language surface without
silently changing historical feature gates. Features introduced in earlier
editions remain gated at their documented minimum versions; for example,
Syntax 2.9 `@mix` remains a 2.9 feature. The compiler must preserve source
version evidence through diagnostics, intermediate representation, and
artifact metadata. Consult the [syntax version matrix](../../api/sleela/2.1/language/SYNTAX-VERSION-MATRIX.md)
for the feature chronology and implementation boundaries.
Unsigned and wide-integer source signatures must preserve their declared kind
and width through lowering and runtime boundaries. Unsupported operations
must fail explicitly rather than silently narrowing or changing signedness.
The shared type-signature contract is in [`markdown/SOURCE.md`](../../markdown/SOURCE.md);
focused native tests are in `impl/tests/unsigned_integer_test.cpp`.
## Native C++20 compiler prototype
The top-level /compiler directory provides a separately buildable native C++20 compiler subset with lexer, expression parser, local-name checks, stack-bytecode lowering, interpreter, disassembler, emitter, and tests. It is not feature-equivalent to the production compiler in /impl; read /compiler/README.md before using it. The SLeeLa capability metadata and pipeline-stage contracts are SLNativeCompiler.sleela and SLCompilerPipeline.sleela.
## SLeeLa compiler workbench and native C/C++ output
The SLeeLa-facing developer interface is defined by [COMPILER-DEVELOPER-INTERFACE.md](COMPILER-DEVELOPER-INTERFACE.md). New source units provide:
- `SLCompilerWorkbench.sleela` and `SLCompilerDeveloperCLI.sleela` — runnable-facing orchestration for terminal, IDE, or build integration.
- `SLCompilerBuildRequest.sleela` and `SLCompilerBuildResult.sleela` — explicit build request validation and structured result reporting.
- `SLCompilerNativeBackend.sleela`, `SLNativeSourceEmitter.sleela`, and `SLCompilerToolchain.sleela` — target selection and the verified-IR-to-C/C++ backend contract.
- [Lesson 05](tutorials/05-sleela-compiler-to-c-cpp.md) — developer workflow and native-generation safety rules.
The intended native path is `.sleela compiler source -> validated compiler IR -> C or C++ source -> explicitly selected native toolchain -> native artifact`. The SLeeLa/SLVM route remains the primary VM-oriented path.
**Implementation boundary:** these additions establish the SLeeLa source API and native bridge contract. The native `sleela_compiler_workbench_build` and `sleela_compiler_emit_verified_ir` bridge entry points must be implemented and covered by end-to-end tests before C/C++ source generation can be claimed as operational. Native build authorization defaults to disabled; compilation does not execute the produced program.
## Compiler construction examples
The four-stage learning path for implementing a compiler in SLeeLa source is available under [`examples/`](examples/README.md): **Novice**, **Mid**, **Senior**, and **Very Senior**. Each level includes a SLeeLa scaffold, exercises, validation goals, and appropriate safety/reproducibility guidance. These examples are educational scaffolds and do not imply that full self-hosting or complete language coverage has already been verified.