jschoubben
cf9357e8e9
What the mesh is, what it is becoming, and why. Implementation lives in the code repositories; the reasoning lives here. 00-GENESIS mission, engineering context, effect, and the rules that hold 01-RESEARCH investigations, before they harden into design 02-DESIGN the authoritative specification adr numbered decisions — what was chosen, and what was rejected DECISIONS.md the ledger: every decision, in the order it was taken Written for a reader who is not its author and has no access to the mesh it describes. Addresses use the documentation ranges of RFC 5737 and RFC 1918; nodes are named by role. Single initial commit by intent. The prior history came from a private repository and carried operational detail — a routable address identified as a VPN hub, real domain names, a hosting provider — which sanitising a tip commit would not have removed from the log.
43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# How we build
|
|
|
|
Working notes on the rules that hold across the mesh. Short, and each one earned.
|
|
|
|
## Name a context after its aggregate, not after a metaphor
|
|
|
|
`hal/agents` owns **Agent**. A *brain* — memory, thoughts, cognition — is something an
|
|
agent **has**, a concept inside the aggregate. It is not a module.
|
|
|
|
The cost of getting this wrong is visible today: `hal/brain` names the node runtime, so
|
|
the most evocative word in the system points at infrastructure, and `hal/cortex`
|
|
describes itself as "mesh messaging" in its manifest while the anatomy documentation
|
|
calls it the interactive runtime — and it runs on no node at all.
|
|
|
|
Anatomy makes attractive names and poor boundaries. Name the thing the domain calls it.
|
|
|
|
## Ubiquitous language is checked, not assumed
|
|
|
|
If a document states a rule about the mesh, say how the rule is verified. This repository
|
|
has a documented requirement that every module exposing tools declares `brain` as a
|
|
dependency. Zero modules do. An unenforced rule is indistinguishable from a wrong one,
|
|
and costs more, because people believe it.
|
|
|
|
## Contexts integrate through the record, never through a shared schema
|
|
|
|
Publish to the stream; do not join across a boundary. Today five domains share one
|
|
45-table schema, which is why work that belongs to one context keeps having to be
|
|
implemented in another.
|
|
|
|
## A failed step must stop the steps after it
|
|
|
|
Scripted work runs as a sequence, and a sequence that continues past a failure does the
|
|
next thing in the wrong place. Gate each step on the last: `cd X || exit`, not `cd X`
|
|
followed by a newline.
|
|
|
|
Earned the obvious way. A `git worktree add` failed because the branch name collided with
|
|
an existing namespace; the `cd` into that worktree failed too; and the `cp`, `git add` and
|
|
`git commit` that followed ran in the shared checkout and committed to local `main`. The
|
|
error was printed and scrolled past.
|
|
|
|
This is the same shape as the faults this refactor exists to remove — a step reported
|
|
failure, nothing stopped, and the damage happened somewhere nobody was looking.
|