32. Vitte Stdlib Catalog

Level: intermediate · Reading time: 11 min · Prerequisite: book/chapters/31-build-errors.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

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

Concrete Problem

Module chapters often stop at import syntax and never explain ownership boundaries across files and packages.

Red Thread (Single Project)

A tiny application is split into a domain module, a service module, and an entry module.

For what

This chapter helps the reader structure code so that imports reflect ownership instead of accident.

What you are going to do

You will inspect a small module layout, identify public vs local boundaries, then inspect an import misuse.

Coherent example

space demo/modules

use demo/report.{build_summary} as report

proc run() -> int {
  give report.build_summary()
}

entry main at core/app {
  return run()
}

Global explanation

The point of a modules chapter is not the import token itself. The point is ownership: what belongs together, what should stay private, and what the public surface of a module should look like.

Invalid case

proc bad_module() -> int {
  use demo/report
  give 0
}

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

Common pitfalls

• Using module pages as import syntax cheat sheets only.
• Importing too much because boundaries were never designed.
• Putting module-surface declarations inside local blocks.

Short exercise

Split one procedure from the example into another logical module and keep the public boundary explicit.

Summary in 5 points

1. Modules are ownership boundaries.
2. Imports should reveal architecture, not hide it.
3. Public surface and internal detail should be easy to distinguish.
4. Import misuse is a structural error, not style noise.
5. Good module docs connect layout and responsibility.