Files
hq/00-META/principles.md
T

2.4 KiB

status, updated
status updated
canonical 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.
  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.

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.