0. Preface

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

TL;DR (5 lines)

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

Frequent mistakes

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.

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.

Work in this chapter

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)
}

proc main(args: list[string]) -> int {
  give 0
}

export *

Complete examples

Each block below is a complete reading unit with its own boundary, data shape, and observable result.

Primary coherent example

This is the compact chapter anchor used by the surrounding explanation.

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)
}

proc main(args: list[string]) -> int {
  give 0
}

export *

Explicit decision boundary

This full block keeps request data, validation, and result shape separate.

space examples/philosophy/decision

form BuildInput {
  name: string
  attempts: int
}

pick BuildStatus {
  case Ready(name: string),
  case Refused(code: int),
}

proc prepare(input: BuildInput) -> BuildStatus {
  if input.name == "" { give BuildStatus.Refused(11) }
  if input.attempts < 0 { give BuildStatus.Refused(12) }
  give BuildStatus.Ready(input.name)
}

proc main(args: list[string]) -> int {
  let input: BuildInput = BuildInput { name: "demo", attempts: 1 }
  let status: BuildStatus = prepare(input)
  give 0
}

export *

Stable failure surface

This example gives every failure a named result instead of a hidden convention.

space examples/philosophy/failure

pick LoadResult {
  case Loaded(size: int),
  case Empty,
  case Invalid(code: int),
}

proc load_size(size: int) -> LoadResult {
  if size < 0 { give LoadResult.Invalid(40) }
  if size == 0 { give LoadResult.Empty }
  give LoadResult.Loaded(size)
}

proc main(args: list[string]) -> int {
  let result: LoadResult = load_size(8)
  give 0
}

Immediate work for this chapter

Show the design rule through a real data shape, not through slogans.
Tie every claim about clarity to a named contract in the example.
Keep failure surfaces explicit before adding broader language values.
Keep the first code block complete and aligned with current Vitte docs syntax.
Keep the invalid block focused on one broken contract only.
Replace generic prose with one concrete rule visible in the code.
Keep every example small enough to review from top to bottom.

Chapter override: 00-preface.html

Dedicated problem

0. Preface needs a concrete production-grade anchor around intent, contract, and observable failure. The page should keep the examples, diagnostics, and review rules tied to that exact boundary instead of drifting back to generic tutorial prose.

Specific complete examples

0. Preface chapter anchor

The primary example is promoted here as the first chapter-specific production reading unit.

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)
}

proc main(args: list[string]) -> int {
  give 0
}

export *

Explicit decision boundary

This full block keeps request data, validation, and result shape separate.

space examples/philosophy/decision

form BuildInput {
  name: string
  attempts: int
}

pick BuildStatus {
  case Ready(name: string),
  case Refused(code: int),
}

proc prepare(input: BuildInput) -> BuildStatus {
  if input.name == "" { give BuildStatus.Refused(11) }
  if input.attempts < 0 { give BuildStatus.Refused(12) }
  give BuildStatus.Ready(input.name)
}

proc main(args: list[string]) -> int {
  let input: BuildInput = BuildInput { name: "demo", attempts: 1 }
  let status: BuildStatus = prepare(input)
  give 0
}

export *

Stable failure surface

This example gives every failure a named result instead of a hidden convention.

space examples/philosophy/failure

pick LoadResult {
  case Loaded(size: int),
  case Empty,
  case Invalid(code: int),
}

proc load_size(size: int) -> LoadResult {
  if size < 0 { give LoadResult.Invalid(40) }
  if size == 0 { give LoadResult.Empty }
  give LoadResult.Loaded(size)
}

proc main(args: list[string]) -> int {
  let result: LoadResult = load_size(8)
  give 0
}

Risks and diagnostics

Risk	Diagnostic signal	Action
Boundary drift	The chapter loses sight of intent, contract, and observable failure.	Restate the boundary beside the first code block and every invalid case.
Generic prose	A paragraph would still be true in another chapter.	Replace it with a code-specific rule from this page.
Weak diagnostic	The failure does not point back to the chapter contract.	Reduce the invalid case until one failure explains the rule.

