--- status: canonical updated: 2026-11-16 --- # The principles A short, living list. Every question met while building is tested against these principles and answered by the lead in one line; only a question no principle settles goes to the operator or to a decision record. A detail that a principle settles is not written down as a design line or a record. The list changes when the operator says so: add, sharpen or drop a principle in a pull request to this file. 1. **NATS-native.** Every interaction between modules is an event, or a call over the bus where an answer is needed. A module keeps its data in the bus's own storage, and reads another module's data only by asking it, through its verbs or its tools. 2. **The mesh owns the truth.** State lives in the mesh and is written onto the nodes from there. Nothing is changed by hand on a node. 3. **Failure is loud.** Nothing reports success when it did nothing, and nothing fails silently. When in doubt, fail. 4. **A module is steered by its tools.** Everything a module holds can be read, everything it does can be started by hand, and everything that goes wrong can be recovered, all through its tools. 5. **Everything ships the same way.** The mesh's own parts go through the same build, check and delivery as any app. 6. **Nothing is exposed publicly.** No data leaves the mesh unasked: no secret in a record, a log or a public repository, no service reachable from outside unless it is meant to be. Inside the mesh, every agent and module is trusted; who may do what is not a question to ask. 7. **No part without a need.** Every mechanism, field, seat and step exists because something needs it; prefer what exists over a new one, and remove what no longer serves. Never a shortcut instead of the right shape. 8. **One word per thing**, from the [glossary](glossary.md). 9. **Depend on the contract, at the level it is interchangeable.** A module depends on a seat where the mesh means more than one module to be able to fill the need, and on a module where only that module does; never on another module's internals. 10. **The module is the unit.** Everything is done per module, never per repository. A repository is only where a module's files are kept; a merge moves only the modules it changes. 11. **Configurable, never hard-coded.** A value that can differ between machines, modules or over time (a port, a path, a bound, a cap, a name, a time) is a setting with a default, never written into the code. 12. **A module writes only its own.** A module writes its own files and state alone; what another module needs from it goes through a provision or a contribution that module declares, never a file written in its place. How it is checked: the one code review of a milestone checks the code against these principles and the design's shape; an answer to a develop question names the principle that settles it.