Vitte

9. Modules and organization (pocket version)

TL;DR (5 lines)

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

Concrete Problem

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

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.

Short exercise

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

Next best action

Keep the example small, reproduce it locally, then continue to the full chapter if you need the broader context.