slovo/docs/language/DESIGN.md

# 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:

```text
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:

```text
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:

```text
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:

1. surface syntax
2. typed-core representation
3. lowering rule
4. diagnostic behavior
5. formatter behavior
6. 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:

```text
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:

```slo
(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:

1. Does it preserve visible structure?
2. Does it lower into typed core?
3. Can the formatter canonicalize it?
4. Can diagnostics explain it?
5. Can tools inspect it?
6. Can LLMs generate and repair it reliably?
7. Does it keep unsafe behavior explicit?
8. Does it avoid hidden machine costs?
9. Does it strengthen Slovo's identity?
10. Can it wait?

If it can wait, it probably should.