17. Stdlib

Level: beginner · Reading time: 13 min · Prerequisite: book/chapters/16a-vitte-binding.html · Track: essential · Maturity: reviewed · Last review: 2026-05-09

Prerequisites: book/chapters/16a-vitte-binding.html. See also: book/chapters/16a-vitte-binding.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Readers often see stdlib pages as catalogs with no architectural guidance, so they cannot place new code correctly.

Red Thread (Single Project)

One small application flow uses pure helpers, path normalization, and summary rendering while naming which library family owns each concern.

For what

This chapter helps the reader classify library work by family and responsibility.

What you are going to do

You will inspect one complete flow, then map its responsibilities to stdlib families and compare it to an invalid domain variant.

Coherent example

space demo/stdlib

form Manifest {
  name: string
  root_path: string
  targets: int
}

pick Plan {
  case Ready(summary: string)
  case Invalid(code: int)
}

proc normalize_root(root_path: string) -> string {
  if root_path == "" { give "." }
  give root_path
}

proc validate_manifest(m: Manifest) -> Plan {
  if m.name == "" { give Plan.Invalid(11) }
  if m.targets <= 0 { give Plan.Invalid(12) }
  give Plan.Ready(m.name)
}

Global explanation

The stdlib should be taught by ownership. Core helpers, collections, data transforms, path and I/O boundaries, JSON, concurrency, and runtime-facing families all solve different problems. The chapter is useful only if the reader can classify future code with it.

Invalid case

entry main at core/app {
  let manifest: Manifest = Manifest("", "", 0)
  return 0
}

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

Common pitfalls

• Listing module names without explaining responsibility.
• Reducing stdlib docs to hello-world snippets.
• Mixing host interaction and pure domain logic in one explanation.

Short exercise

Take the example and say which future step would belong to `json`, which to `io`, and which should remain in pure domain code.

Summary in 5 points

1. Stdlib families exist to separate responsibilities.
2. A complete scenario teaches more than a flat catalog.
3. Validation and transport should stay apart.
4. Family boundaries matter in docs as much as in code.
5. The chapter should scale to the whole library tree.