---
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/0008-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 0008](../../02-DECISIONS/0008-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 0019](../../02-DECISIONS/0019-modules-and-the-graph.md), which settles the principle and deliberately not the list. |