Review checklist

The first example is complete and aligned with Vitte docs syntax.
The production section names where this construct belongs in real code.
The risk table connects each failure to a diagnostic or review action.
The avoid list rejects broad misuse without adding quiz-like prompts.

Production use

Use this chapter when a code review needs to preserve intent, contract, and observable failure.
Keep examples small enough to copy into fixtures or docs smoke tests.
Treat the invalid case as regression material for future docs checks.

What to avoid

Do not add a second topic that hides the chapter's main contract.
Do not expand examples by adding unrelated subsystems.
Do not rely on prose when a small Vitte block can show the rule.

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

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

Next best action

Extend the coherent example by one small, justified step and keep the same contract visible from input to output.

Chapter deep dive

0. Preface sets the design lens before syntax becomes the main topic. The chapter is written for a reader deciding what kind of code Vitte is trying to reward.

The practical boundary is: intent, contract, and observable failure. Keep that boundary in view while reading the example, the invalid case, and the exercise.

Role in the learning path

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.

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

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

Profile-specific deep dive

Design lens

The chapter should show explicitness, contracts, and failure surfaces in code.
Readable structure is demonstrated by named data and results.
Language values become useful only when they change review behavior.

Practical rule

Avoid prose-only principles.
Tie every principle to a small executable shape.
Keep failure handling as part of the design story.

Reading the valid example

space demo/philosophy: names the ownership boundary before any behavior appears.
form BuildRequest {: introduces a data contract that later branches can rely on.
name: string: supports the chapter contract without adding hidden behavior.
retries: int: supports the chapter contract without adding hidden behavior.
}: supports the chapter contract without adding hidden behavior.
pick Decision {: makes possible outcomes explicit instead of encoding them as magic values.
case Accepted(name: string),: names one outcome that callers must be ready to handle.
case Rejected(code: int),: names one outcome that callers must be ready to handle.
}: supports the chapter contract without adding hidden behavior.
proc decide(req: BuildRequest) -> Decision {: states the callable contract: inputs first, result shape last.
if req.name == "" { give Decision.Rejected(11) }: guards a failure or edge case before the nominal result.
if req.retries < 0 { give Decision.Rejected(12) }: guards a failure or edge case before the nominal result.
give Decision.Accepted(req.name): ends the local path with an explicit result.
}: supports the chapter contract without adding hidden behavior.
proc main(args: list[string]) -> int {: states the callable contract: inputs first, result shape last.
give 0: ends the local path with an explicit result.
}: supports the chapter contract without adding hidden behavior.
export *: supports the chapter contract without adding hidden behavior.

Lesson from the invalid example

proc vague(x: int) -> int {: this line helps isolate the failure because it states the callable contract: inputs first, result shape last.
if x { give 1 }: this line helps isolate the failure because it guards a failure or edge case before the nominal result.
give 0: this line helps isolate the failure because it ends the local path with an explicit result.
}: this line helps isolate the failure because it supports the chapter contract without adding hidden behavior.

Engineering decisions to preserve

Name the boundary before changing code: Vitte favors explicit contracts over implicit convention.
Keep the smallest example executable: A philosophy chapter still needs code, not only prose.
Make the invalid path explain one failure only: The smallest useful example already separates domain and transport.
Prefer a visible contract over an implied convention: Invalid paths are part of the design contract.
Leave a review anchor that another maintainer can verify: Readable structure is a technical property, not decoration.

Context-specific review criteria

The page makes the intent, contract, and observable failure boundary visible before the first code block.
The intended reader, a reader deciding what kind of code Vitte is trying to reward, can follow the valid example through named contracts instead of memorized tokens.
The invalid example fails for the same reason the prose discusses.
The exercise extends the same contract instead of introducing an unrelated concept.
The next chapter can reuse the vocabulary introduced here without redefining it.
The chapter stays specific enough that its title materially changes the meaning of the page.
Every warning connects to a concrete code shape.
The summary leaves one durable engineering rule behind.

