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.
2.0 KiB
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.