Principles: no part without a need (7); depend on the contract, at the level it is interchangeable (9) #616

Merged
mesh-tools merged 1 commits from principles/contract-and-no-part-without-need into main 2026-11-16 09:06:34 +00:00
2 changed files with 12 additions and 8 deletions
+6 -3
View File
@@ -1,6 +1,6 @@
---
status: canonical
updated: 2026-11-11
updated: 2026-11-16
---
# The principles
@@ -22,9 +22,12 @@ add, sharpen or drop a principle in a pull request to this file.
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.
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.
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.
@@ -53,11 +53,12 @@ deals with it, which is how the list is kept true.
11. **Silent waits met during G's start:** the indexer's first versions fill returns without a word while another fill
runs, so a hung fill held every later one silently for two hours; `grants_membership` and `grants_assert` time out
after 30 seconds with no log line; the tool runner says a dropped event once per key.
12. **The module graph's edges are dependencies, never verbs or bus subjects** (2026-11-16): a manifest says what its
module depends on, a seat whenever one exists and otherwise a module (a build dependency on a package module, a
program needing another module), and the graph's edges come from that alone. The verb edges of ADR 0614 §2 and §3,
and the cycle exceptions they needed (A-361, A-428, A-437), go; whether `invokes`, `uses` and the `views` forms stay
in a manifest at all is asked with the research on the mesh's accounts, and "each fact is declared in one place".
12. **The module graph's edges are dependencies, never verbs or bus subjects** (2026-11-16; principle 9): a manifest
says what its module depends on, a seat where the need is meant to be interchangeable and otherwise a module (a
build dependency on a package module, a program needing another module), and the graph's edges come from that
alone. The verb edges of ADR 0614 §2 and §3, and the cycle exceptions they needed (A-361, A-428, A-437), go; whether
`invokes`, `uses` and the `views` forms stay in a manifest at all is asked with the research on the mesh's
accounts, and "each fact is declared in one place".
## Met during G's start (2026-11-14)