jschoubben
77f3a4cea7
Every remaining cluster merged. Each was one design that had been split across
several records because it was worked out over days rather than at once.
the node host 8 -> 1 applies not decides, depends on nothing,
per operating system, root service, the
launcher, episodic, what a declaration is,
actions from the bundle only
a node and how it joins 4 -> 1 what a node is, joining, the link as
security boundary, the enrolment token
modules and the graph 7 -> 1 everything is a module, no domain modules,
three edges, provisioning, the core library
substrate and control 6 -> 1 the test, seven contexts, one control plane,
plane the authority is not a database, the named
products, the pinned bundle
connectivity 3 -> 1 a route is a grant, reachability declared,
filter rules
delivery 5 -> 1 reconciliation not a pipeline, artifacts,
the three silos, a failed step, the verdict
the lab 5 -> 1 (earlier)
how this repository 10 -> 1 (earlier)
works
Nothing was dropped. Each consolidated record carries the reasoning of the ones
it absorbs -- the measurements, the incidents, the alternatives rejected --
because that reasoning is the only reason to keep a record at all. What is gone
is the fragmentation: eight files to read to understand tier 0, when tier 0 is
one component.
The four superseded records went too. They existed to point at their
successors, and the successors now contain what they said.
The checker made this safe. Each merge left dangling links -- 38 files after
the host merge alone -- and it named every one. Nothing was found by reading,
and a manual pass would certainly have missed some, including references inside
AGENTS.md which every session loads.
68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
---
|
|
status: active
|
|
initiated: 2026-08-22
|
|
touches: [03-DESIGN/00-as-is/02-modules-and-manifests.md, 03-DESIGN/00-as-is/10-module-catalogue.md, 03-DESIGN/01-to-be/00-work-breakdown.md]
|
|
became: [02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md]
|
|
---
|
|
|
|
# 001 — Module domain decomposition
|
|
|
|
- **Initiated by:** jochen, 2026-08-22
|
|
- **Areas touched:** every `hal/*` and `noxflow/*` module; the pipeline's dependency
|
|
graph; the knowledge base; agent identity and credentials.
|
|
|
|
## Summary
|
|
|
|
HAL has 124 modules. That number is not a maintenance problem in itself — it is the
|
|
**symptom of missing bounded contexts**. Modules are split not because they model
|
|
different domains, but because splitting is the only lever the platform offers:
|
|
|
|
- no way to run one daemon on one node without making it a module
|
|
(`hal/claude-licences` — one daemon, single-node)
|
|
- no way to expose two of a kind from one module
|
|
- no namespace separating the mesh from the software it runs
|
|
|
|
This effort establishes the **current state**, the **ideal state**, and the sequence
|
|
between them.
|
|
|
|
## Trigger
|
|
|
|
A night of debugging that produced four fixes and one conclusion. Every fault was a
|
|
boundary fault:
|
|
|
|
- Per-agent Claude credentials had to be written by the *noxflow runtime*, because
|
|
`agents.claude_account` is in noxflow's database — even though agent identity is a
|
|
mesh concept and node identity already lives in the mesh registry.
|
|
- Whether `hal/brain` may depend on noxflow took three attempts to answer, twice
|
|
wrongly, because the ownership boundary was never stated.
|
|
- Authoritative documentation existed in `mesh_docs` and was not found, while a
|
|
proposal in repo markdown was invisible to search entirely.
|
|
|
|
## Decisions taken (2026-08-22)
|
|
|
|
| Question | Decision |
|
|
|---|---|
|
|
| What should noxflow become? | Decompose into `hal/*` modules; noxflow returns to tasks/workflows |
|
|
| Who owns agent identity? | `hal/agents` — a mesh concept, alongside nodes |
|
|
| Where do third-party apps live? | Out of this repo. They run *on* the mesh; they are not *of* it |
|
|
| Knowledge structure | Modelled on `papa-hq`; implementation choice left open |
|
|
|
|
## Open questions
|
|
|
|
Tracked in [`analysis.md`](analysis.md) under "Open questions".
|
|
|
|
## Deliberately not decided
|
|
|
|
Recorded so they are not mistaken for oversights. Each is open, and each comes out of
|
|
[ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md); this effort stays
|
|
`active` until they are answered.
|
|
|
|
| Question | Status |
|
|
|---|---|
|
|
| `hal/scheduler` — infrastructure, or part of the work context. | Open. |
|
|
| Which context owns the executor. | Open. |
|
|
| Catalogue destination — one repository or many. | Open. Phase 4. |
|
|
| What the shared library keeps after extraction. | Open. Phase 3. |
|
|
| Where human agent modality is recorded — which user, on which node, a human agent acts as. | Open. Required by the model; not yet stored. |
|
|
| Which domains the modules outside the platform core group into. | Open, from [ADR 0044](../../02-DECISIONS/0044-modules-and-the-graph.md), which settles the principle and deliberately not the list. |
|