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.
91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- 02-DECISIONS/0002-everything-is-a-module.md
|
|
- 02-DECISIONS/0010-applications-live-in-their-own-repository.md
|
|
- 02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md
|
|
---
|
|
|
|
# The catalogue, and what its shape says
|
|
|
|
The catalogue holds **124 modules**. Thirty-three belong to the mesh's own domain; the other
|
|
ninety-one run *on* the mesh rather than being *of* it
|
|
([ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md)).
|
|
|
|
The count is not the finding. The **shape** is.
|
|
|
|
## How it is organised today
|
|
|
|
By namespace, and the namespace records origin rather than purpose:
|
|
|
|
- **The mesh's own namespace** holds the platform: the runtime and its daemons, the shared
|
|
library, delivery, provisioning, configuration synchronisation, knowledge, identity, the
|
|
board, developer tooling, and node presentation.
|
|
- **A second namespace** holds the work domain — tasks, workflows, agents, meetings — split
|
|
across a handful of packages that share one schema.
|
|
- **Everything else sits flat at the top level**, one directory per piece of software.
|
|
|
|
## What the flat level actually contains
|
|
|
|
Grouped by what they are *for* — a grouping the catalogue itself does not express:
|
|
|
|
| Purpose | Roughly |
|
|
|---|---|
|
|
| Data and storage services the mesh provisions against | Relational and document databases, a cache, an object store, a package registry, a time-series store |
|
|
| Messaging and identity | A message broker, an identity provider |
|
|
| Reachability | A VPN, a firewall, an intrusion filter, an SSH daemon, a resolver, a certificate authority, a reverse proxy, network equipment control |
|
|
| Forge and container plumbing | Forge integrations, an image registry, container lifecycle and retention |
|
|
| Media libraries | Acquisition, organisation, playback, transcoding, streaming |
|
|
| Workstation and desktop | Browser, file manager, monitors, session management, audio, package management, runtime managers |
|
|
| Hardware-specific support | Power and firmware control for particular hardware, filesystem management |
|
|
| Collaboration and productivity | File sync, office tooling, boards, automation, chat and messaging bridges, mail, analytics, dashboards, home automation, issue trackers and wikis |
|
|
| Third-party organisation integrations | Systems belonging to organisations outside the mesh |
|
|
|
|
Every row is several modules, and **no row is a thing the mesh can see**. Four modules
|
|
together constitute "how a node is reachable", and they have no relationship the mesh can
|
|
assign, version, reason about or replace as one unit. A change to how the mesh handles
|
|
connectivity is made four times.
|
|
|
|
## What the shape records
|
|
|
|
**The catalogue's shape records what was installed, not what anything is for.** One module is
|
|
the unit of one piece of software, because that is the only granularity the module system
|
|
offers.
|
|
|
|
This is the same failure [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md)
|
|
names for the platform core — *boundaries drawn by deployment accident rather than by domain* —
|
|
appearing outside it, at four times the scale. The core is being recomposed; the flat level is
|
|
addressed in principle by
|
|
[ADR 0017](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md), which
|
|
deliberately does not yet settle the domain list.
|
|
|
|
## Two properties worth keeping
|
|
|
|
Whatever replaces the shape, two things about it are right.
|
|
|
|
**Uniformity.** A media server and the mesh's own coordinator are installed, provisioned,
|
|
delivered and verified by identical machinery. The mesh's own components hold no privilege —
|
|
which is what makes dogfooding structural rather than a discipline, and what makes moving a
|
|
module out of the repository safe.
|
|
|
|
**Placement is already decided.** A standalone application belongs in its own repository
|
|
([ADR 0010](../../02-DECISIONS/0010-applications-live-in-their-own-repository.md)), and reviewers reject
|
|
it in the monorepo. The catalogue's flat level is not a dumping ground by policy; it is one by
|
|
history.
|
|
|
|
## Known inconsistencies in the catalogue itself
|
|
|
|
Recorded because a reader will meet them:
|
|
|
|
- A documented requirement that every capability-exposing module declare the core runtime as a
|
|
dependency is met by **zero** modules.
|
|
- A firewall-scoping key is declared by five manifests and read by none
|
|
([`04-ISSUES/003`](../../04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md)).
|
|
- A connections block in the manifest is metadata: it describes a module's reachability and
|
|
wires nothing.
|
|
- At least one module deliberately runs outside the standard per-module supervision, for
|
|
reasons recorded in the operational memory. The standard path is not universal.
|