Contract matrix

Concern	Chapter rule	Evidence to keep
Ownership	Code belongs behind the boundary named by the chapter.	The chapter keeps ownership visible through intent, contract, and observable failure.
Input contract	The procedure receives a shape that is named before branching.	The valid example names the accepted shape before branching.
Nominal path	The clean path remains readable without hidden state.	The successful result can be found without reading hidden state.
Failure path	The invalid case isolates one failure reason.	The broken example has one main reason to fail.
Naming	Names explain the domain rather than only the mechanism.	Names remain tied to the chapter goal.
Types	Types remove ambiguity from values and results.	Fields and return values carry domain meaning.
Control flow	Branches stay traceable from guard to result.	Guards appear before the result they protect.
Module boundary	The public surface stays smaller than implementation detail.	The public surface remains smaller than the implementation detail.
Diagnostic value	The failure path points back to the exact contract.	The invalid example points back to the exact contract.
Test value	Regression evidence covers one passing path and one failing path.	One passing case and one failing case cover the lesson.
Refactor value	Implementation cleanup preserves the result shape.	The result shape stays stable during local cleanup.
Publication value	The chapter leaves one concrete engineering rule.	The chapter leaves one concrete engineering rule.

Rewrite path for this chapter

Rewrite the opening paragraph so it names intent, contract, and observable failure before naming syntax.
Keep the valid example small enough that the full contract fits on screen.
Move any broad claim back to a specific line in the example.
Preserve one invalid case that fails for the chapter's main reason.
Add one sentence explaining why the invalid case is not a random error.
Make every pitfall actionable by naming the code shape it damages.
Keep the exercise inside the same domain as the example.
Avoid introducing a second unrelated project just to show variety.
Use the summary to restate the chapter rule, not the table of contents.
Check that the next chapter can build on this vocabulary.
Remove any sentence that would still be true in every other chapter.
Keep the last action small, local, and testable.

Diagnostic anchors

The first inspected line is the one that declares the chapter's main contract.
The central type, field, procedure, or branch carries the chapter's main idea.
The invalid example includes a sentence-level explanation of its failure.
Refactors preserve the detail that would otherwise mislead a future reader.
The behavior that must stay stable is named before implementation changes begin.
Vague names are replaced before they become review friction.
Regression coverage protects the chapter's main contract.
Implementation details stay out of public API unless the chapter explicitly teaches that surface.
Beginner-facing diagnostics point to the contract, not to a random syntax detail.
The next chapter can assume one clearly named concept from this page.

When extending this chapter

Extend toward a reader deciding what kind of code Vitte is trying to reward, not toward a broader catalog of features.
Add a second example only if it sharpens the same contract.
Prefer a small variant over a new subsystem.
Keep prose close to code; every abstract claim should point to a visible shape.
Do not hide a new concept in the exercise.
If a paragraph explains policy, add the concrete code boundary it protects.
If a paragraph explains syntax, add the semantic reason the syntax matters.
If a paragraph explains architecture, identify the owner of each boundary.
If a paragraph explains failure, keep the failing line close to the explanation.
Stop expanding when the chapter has one complete, testable lesson.

Failure modes to avoid

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.

Practice scenario

Start from the coherent example in 0. Preface. Change one identifier, one guard, and one returned value. After each change, write down whether the public contract is still the same contract or a new one.

If the contract changed, update the type or result shape first. If only the implementation changed, keep the external name stable and add one regression note explaining what should not change again.

Before moving on

You can state the chapter role: sets the design lens before syntax becomes the main topic.
You can point to the main boundary: intent, contract, and observable failure.
You can connect the invalid case to the problem statement: 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.
You can perform the 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.