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.
78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
# HAL — HQ
|
|
|
|
The single source of truth for what the HAL mesh **is**, what it is **becoming**, and
|
|
why. Implementation lives in `modules/`; the reasoning behind it lives here.
|
|
|
|
## Structure
|
|
|
|
| Folder | Purpose |
|
|
|--------|---------|
|
|
| [`00-GENESIS`](00-GENESIS/) | Mission and foundational context. The northern star for every decision. |
|
|
| [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. |
|
|
| [`02-DESIGN`](02-DESIGN/) | The authoritative specification. Implementation is built against this. |
|
|
| [`adr`](adr/) | Numbered architecture decisions — what was chosen, and what was rejected. |
|
|
|
|
## Rules
|
|
|
|
- Markdown only.
|
|
- No new top-level folders without explicit confirmation.
|
|
- Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only
|
|
after analysis against GENESIS confirms alignment.
|
|
- **GENESIS and DESIGN are instance-agnostic.** They describe the mesh as a concept — no
|
|
machine names, no counts, no topology. A reader must not be able to tell how many nodes
|
|
the author happened to have.
|
|
- **RESEARCH describes real observations, but never identifies the mesh it observed.**
|
|
Evidence is what makes research worth reading, and the shape of a finding survives
|
|
anonymisation intact — *a node publicly named but behind a household NAT* carries the whole
|
|
lesson without naming anything.
|
|
- A document that states a rule about the mesh should say how that rule is **checked**.
|
|
This repo has a rule requiring every tools module to declare `brain` as a dependency;
|
|
zero modules do. An unenforced rule is indistinguishable from a wrong one.
|
|
|
|
### This repository is public
|
|
|
|
Written for a reader who is not its author and has no access to the mesh it describes.
|
|
Concretely, nothing here may contain:
|
|
|
|
- **routable addresses, real domain names, hosting providers, or node names** — use the
|
|
documentation ranges (RFC 5737 `203.0.113.0/24`, RFC 1918) and role names such as `anchor`,
|
|
`home-server`, `workstation`, `laptop`
|
|
- **absolute paths** from anyone's machine, usernames, home directories, or email addresses
|
|
- **credentials in any form**, including lengths or hashes of live secrets
|
|
- **operational detail that is only useful to an attacker** — which host is the VPN hub, on
|
|
which port, which node is reachable only through a forwarded port
|
|
|
|
Private-range addresses and the overlay plan are fine: they describe a pattern, not a target.
|
|
|
|
The test is whether a paragraph would still teach something to a stranger running an entirely
|
|
different mesh. If it would, it belongs. If it only makes sense to someone who knows this
|
|
particular installation, it is either a note in the wrong place or a disclosure.
|
|
|
|
## Why this is its own repository
|
|
|
|
It began inside the code repository, on the reasoning that HAL already has a mesh-native
|
|
knowledge store and that adding a fourth knowledge system would repeat the mistake this
|
|
folder was created to fix.
|
|
|
|
**That objection was about a fourth knowledge *system*, and it is answered by indexing, not
|
|
by location.** These documents are still indexed into the knowledge base, so
|
|
`recall_search` returns them beside everything else. One source, many surfaces — which was
|
|
always the actual requirement. Where the source is authored is a separate question.
|
|
|
|
Answered separately, a repository of its own is the better home:
|
|
|
|
- **The cadence is different.** A decision changes when thinking changes, not when code
|
|
changes. Tying documents to a code branch means they merge on the code's schedule.
|
|
- **The reviewers are different.** A design argument is not reviewed the way an
|
|
implementation is, and it should not queue behind a build.
|
|
- **The scope is wider than one repository.** ADR 0001 sends most modules out of the
|
|
monorepo entirely. Documentation that governs several repositories cannot live inside one
|
|
of them.
|
|
|
|
The trade is real and worth naming: a change to a document and the change to the code it
|
|
describes can no longer land in one commit. Keeping them honest is a discipline now rather
|
|
than a mechanism — which is why [`DECISIONS.md`](DECISIONS.md) records decisions as they are
|
|
taken, and why a document that states a rule should say how the rule is checked.
|
|
|
|
Recorded as decision 27 in [`DECISIONS.md`](DECISIONS.md).
|