0. Preface

Level: beginner · Reading time: 15 min · Prerequisite: book/chapters/00-foreword.html · Track: essential · Maturity: reviewed · Last review: 2026-05-09

Prerequisites: book/chapters/00-foreword.html. See also: book/chapters/00-foreword.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Readers often learn syntax before learning the design contract of the language. That creates code that compiles but is hard to maintain, review, or debug.

Red Thread (Single Project)

One tiny service module evolves from a vague script into a deliberate Vitte design with explicit contracts, stable names, and visible failure boundaries.

For what

This chapter helps the reader understand what Vitte optimizes for before touching advanced syntax.

What you are going to do

You will read one small module, identify the design choices that make it readable, then compare that with a weaker variant.

Coherent example

space demo/philosophy

form BuildRequest {
  name: string
  retries: int
}

pick Decision {
  case Accepted(name: string)
  case Rejected(code: int)
}

proc decide(req: BuildRequest) -> Decision {
  if req.name == "" { give Decision.Rejected(11) }
  if req.retries < 0 { give Decision.Rejected(12) }
  give Decision.Accepted(req.name)
}

entry main at core/app {
  return 0
}

Global explanation

The chapter is not about one token. It is about explicit contracts, clear boundaries, and stable failure surfaces. The example is small, but it already separates domain data, decision logic, and process entry.

Invalid case

proc vague(x: int) -> int {
  if x { give 1 }
  give 0
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Talking about beauty or simplicity without showing a concrete contract boundary.
• Using philosophy chapters as prose-only pages with no executable anchor.
• Describing intent without showing what the compiler can actually enforce.

Short exercise

Take one vague helper in your own code and rewrite it so that the domain input, the branch conditions, and the result boundary are explicit.

Summary in 5 points

1. Vitte favors explicit contracts over implicit convention.
2. A philosophy chapter still needs code, not only prose.
3. The smallest useful example already separates domain and transport.
4. Invalid paths are part of the design contract.
5. Readable structure is a technical property, not decoration.