jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
|
|
- 02-DECISIONS/0002-everything-is-a-module.md
|
|
- 02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md
|
|
---
|
|
|
|
# The mesh as it stands
|
|
|
|
A set of machines, each running the same runtime, each loading only the parts of the catalogue
|
|
it has been assigned. They hold no shared filesystem and make no direct connections to one
|
|
another. What makes them a mesh is a database that knows what should run where, and a message
|
|
broker that carries everything between them.
|
|
|
|
## Three nouns
|
|
|
|
**A node** is a machine that runs the runtime. Nodes differ in what they are assigned and in
|
|
what they can reach — some carry a public name, some sit behind a household connection with no
|
|
inbound route at all — and the mesh is designed so that difference stays a property rather than
|
|
becoming a special case. A node holds no authoritative state: everything it needs is derived
|
|
onto it and can be regenerated.
|
|
|
|
**A module** is a directory with a manifest, and it is the only unit the mesh installs. A
|
|
containerised service is a module. A set of capabilities with no service behind them is a
|
|
module. A bare marker whose whole content is that a node has it is a module. The mesh's own
|
|
components are modules on exactly the same terms as everything else it carries
|
|
([ADR 0002](../../02-DECISIONS/0002-everything-is-a-module.md)).
|
|
|
|
**An agent** is a participant. Some agents are human. What differs is modality — how the agent
|
|
acts — and not category: both hold identity, both act, both accumulate memory
|
|
([ADR 0012](../../02-DECISIONS/0012-agents-are-persistent-employees.md)).
|
|
|
|
## Where truth lives
|
|
|
|
The repository defines **what exists**: the modules, what each declares, how each is built.
|
|
|
|
The mesh database defines **what runs where**: which node is assigned which module, at which
|
|
selection, with which overrides, plus the settings every node reads. No node-to-module mapping
|
|
is ever committed ([ADR 0003](../../02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md)).
|
|
|
|
Everything on a node's disk is **derived** from those two, and is regenerated rather than
|
|
edited ([ADR 0004](../../02-DECISIONS/0004-managed-files-are-generated-never-edited.md)). A node that
|
|
loses its database keeps running from a local cache, which is deliberate and has the obvious
|
|
cost: the cache carries no indication of its own age.
|
|
|
|
## How anything moves
|
|
|
|
Nothing dials a node. Every node dials the broker outbound, owns an exchange named for itself,
|
|
and consumes from its own request queue
|
|
([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md)). Three message shapes carry
|
|
everything: requests expecting a reply, commands instructing that a stage of work be done, and
|
|
events stating that something happened.
|
|
|
|
A capability that lives on another node is reached the same way a local one is. At startup a
|
|
node asks its peers what they host and creates a local stand-in for each remote capability, so
|
|
the caller does not know or care where the work happens. Credentials never travel: the call
|
|
goes to where the capability is.
|
|
|
|
## How change reaches a node
|
|
|
|
A push to the forge is the only trigger. What follows is three silos with deliberately
|
|
different cardinality: compile once, package and upload once, then install-configure-start-
|
|
verify **on every assigned node**
|
|
([ADR 0014](../../02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md)). What travels between
|
|
build and node is a self-contained build output, so a deploy is extract-and-run and touches no
|
|
network ([ADR 0013](../../02-DECISIONS/0013-an-artifact-is-build-output.md)).
|
|
|
|
Modules are resolved into dependency levels and a level completes before the next begins, so a
|
|
module always builds against its dependencies as they were just published.
|
|
|
|
## What the mesh does for a module
|
|
|
|
A module declares what it **provides** and what it **requires**. The mesh satisfies the
|
|
requirement: it creates the resource, generates the credential, records the grant, and writes
|
|
the values where the module will read them. The module never learns which node its database
|
|
lives on, and nobody ever writes a credential by hand
|
|
([ADR 0005](../../02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md)).
|
|
|
|
This is the property the mesh's whole shape rests on, and it is why provisioning is treated as
|
|
a core concern rather than as plumbing.
|
|
|
|
## The shape of its failures
|
|
|
|
Worth stating in an overview, because it is the most consistent thing about the system: the
|
|
mesh's expensive faults are almost never crashes. They are operations that reported success
|
|
and did nothing — a download that half-completed, a hook that was never called because it was
|
|
named for a feature the module does not declare, a stage that reported it had dispatched a
|
|
message rather than that the effect happened, a package that 404ed from every mirror while the
|
|
job went green.
|
|
|
|
[ADR 0008](../../02-DECISIONS/0008-a-failed-step-fails-the-job.md) is the response, and it is applied
|
|
instance by instance rather than enforced by a mechanism. New instances are still being found.
|
|
That is an as-is fact, not a criticism: it is the single most useful thing to know about this
|
|
system before changing it.
|