---
status: canonical
updated: 2026-11-11
---

# 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. **The simplest thing that works.** Prefer what already exists. No new mechanism unless it is needed, and fewer
   parts over more.
8. **One word per thing**, from the [glossary](glossary.md).

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.