5.4 KiB
Slovo Design Notes
Design is how the manifesto survives contact with implementation.
MANIFEST.md explains why Slovo exists.
DESIGN.md explains how Slovo should resist drift.
SPEC-v0.md defines the first tiny version.
1. Design Thesis
Slovo is a typed structural language aimed at systems programming.
Its defining promise is continuity of structure:
source form
↓
parsed tree
↓
checked tree
↓
lowered tree
↓
LLVM IR
↓
machine code
The tree should remain visible across the pipeline.
The written form should not be a disguise.
The written form should be the beginning of the compiler's truth.
2. Design Laws
Law 1: The Tree Is the Language
Source code should map directly to tree structure.
No operator precedence.
No grammar puzzles.
No hidden parse tricks.
Law 2: Canonical Core, Possible Surface
Slovo may eventually have surface conveniences.
But every convenience must lower into one canonical core meaning.
Convenience must not hide meaning.
Law 3: Explicit Beats Implicit
No hidden numeric casts.
No magic imports.
No invisible control flow.
No unmarked unsafe behavior.
Law 4: Lowering Is a Contract
Every feature must explain how it lowers.
A feature is not accepted because it is expressive.
A feature is accepted when its meaning remains visible after lowering.
Law 5: Tooling Is Part of the Language
Parser, formatter, type checker, structured diagnostics, lowering inspector, test runner, and package layout are part of the language promise.
A feature that cannot be formatted, diagnosed, lowered, and tested is not ready.
Law 6: Safety Must Be Precise
Safety claims must be specific.
If Slovo says code is safe, it must define what kind of machine-level danger safe code excludes.
Law 7: Hype Must Not Design the Language
Slovo is LLM-friendly, but not AI-hype-driven.
The goal is durable structure useful to humans, tools, compilers, and machines.
3. Safety Model v0
Safe Slovo code should guarantee:
- values are initialized before use
- nullable absence uses
option - recoverable failure uses
result - casts are explicit
- safe array and slice access is bounds-checked
- raw pointers require
unsafe - allocation and deallocation primitives require
unsafe - unsafe code is lexically visible
- uninitialized memory is not observable from safe code
Safe Slovo does not initially guarantee:
- data-race freedom
- deterministic real-time behavior
- absence of panics/traps
- absence of logic errors
- absence of resource leaks
- full memory safety across FFI
- Rust-like borrow checking
4. Memory Model v0
The recommended v0 memory model:
safe code:
- managed heap values
- no raw pointer operations
- bounds-checked slices
- option/result instead of null/exceptions
unsafe code:
- raw pointers
- explicit allocation APIs
- explicit deallocation APIs
- pointer load/store
- pointer arithmetic, if added, only in unsafe
No concurrency memory model is defined in v0.
Possible v1+ directions:
- arenas
- regions
- ownership
- affine resources
- FFI memory contracts
- layout annotations
- controlled unsafe abstractions
The v0 goal is not to beat Rust.
The v0 goal is to be honest, implementable, and structurally clean.
5. Type-System Restraint
Slovo begins with explicit types and limited inference.
Inference may be allowed only where the expected type is already clear from context.
Initial type families:
primitive:
bool
i8 i16 i32 i64
u8 u16 u32 u64
f32 f64
char
string
unit
never
compound:
(ptr T)
(array T N)
(slice T)
(option T)
(result T E)
Generics should wait until the core is stable.
6. Lowering Discipline
Every feature must have:
- surface syntax
- typed-core representation
- lowering rule
- diagnostic behavior
- formatter behavior
- test examples
A feature without a lowering rule is incomplete.
A feature without diagnostics is incomplete.
A feature without formatting is incomplete.
A feature without tests is incomplete.
7. Diagnostics Contract
Human-readable diagnostic:
Cannot call add with argument 2.
Expected:
i32
Found:
string
At:
(add 3 "hello")
Hint:
Use an integer value or convert explicitly.
Machine-readable diagnostic:
(error
(code TypeMismatch)
(expected i32)
(found string)
(span "main.slo" 12 8 12 15)
(hint "Use an integer value or convert explicitly."))
Diagnostics should include:
- stable error code
- source span
- expected value/type/form
- found value/type/form
- explanation
- possible repair hint when safe
Diagnostics are a tool API, not only user messages.
8. Formatter Contract
The formatter is canonical.
A Slovo implementation that accepts code the formatter cannot canonicalize is incomplete.
The formatter should:
- normalize indentation
- preserve tree structure
- avoid stylistic alternatives
- make nested forms readable
- never change program meaning
Formatting is shared understanding.
9. Feature Admission Checklist
Before adding a feature, ask:
- Does it preserve visible structure?
- Does it lower into typed core?
- Can the formatter canonicalize it?
- Can diagnostics explain it?
- Can tools inspect it?
- Can LLMs generate and repair it reliably?
- Does it keep unsafe behavior explicit?
- Does it avoid hidden machine costs?
- Does it strengthen Slovo's identity?
- Can it wait?
If it can wait, it probably should.