novox/hq
3
0
Fork 0
Code Issues 5 Pull Requests 5 Releases Wiki Activity

Document the whole module surface, and keep it true with a test

Browse Source 
A reference table goes stale the day somebody adds a field, so this one points at
mesh-catalog/modules/showcase — a module that uses all of it — and a test that
fails when it stops doing so. Read the module when the table disagrees with it.

Two rows in the coverage survey were stale because of this week's work: systemd
units were a file plus a service, which made every author write unit syntax and
is why "process" exists; and building from source was images only, where a
bundle now names a language and lets the mesh choose the toolchain.

And the two rows at the bottom of the resource table are the interesting ones.
"action" is refused to modules outright — the link may not carry a command, so a
module needing something done ships a program that reconciles. "service"
installs no unit by design, right for software shipping one and wrong for code
the mesh built, which has none until the mesh writes it.

Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
jschoubben
2026-09-15 13:06:16 +02:00
parent 8a7328c282
commit 411f0680b8
3 changed files with 81 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/12-a-module-repository.md
+7
View File
@@ -225,9 +225,16 @@ answered to the asker and kept nowhere.
| kind | is |
|---|---|
| **image** | built from a Dockerfile in this repository |
| **bundle** | this module's own code, compiled by the toolchain its language implies, then packed |
| **archive** | a directory in this repository, packed |
| **upstream** | an image somebody else built, mirrored into the mesh's own registry |
**The second was added later and is why most modules now need no Dockerfile.** An archive packs a
directory as it stands, so shipping compiled output meant compiling somewhere first — and that
meant every module repeating a recipe that is easy to get wrong in ways that fail elsewhere. The
whole surface a module has, and a module that exercises all of it, are in
[`18-building-a-module`](18-building-a-module.md).
**The third exists because a module usually runs software it did not write.** A database module
ships configuration and a provisioner and does not build a database. Naming the upstream reference
directly would need every machine to reach a public registry, and would pin to a tag its owner can