novox/hq
3
0
Fork 0
Code Issues Pull Requests 2 Releases Wiki Activity

Base layer: the mesh as it is, under the mesh as it should be

Browse Source 
HQ held only the to-be. Every reader had to already know the system the
decisions were about, and an as-is claim had nowhere to live except inside
an intention.

Adds 02-DESIGN/00-as-is — eleven documents written from the implementation
and the operational record, not from intent, including the parts nobody
would choose again. The two existing designs move under 01-to-be. Layers
are declared in frontmatter and never mix: a design that ships does not
move, its as-is counterpart is written, and both stand.

Back-fills adr/0001-0014 for decisions taken in implementation and never
recorded — the broker, the module abstraction, the mesh database, managed
files, provisioning, migrations, the workspace removal, failing loudly,
the constitution, application placement, linking, the employee model, the
artifact, the three silos. Each marked reconstructed, dated from the
history, and citing the evidence it was recovered from. The two existing
records renumber to 0015 and 0016 so the ledger runs oldest first;
0017 extends 0015 to modules outside the core, principle only — the
domain list is deliberately not invented here.

how-we-build.md becomes the source of the mesh constitution, with a sync
playbook, so the enforced copy stops being the only one that is true.

Process becomes explicit: five playbooks, eight thin skills that defer to
them, a repository map, and AGENTS.md with CLAUDE.md as its include.

The five Observations become 04-ISSUES 001-005 where they can be owned and
closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge
base. That claim is what decision 27 rests on, it was never checked, and
the README now says so instead of repeating it.

Also corrects the ADR index into something generated, the "02-DESIGN is
empty" claim, the VISION.md pointer that did not survive the repo split,
and a note asserting the symlink rule was contradicted — it was a
misreading; the rule forbids hand-made links, the installer links by design.
This commit is contained in:
jschoubben
2026-08-23 03:08:26 +02:00
parent cf9357e8e9
commit 702efca6bb
74 changed files with 3676 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/hal-amend-design/SKILL.md
+46
View File
@@ -0,0 +1,46 @@
---
name: hal-amend-design
description: Use when a hal-hq design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently".
---
# hal-amend-design
Changes a design document. **Authoritative playbook:**
[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md).
## Which layer is being changed
**Establish this first — the two amend for opposite reasons.**
| Layer | Amend when | Requires |
|---|---|---|
| `01-to-be/` | The intention changed | A decision record. Always. |
| `00-as-is/` | The mesh changed, or the document was wrong about it | Evidence from the implementation. Never a decision. |
An as-is document is corrected against **what the code does**, not against what anyone meant.
If the implementation and the intention disagree, the as-is document records the implementation
and says they disagree.
## Amending the to-be layer
1. Write the decision record. If it reverses an earlier one, that record gets
`status: superseded` and `superseded-by:` — its text is never edited.
2. Edit the design; set `updated:` to today.
3. If this came from an issue, set that issue's `amended-design:`.
4. Add the ledger line to `DECISIONS.md`.
## Amending the as-is layer
1. Establish what is actually true — from the code, a pipeline log, a live query, the
operational record. Not from a design document.
2. Edit the document. Set `updated:` only if the **implementation state** changed; a
correction to text that was always wrong does not change it.
3. If the correction reveals that something shipped differently from its design, say so in the
as-is document and leave the to-be document alone. That divergence is a finding, and may
deserve an issue.
## Do not
- Do not put a future intention in an as-is document.
- Do not quietly fix a wrong claim that held up a decision. Record that it was wrong and where
it was relied on — that is the failure this repository exists to name.
.claude/skills/hal-diagnose/SKILL.md
+40
View File
@@ -0,0 +1,40 @@
---
name: hal-diagnose
description: Use when investigating an open hal-hq issue — finding which component owns a symptom, and why. Triggers on "diagnose issue N", "where does this live", "who owns this bug", "why does this happen".
---
# hal-diagnose
Investigates an open issue to the point where its owner is known. **Authoritative playbook:**
[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md).
## Before forming a hypothesis
**Search the operational memory for the literal symptom text.** Not after a hypothesis fails —
before forming one. The knowledge base is indexed on symptoms, and the entry needed is usually
titled after the error being stared at.
This fires hardest on familiar ground, where a confident trail feels like progress. Two entries
have been rediscovered from scratch over several hours in one session because the search was
skipped. Both were already written down.
If the search returns nothing and the problem is then solved, write the finding back. An empty
result is not "nothing to learn" — it is the reason the next person repeats the work.
## Steps
1. Read `00-report.md`. Move `status:` to `diagnosing`.
2. Investigate. Write `01-diagnosis.md` in the same folder: the trail, **dated**, including
what was ruled out and how. Archaeology — which commit, which pull request, which date a
behaviour changed — is the most valuable content here.
3. When the owner is known, set `status: located` and fill `located-in:` with repositories or
modules from [`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md).
4. On resolution: `status: resolved`, fill `fixed-by:`. If the root cause was a design gap, run
`hal-graduate` for the amendment and fill `amended-design:`.
## Rules
- State evidence, not assertion. A date and a reference outrank a conclusion.
- Record what was ruled out. The next person needs to know where not to look.
- Closed issues are never deleted.
- `wontfix` is legitimate and requires a sentence saying why.
.claude/skills/hal-graduate/SKILL.md
+45
View File
@@ -0,0 +1,45 @@
---
name: hal-graduate
description: Use when a hal-hq research effort concludes and becomes design, or when a design must change. Triggers on "graduate this research", "this is decided", "write the ADR", "close the effort", "the design changed".
---
# hal-graduate
Closes a research effort into a decision and a design, or amends an existing design.
**Authoritative playbook:**
[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md) — read
it; this skill adds only the scaffolding.
## Steps
1. **Check against GENESIS** — `mission.md`, `context.md`, `effect.md`. If the conclusion
conflicts, say which is wrong, in writing, before proceeding.
2. **Write the decision record** in `adr/`, next free number, frontmatter per
[`adr/README.md`](../../../adr/README.md). `reconstructed: false` — this one is being taken,
not recovered. Record the rejected options.
3. **Write the design** under `02-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`,
empty `code:`, today's `updated:`, and `decisions:` pointing at the record.
4. **Close the effort** — the research `status.md` gets `status: graduated` and `became:`
pointing at both.
5. **Add the ledger line** to `DECISIONS.md` under today's heading.
## Amending an existing design
A design changes only through a decision. Write the record first; if it reverses an earlier
one, set that record's `status: superseded` and `superseded-by:` — **never edit its text**.
Then edit the design and set `updated:`.
## When something ships
Write or update the matching `02-DESIGN/00-as-is/` document so it describes what now runs,
including anything that shipped differently from the intent. Set the to-be document's
`status: implemented` and its `code:`. **The to-be document does not move** — both stand.
`status: implemented` must be defensible from the owning repository's main branch. If it
cannot be checked, it is `in-progress`.
## Do not
- Do not move a to-be document into `00-as-is/`.
- Do not edit an as-is document to describe an intention.
- Do not change a decision record's meaning. Supersede it.
.claude/skills/hal-handoff/SKILL.md
+32
View File
@@ -0,0 +1,32 @@
---
name: hal-handoff
description: Use when a hal-hq design is settled and implementation is about to start in a code repository. Triggers on "start building this", "hand this off", "ready to implement", "who owns this now".
---
# hal-handoff
Hands a settled design to a code repository. **Authoritative playbook:**
[`00-GENESIS/process/04-build-handoff.md`](../../../00-GENESIS/process/04-build-handoff.md).
## Steps
1. **Confirm it is settled.** `status: designed`, and every claim traceable to a record in
`adr/`. An open question in the text is a reason to run `hal-new-research`, not to build
around it.
2. **Name the owner.** Set `code:` from
[`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md). If the repository does not exist yet,
add it to `repos.md` in the same change.
3. **Read the as-is counterpart.** What is being replaced must be written down in
`02-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how
shipped behaviour gets lost.
4. **Flip the status** to `in-progress`, `updated:` today.
5. Build in the code repository. hal-hq never carries implementation.
6. On completion, run `hal-graduate`'s "when something ships" section.
## Non-negotiable
- Every merge is a human checkpoint, without exception.
- **Never open a pull request unprompted.** A permissions list saying it is allowed is not a
request.
- Work in an isolated worktree, never a shared checkout.
- Never push to the main branch.
.claude/skills/hal-new-issue/SKILL.md
+47
View File
@@ -0,0 +1,47 @@
---
name: hal-new-issue
description: Use when something is wrong with the HAL mesh at the level of design or governance — a rule enforced by nothing, a stated behaviour that does not happen, a failure the design lets pass silently. Triggers on "this is broken", "open an issue", "that rule isn't enforced", "this reports success and does nothing".
---
# hal-new-issue
Opens a numbered issue. **Authoritative playbook:**
[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md).
## First, decide it belongs here
| Belongs in `04-ISSUES` | Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| Finding the owner needs the whole mesh in view | Symptom → fix, once the answer is known |
**Search the knowledge base first** for the literal symptom text. If the answer is already
there, this is not an issue — it is a lookup. If the answer is a general lesson, it belongs in
both.
## Steps
1. Next free number. Create `04-ISSUES/NNN-short-name/00-report.md` with:
```yaml
---
status: open
opened: YYYY-MM-DD
located-in: []
fixed-by:
amended-design:
---
```
2. Write the symptom **as observed**, in plain terms, with the evidence that it happened —
what was run, what came back, when.
3. Say why it matters beyond the instance. An issue that is only one occurrence is a knowledge
base entry.
4. End with open questions rather than a proposed fix. Diagnosis is a separate step.
## Do not
- Do not name nodes, domains, addresses or paths. This repository is public.
- Do not guess the owner — `located-in:` is filled by diagnosis, not by opening.
.claude/skills/hal-new-research/SKILL.md
+42
View File
@@ -0,0 +1,42 @@
---
name: hal-new-research
description: Use when starting a new research effort in hal-hq — an idea, technology or approach worth investigating before it is committed to design. Triggers on "research X", "investigate X", "spike X", "should we use X", "is X worth doing".
---
# hal-new-research
Scaffolds a new research effort. **Authoritative playbook:**
[`00-GENESIS/process/01-research.md`](../../../00-GENESIS/process/01-research.md) — read it;
this skill only does the mechanical setup.
## Steps
1. Find the next free number: list `01-RESEARCH/NNN-*`, take the highest plus one, zero-padded
to three digits.
2. Create `01-RESEARCH/NNN-descriptive-name/` (kebab-case from the topic).
3. Create `status.md` in it with exactly this frontmatter, then a prose summary of **what** is
being investigated, **why**, and **what it touches**:
```yaml
---
status: ongoing
initiated: YYYY-MM-DD
touches: []
became: []
---
```
4. Do the research in further documents in the same folder. Keep the summary current.
## Do not
- Do not restate the status in prose. It lives in frontmatter, in one place.
- Do not fill `became:` while the effort is open — `hal-graduate` sets it at closure.
- Do not skip or reuse a sequence number.
- Do not write into `02-DESIGN` from an open effort.
- Do not name the mesh being observed. Evidence is required; identification is forbidden.
## Closing
An effort never just stops. It closes through `hal-graduate` as `graduated` or `abandoned`,
always with `became:` pointing at what it turned into. Nothing is deleted.
.claude/skills/hal-status/SKILL.md
+41
View File
@@ -0,0 +1,41 @@
---
name: hal-status
description: Use when you need a cross-cutting view of where hal-hq stands — research state, design implementation state, open issues, or the decision-record index. Triggers on "what's the status", "show the ADR index", "where do things stand", "what's in progress", "what's open".
---
# hal-status
Generates a cross-cutting view **from frontmatter**. This is a read-and-render skill, not a
workflow — hal-hq has **no central status file by design** (decision 35). Every view is
generated on demand and never written back to disk.
## What to read
| Section | Files | Frontmatter |
|---|---|---|
| Research | `01-RESEARCH/NNN-*/status.md` | `status` (`ongoing` / `graduated` / `abandoned`), `initiated`, `touches`, `became` |
| Design | `02-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` |
| Decisions | `adr/NNNN-*.md` | `status` (`proposed` / `accepted` / `superseded`), `date`, `deciders`, `reconstructed`, `superseded-by`, `extends` |
| Issues | `04-ISSUES/NNN-*/00-report.md` | `status` (`open` / `diagnosing` / `located` / `resolved` / `wontfix`), `opened`, `located-in`, `fixed-by`, `amended-design` |
## Steps
1. Read the frontmatter block from every file above — a grep across each tree is enough, no
need to load bodies.
2. Render what was asked as Markdown tables. Group and sort sensibly. The **ADR index** is one
of these views: records ordered by number, with title, date and status, and reconstructed
ones marked.
3. Flag anything inconsistent at the end, as flags — do not silently correct the render:
- a `graduated` or `abandoned` effort with an empty `became:`
- an `implemented` design with an empty `code:`
- a `superseded` record with no `superseded-by:`
- an `open` or `diagnosing` issue with no activity
- a to-be design whose `decisions:` points at a record that does not exist
- an as-is design whose claims are older than its `updated:` date suggests
## Do not
- **Do not write a status file.** Central status files are explicitly rejected. The view is
always generated, always ephemeral. This includes the ADR index — the hand-written one had
already drifted after a single addition, which is why it was removed.
- Do not infer status from prose. Trust only the frontmatter; if it is wrong, flag it.
.claude/skills/hal-sync-constitution/SKILL.md
+38
View File
@@ -0,0 +1,38 @@
---
name: hal-sync-constitution
description: Use after changing a rule in hal-hq's 00-GENESIS/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page".
---
# hal-sync-constitution
Publishes the derived constitution from its source. **Authoritative playbook:**
[`00-GENESIS/process/05-constitution-sync.md`](../../../00-GENESIS/process/05-constitution-sync.md).
## What this is
[`00-GENESIS/how-we-build.md`](../../../00-GENESIS/how-we-build.md) is the **source**. The
knowledge base carries a **derived** page that the mesh injects into every eligible design
session, and against which a check phase can block work.
Two texts stating the same rules drift, and the enforced copy wins by default — so the reasoned
copy quietly stops being true. This skill is the mechanism that prevents that, and it is how
the claim "HQ is the source" is checked.
## Steps
1. Confirm the source change is recorded as a decision. A rule the mesh enforces is
architecturally significant; if there is no record, run `hal-graduate` first.
2. Derive the page: the **rules without the reasoning**. Section numbering is stable — the
orchestrator and the review fragments cite sections by number, so never renumber to tidy.
3. Publish it to the knowledge base under the constitution slug, replacing the body.
4. **Read it back and verify the change is present.** A publish that reported success and did
nothing is exactly the failure class this repository exists to name — do not skip this.
5. Note the sync in the decision's ledger line.
## Do not
- **Never edit the derived page directly.** An edit there survives until the next sync and then
vanishes, taking its reasoning with it.
- Do not relax a rule in the derived page. Overrides may only tighten.
- Do not report the sync as done without the read-back. If it could not be performed, say so —
an unsynced rule is a rule the mesh does not enforce, whatever the source says.
00-GENESIS/README.md
+29 -11
View File
@@ -3,26 +3,44 @@
The **northern star**. What HAL is, the environment it runs in, and what changes when it
works. Every research effort and design decision is checked against this folder.
| File | Purpose |
| File / folder | Purpose |
|------|---------|
| [`mission.md`](mission.md) | Vision, mission, and the values that decide arguments |
| [`context.md`](context.md) | The environment — conditions, not aspirations |
| [`effect.md`](effect.md) | What is different when the work is done |
| [`how-we-build.md`](how-we-build.md) | Rules that hold across the mesh, each one earned |
| [`how-we-build.md`](how-we-build.md) | The rules that hold across the mesh, each one earned. **The source of the mesh constitution** — the governed page the mesh injects into design sessions is derived from it. |
| [`repos.md`](repos.md) | Where implementation lives, and what each repository owns |
| [`process/`](process/) | The playbooks — how work moves through this repository, for engineers and agents alike |
## Rules
- Markdown only.
- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration.
- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration. The one
exception is `how-we-build.md`, which changes whenever a rule is earned — and only through
its amendment process.
- Research and design must be traceable back to what is written here.
- **Instance-agnostic.** These documents describe the mesh as a concept. No machine names, no
counts, no topology.
## Note on `VISION.md`
## On the architecture overview in the code repository
The repository root carries `VISION.md`, an architecture overview predating this folder.
It is a useful description of *how* the mesh works and should be folded into
[`02-DESIGN`](../02-DESIGN/), not here — GENESIS answers *why*.
The code repository carries an architecture overview predating this folder. It is a useful
description of *how* the mesh works, and its content now lives — anonymised and checked against
the implementation — in [`02-DESIGN/00-as-is/`](../02-DESIGN/00-as-is/). GENESIS answers *why*;
that document answered *how*, which is the design layer's job.
It has also drifted: it lists "Symlinks, not copies" as a key design principle, while the
operating rules forbid creating symlinks at all after one caused production data loss.
A founding document contradicting a hard rule is precisely the failure this folder exists
to prevent.
It had also drifted from the implementation in ways worth recording, since both were found by
comparing it against the code rather than by anyone noticing:
- It described the pipeline as having a separate builder process and a build stage that
packages. Neither was true after 2026-08-04; the documents stayed stale until 2026-08-06
([ADR 0014](../adr/0014-build-publish-and-deploy-are-three-silos.md)).
- It listed the mesh as spanning a fixed number of named machines, which is exactly the
content this repository cannot carry.
One earlier note in this file has been withdrawn as **wrong**, and is recorded here rather than
deleted. It claimed the overview's "symlinks, not copies" principle contradicted the mesh's
hard rule against symlinks. It does not. The rule forbids *creating* a symlink by hand; the
installer creates and reconciles every link the mesh needs, deliberately
([ADR 0011](../adr/0011-the-installer-owns-linking.md)). The rule is about who may link, not
about whether the mesh links — a misreading common enough that the ADR now says so explicitly.
00-GENESIS/context.md
+5
View File
@@ -1,3 +1,8 @@
---
status: canonical
updated: 2026-08-22
---
# Engineering Context
The conditions the mesh is built for. Properties, not an inventory — no node here is
00-GENESIS/effect.md
+5
View File
@@ -1,3 +1,8 @@
---
status: canonical
updated: 2026-08-22
---
# Effect
Imagine the mesh works as intended. What is different?
00-GENESIS/how-we-build.md
+170 -26
View File
@@ -1,42 +1,186 @@
---
status: canonical
updated: 2026-08-23
derives: knowledge-base constitution page
decisions:
- adr/0009-the-mesh-is-governed-by-a-constitution.md
---
# How we build
Working notes on the rules that hold across the mesh. Short, and each one earned.
The rules that hold across the mesh. Short, and each one earned.
## Name a context after its aggregate, not after a metaphor
**This document is the source of the mesh constitution.** The governed page the mesh injects
into design sessions is *derived* from it, section for section, and carries the rules without
the reasoning. Never edit that page directly — an edit there survives until the next sync and
then vanishes, taking its reasoning with it. The sync is playbook
[`process/05-constitution-sync.md`](process/05-constitution-sync.md), and it is how the claim
"HQ is the source" is checked.
`hal/agents` owns **Agent**. A *brain* — memory, thoughts, cognition — is something an
agent **has**, a concept inside the aggregate. It is not a module.
Section numbers are stable. The orchestrator and the review fragments cite them.
The cost of getting this wrong is visible today: `hal/brain` names the node runtime, so
the most evocative word in the system points at infrastructure, and `hal/cortex`
describes itself as "mesh messaging" in its manifest while the anatomy documentation
calls it the interactive runtime — and it runs on no node at all.
---
## 1. Purpose
These are the principles and guardrails every piece of work in the mesh is checked against —
design sessions, analysis gates, reviews, and agents acting on their own. A rule stated here is
non-negotiable unless amended per §6.
They exist because each was violated first. Where a rule reads as arbitrary, that is a sign the
incident behind it is not written down, and the fix is to write it down, not to relax the rule.
---
## 2. Non-negotiables
| Rule | What it means |
|---|---|
| **Never write to a production database directly** | No insert, update, delete or schema statement executed against production by hand. Schema changes go through numbered migrations; data changes go through application code or the module's own capabilities. Raw statements skip every side effect the proper path has — events, audit, cache invalidation, fan-out. |
| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. [ADR 0006](../adr/0006-schema-changes-are-numbered-migrations.md) |
| **Never bypass the pipeline** | No manual database edit, no manual restart as a workaround. Fix the cause and deploy. A workaround that works is a workaround that is never removed, and the next person cannot tell the node from its declaration. |
| **Never create a symlink** | The installer owns all linking and reconciles it. A hand-made link caused production data loss through container volume resolution — and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. [ADR 0011](../adr/0011-the-installer-owns-linking.md) |
| **Never push directly to the main branch** | Branch, push, review, merge. Every merge is a human checkpoint, without exception. |
| **One change per pull request, and never merge your own** | Unrelated improvements bundled together cannot be reviewed or reverted separately. Self-merging removes the checkpoint that is the entire point. |
| **Never open a pull request unprompted** | A permissions list saying it is allowed is not a request. |
| **A failed step fails the job** | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. [ADR 0008](../adr/0008-a-failed-step-fails-the-job.md), and §5. |
### A failed step must stop the steps after it — how it was earned
A worktree creation failed because the branch name collided with an existing namespace. The
change into that worktree failed too. The copy, the staging and the commit that followed all
ran in the shared checkout and committed to a local main. The error was printed and scrolled
past.
This is the same shape as the faults the mesh's whole refactor exists to remove: a step
reported failure, nothing stopped, and the damage happened somewhere nobody was looking.
---
## 3. Module and infrastructure rules
### Manifests
- **Never bump a version by hand.** The builder owns versioning. A version change in a diff is
a defect; revert it.
- **Features are detected, not declared.** The installer discovers what a module carries from
what its directory contains. A declared list and the directory it describes drift, and the
directory is the one that is true.
- **Every runtime variable is declared.** A variable the module reads and the manifest does not
declare is invisible to the mesh: it will not be generated, injected, or audited.
- **Provisioned credentials arrive through declared requirements**, never hardcoded in code,
compose files or scripts. [ADR 0005](../adr/0005-capabilities-are-provisioned-on-declaration.md)
### Placement
- **Core modules belong to the monorepo** — the runtime, delivery, provisioning, configuration,
knowledge, and the shared infrastructure the mesh provisions against.
- **Every standalone application gets its own repository**, with a manifest at its root,
registered as a build source. Creating an application directory in the monorepo is a
convention violation and reviewers reject it.
[ADR 0010](../adr/0010-applications-live-in-their-own-repository.md)
### Migrations
- Numbered, idempotent, and safe to re-run. Guard every statement.
- The initial migration is **frozen** once it has run anywhere. Change is a new number.
- Numbers are unique. A duplicate prefix is a defect, not a style question.
### Managed files
**A file edited on a node is a bug with a delay on it.** Everything under the mesh's managed
surface is regenerated from the mesh database; a local edit survives one synchronisation and is
then silently overwritten, bringing back whatever it fixed. Use the mesh operation that owns
the value. If unsure whether a file is managed, ask the tooling — the answer is not visible
from the file. [ADR 0004](../adr/0004-managed-files-are-generated-never-edited.md)
---
## 4. Naming and boundaries
### Name a context after its aggregate, not after a metaphor
A context named `agents` owns **Agent**. A *brain* — memory, thoughts, cognition — is something
an agent **has**: a concept inside the aggregate, not a module.
The cost of getting this wrong is visible today. An anatomy name points at the node runtime, so
the most evocative word in the system names infrastructure; another describes itself as "mesh
messaging" in its manifest while the anatomy documentation calls it the interactive runtime —
and it runs on no node at all.
Anatomy makes attractive names and poor boundaries. Name the thing the domain calls it.
## Ubiquitous language is checked, not assumed
### Group by domain, not by single function
If a document states a rule about the mesh, say how the rule is verified. This repository
has a documented requirement that every module exposing tools declares `brain` as a
dependency. Zero modules do. An unenforced rule is indistinguishable from a wrong one,
and costs more, because people believe it.
A module is a purpose, not a piece of software. Four modules that together constitute "how a
node is reachable" and cannot be assigned, versioned or replaced as one thing are four
accidents, not four boundaries.
[ADR 0017](../adr/0017-modules-outside-the-core-are-grouped-by-domain.md)
## Contexts integrate through the record, never through a shared schema
### Contexts integrate through the record, never through a shared schema
Publish to the stream; do not join across a boundary. Today five domains share one
45-table schema, which is why work that belongs to one context keeps having to be
Publish to the stream; do not join across a boundary. Today several domains share one
forty-five-table schema, which is why work belonging to one context keeps having to be
implemented in another.
## A failed step must stop the steps after it
---
Scripted work runs as a sequence, and a sequence that continues past a failure does the
next thing in the wrong place. Gate each step on the last: `cd X || exit`, not `cd X`
followed by a newline.
## 5. Evidence and verification
Earned the obvious way. A `git worktree add` failed because the branch name collided with
an existing namespace; the `cd` into that worktree failed too; and the `cp`, `git add` and
`git commit` that followed ran in the shared checkout and committed to local `main`. The
error was printed and scrolled past.
### Ubiquitous language is checked, not assumed
This is the same shape as the faults this refactor exists to remove — a step reported
failure, nothing stopped, and the damage happened somewhere nobody was looking.
**If a document states a rule about the mesh, it says how the rule is verified.** This
repository has a documented requirement that every capability-exposing module declare the core
runtime as a dependency. Zero modules do.
An unenforced rule is indistinguishable from a wrong one, and costs more, because people
believe it.
### Behavioural criteria require runtime evidence
A criterion of the form *"the script runs"*, *"the endpoint answers"*, or *"the migration
applied"* is satisfied only when the change has actually been exercised: a real run, a real
request, a pipeline log, a live query showing the expected result.
**Marking a runtime criterion verified from a diff is itself a violation.** A reviewer who
finds one names the evidence required and returns the work.
The reason is the mesh's most consistent failure shape: a green result proves transport, not
effect. Absence reads as success unless something looked.
### Search the record before forming a hypothesis
The first action on any error message, failing service or unexpected behaviour is to search the
operational memory for the literal error text — before a hypothesis, not after one fails. The
knowledge base is indexed on symptoms.
This fires hardest on *familiar* ground, where a confident trail feels like progress. Two
entries were each rediscovered from scratch over several hours in a single session because the
search was skipped. Both were already written down.
---
## 6. Amendment
This document is governed. It does not change by commit message or unilateral decision.
1. **Propose** — a change stating what rule is changing, why the current wording is
inadequate, and what reviewed it.
2. **Review** — sign-off by reviewers who are not the proposer.
3. **Record** — the change is a decision and gets a record in [`adr/`](../adr/), because a
rule the mesh enforces is architecturally significant.
4. **Sync** — playbook [`process/05-constitution-sync.md`](process/05-constitution-sync.md)
publishes the derived page. An unsynced rule is a rule the mesh does not enforce, whatever
this document says.
No drive-by edits. Every change traces to a recorded decision.
---
## 7. Overrides
A team or product may define additional constraints that **narrow or tighten** these rules.
They may never relax them.
An override says which rule it tightens, or which gap it fills, and follows the same amendment
process. Absence of an override means these rules apply unmodified.
00-GENESIS/mission.md
+5
View File
@@ -1,3 +1,8 @@
---
status: canonical
updated: 2026-08-22
---
# Mission
## Vision
00-GENESIS/process/00-overview.md
+59
View File
@@ -0,0 +1,59 @@
# Process — overview
How work moves through hal-hq, and who may do what. Every other document in this folder is a
playbook: trigger, who runs it, steps, outputs. Engineers and agents follow the same
playbooks; agents must not act outside them.
## The audiences
| Audience | Contract |
|---|---|
| **Engineers** | Read and write everything. hal-hq is the single source of truth for mission, research, design, decisions and issue diagnosis. |
| **Agents** | The same rights as engineers, exercised through these playbooks. |
| **Anyone else** | This repository is public and written for them, but it is not a support channel. Nothing here identifies the mesh it describes. |
## The knowledge flow
```
idea ──► 01-RESEARCH ──► decision (adr/) ──► 02-DESIGN/01-to-be ──► built (code repo)
│ │ │
│ │ └─► 02-DESIGN/00-as-is once shipped
│ └────► abandoned (recorded, kept)
└─(small/obvious, decision recorded in DECISIONS.md)────► 02-DESIGN directly
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
how-we-build.md ──► constitution sync ──► knowledge base ──► injected into design meetings
```
## The two design layers
`02-DESIGN` holds two layers that are never mixed:
| Layer | What it is | Changes when |
|---|---|---|
| `00-as-is/` | The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. |
| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `adr/`. | A decision is taken or amended. |
A to-be document that ships does not move. Its as-is counterpart is written or updated, the
to-be document's frontmatter goes to `implemented`, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
## The playbooks
| # | Playbook | Trigger |
|---|---|---|
| [01](01-research.md) | Research | An idea worth investigating before committing to design |
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
## Status lives in frontmatter
Research overviews, design docs, issue reports and decision records each carry their status as
YAML frontmatter (schemas in the section READMEs and playbooks). There are **no central status
files**. `DECISIONS.md` is a ledger of decisions as they were taken — an index and a home for
decisions too small to warrant a record — and is explicitly *not* a status board. Cross-cutting
views are generated on demand by the `hal-status` skill and never written to disk.
00-GENESIS/process/01-research.md
+48
View File
@@ -0,0 +1,48 @@
# Playbook 01 — Research
**Trigger.** An idea, technology or approach worth investigating before it is committed to
design. Also: an as-is document that raises a question nobody can answer.
**Who runs it.** Anyone.
## Steps
1. Take the next free number: highest `01-RESEARCH/NNN-*` plus one, zero-padded to three
digits. Never skip or reuse a number.
2. Create `01-RESEARCH/NNN-descriptive-name/` and a `status.md` in it carrying:
```yaml
---
status: active
initiated: YYYY-MM-DD
touches: [] # areas, subsystems or as-is design docs the effort bears on
---
```
Then a short prose summary: **what** is being investigated, **why**, and **what it
touches**.
3. Do the research in further documents in the same folder — notes, option analyses, evidence,
draft designs. Anything goes. Keep the summary in `status.md` current as the effort changes
shape.
## What makes research worth reading
State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"*
outranks *"the dependency rule is not followed"*. An effort that measured nothing has not
finished.
Research describes real observations but never identifies the mesh it observed. The shape of a
finding survives anonymisation intact — *a node publicly named but behind a household NAT*
carries the whole lesson without naming anything.
## Do not
- Do not put status in prose. It lives in `status.md`'s frontmatter, and the prose must not restate it.
- Do not set `became:` while the effort is open — playbook 02 sets it at closure.
- Do not write into `02-DESIGN` from an open effort.
## Closing
An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated`
or `abandoned`, always with `became:` pointing at what it turned into. Nothing is deleted —
what was rejected, and why, is the more expensive half to rediscover.
00-GENESIS/process/02-graduation.md
+60
View File
@@ -0,0 +1,60 @@
# Playbook 02 — Graduation and design change
**Trigger.** A research effort concludes, or an existing design must change.
**Who runs it.** Anyone, with the decision recorded before the design moves.
## Graduating research
1. **Check it against GENESIS.** An effort graduates only if its conclusion is traceable to
[`mission.md`](../mission.md), [`context.md`](../context.md) and
[`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is —
say which, in writing, before proceeding.
2. **Record the decision.** Write a record in [`adr/`](../../adr/) taking the next free
number. Format and rules are in [`adr/README.md`](../../adr/README.md). State evidence,
not assertion, and record the options that were rejected — that is the half worth keeping.
3. **Write the design.** Create the document under `02-DESIGN/01-to-be/` with frontmatter:
```yaml
---
layer: to-be
status: designed
code: [] # owning code repo(s); set at build handoff, empty before
updated: YYYY-MM-DD
decisions: [adr/NNNN-....md]
---
```
4. **Close the effort.** Set the effort's `status.md` frontmatter to `status: graduated` and
`became:` pointing at the design document and the decision record.
5. **Add a ledger line.** Append the decision to [`DECISIONS.md`](../../DECISIONS.md) under
today's heading, pointing at the record.
## Amending an existing design
A design changes only through a decision.
1. Write the decision record. If it reverses an earlier one, the earlier record's `status:`
becomes `superseded-by: adr/NNNN-....md` — **its text is never edited**.
2. Edit the to-be design document and set `updated:` to today.
3. If the amendment came from an issue, set that issue's `amended-design:` to the document
path.
4. Add the ledger line.
## When something ships
Implementation state is a third axis, independent of both design and decision.
1. Write or update the matching document under `02-DESIGN/00-as-is/` so it describes what now
runs — including anything that shipped differently from the intent. A design that shipped
bent is an as-is fact, not a design amendment.
2. Set the to-be document's `status: implemented` and its `code:` to the owning repositories
from [`repos.md`](../repos.md).
3. `status: implemented` must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is `in-progress`.
## Do not
- Do not move a to-be document into `00-as-is/`. Write the as-is document; both stand.
- Do not edit an as-is document to describe an intention. That is what the to-be layer is for.
- Do not change a decision record's meaning. Supersede it.
00-GENESIS/process/03-issues.md
+47
View File
@@ -0,0 +1,47 @@
# Playbook 03 — Issues
**Trigger.** Something is wrong at the level of the mesh's design or governance — a rule that
turns out to be unenforced, a stated behaviour that does not happen, a silent failure the
design permits.
**Who runs it.** Anyone may open an issue. No localisation is required to report one.
## What belongs here, and what does not
| Belongs in `04-ISSUES` | Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
The knowledge base already holds the operational record and is indexed on symptoms. This
folder is not a second copy of it. An issue here is a question HQ must **answer**, not an
incident someone must **clear**.
## Steps
1. Take the next free number. Create `04-ISSUES/NNN-short-name/00-report.md`:
```yaml
---
status: open
opened: YYYY-MM-DD
located-in: [] # owning repo(s)/module(s), filled by diagnosis
fixed-by: # PR or commit reference, filled at resolution
amended-design: # design doc path, when the root cause was a design gap
---
```
Then the symptom **as observed**, in plain terms, with the evidence that it happened.
2. Investigate in `01-diagnosis.md` in the same folder — the trail, dated, including what was
ruled out. Move `status:` to `diagnosing`, then `located` once the owner is known.
3. Resolve. Set `status: resolved`, fill `fixed-by:`, and if the root cause was a design gap,
run playbook [02](02-graduation.md) and fill `amended-design:`.
## Rules
- Closed issues are never deleted — they are the mesh's symptom-to-component memory.
- An issue whose answer is a general lesson should also be written to the knowledge base, so
the next person searching a symptom finds it. Both, not either.
- `status: wontfix` is legitimate and requires a sentence saying why.
00-GENESIS/process/04-build-handoff.md
+30
View File
@@ -0,0 +1,30 @@
# Playbook 04 — Build handoff
**Trigger.** A to-be design is settled and work is about to start in a code repository.
**Who runs it.** Whoever starts the build.
## Steps
1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every
claim in it traces to a record in [`adr/`](../../adr/). An open question in the text is a
reason to run playbook [01](01-research.md), not to start building around it.
2. **Name the owner.** Set `code:` in the design's frontmatter to the repositories from
[`repos.md`](../repos.md). If the repository does not exist yet, add it to `repos.md` in
the same change.
3. **Check the as-is.** Read the matching `02-DESIGN/00-as-is/` document. What is being
replaced is stated there; if it is not, write it before changing it. Building against an
undocumented as-is is how a shipped behaviour gets lost.
4. **Flip the status.** `status: in-progress`, `updated:` today.
5. **Build in the code repository.** hal-hq is not a code repository and never carries
implementation.
6. **On completion**, run the "when something ships" section of playbook
[02](02-graduation.md).
## Rules
- Every merge is a human checkpoint, without exception.
- Never open a pull request unprompted. A permissions list saying it is allowed is not a
request.
- Work in an isolated worktree, never a shared checkout. A failed `cd` in a shared checkout
commits to the wrong branch, and the error scrolls past.
00-GENESIS/process/05-constitution-sync.md
+37
View File
@@ -0,0 +1,37 @@
# Playbook 05 — Constitution sync
**Trigger.** [`how-we-build.md`](../how-we-build.md) changed a rule that the mesh enforces at
runtime.
**Who runs it.** Whoever made the change.
## Why this playbook exists
The mesh injects a constitution into every eligible design meeting; agents check their output
against it and a constitution-check phase can block a meeting. That text is **derived**.
`how-we-build.md` is the source.
Two texts stating the same rules will drift, and the enforced copy winning by default means
the reasoned copy quietly stops being true. This playbook is the mechanism that stops that —
and, per the repository's own rule, it is how the rule "HQ is the source" is checked.
## Steps
1. Edit [`how-we-build.md`](../how-we-build.md). Each rule keeps the reasoning that earned it;
the derived page carries the rule alone.
2. Record the change as a decision — a rule the mesh enforces is architecturally significant.
Playbook [02](02-graduation.md).
3. Publish the derived page to the knowledge base under the constitution slug, replacing its
body. Keep the section numbering stable: the meeting orchestrator and the review fragments
cite sections by number.
4. Verify the derived page reads back with the change present. A publish that reported success
and did nothing is exactly the failure class this repository exists to name.
5. Note the sync in the ledger line for the decision.
## Rules
- **Never edit the derived page directly.** An edit there survives until the next sync and
then vanishes, taking its reasoning with it.
- The derived page may only be **tightened** by per-team override pages, never relaxed.
- If the sync cannot be performed, say so in the ledger line. An unsynced rule is a rule the
mesh does not enforce, whatever `how-we-build.md` says.
00-GENESIS/repos.md
+51
View File
@@ -0,0 +1,51 @@
---
status: canonical
updated: 2026-08-23
---
# The HAL repositories
The map of where implementation lives. Humans use it for orientation; agents use it for issue
triage (playbook [`process/03-issues.md`](process/03-issues.md)). The `code:` frontmatter
field in design documents points at entries here.
Repository *names* are recorded; hosts, URLs and owners are not — this repository is public,
and a forge address is an operational detail (see [`README`](../README.md)).
| Repository | Owns |
|---|---|
| `hal` | The monorepo — the node runtime, the module catalogue, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
| `hal-hq` | This repository — mission, research, design, decisions, issue diagnosis. The source of truth for *why*. Carries no implementation. |
| *(one per application)* | Every standalone application, site or side-project gets its own repository, with `module.yml` at the root. Registered with the mesh as a build source; built and deployed by the same pipeline as anything in the monorepo. |
## What lives where inside the monorepo
Named by role, because the layout is itself part of the as-is design — see
[`02-DESIGN/00-as-is/`](../02-DESIGN/00-as-is/).
| Area | Holds |
|---|---|
| Module catalogue | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
| Node runtime | The daemon and interactive runtime that every node runs. |
| Bootstrap scripts | First-node initialisation, joining an existing mesh, and node rescue. |
| Shared library | The SDK every module builds against. |
| Pipeline test harness | End-to-end coverage of the delivery pipeline. Currently unbuildable — see [`04-ISSUES/005`](../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md). |
## Why applications do not live in the monorepo
A standalone application in the monorepo is a convention violation, and reviewers reject it.
The reasoning is recorded in [`adr/0010`](../adr/0010-applications-live-in-their-own-repository.md):
the mesh installs, provisions for, and ships an application through exactly the same machinery
whether or not its source sits beside the mesh's own — so co-location buys nothing and costs
the monorepo's review cadence.
## There is no npm workspace
Each module is a standalone package that consumes its dependencies from the private registry,
not from a sibling directory. The workspace was removed after it caused build-versus-development
divergence — a workspace member importing another resolved to local unbuilt source in the
pipeline and to a published version in development. Recorded in
[`adr/0007`](../adr/0007-no-npm-workspace.md).
Consequence, and it is a real one: a cross-package change is two steps — publish, then consume
— and a repository-wide `npm install` does not exist.
01-RESEARCH/001-module-domain-decomposition/analysis.md
+6 -1
View File
@@ -1,3 +1,8 @@
---
effort: 001-module-domain-decomposition
updated: 2026-08-22
---
# Current state → ideal state
## 1. The count is a symptom
@@ -232,6 +237,6 @@ returns. That mechanism is the subject of a separate ADR.
pipeline resolves dependencies across the registry rather than the filesystem?
4. **SDK residue** — after extraction, does `hal/sdk` keep transport (`amqp-client`), or
does that belong to `hal/stream`? Everything imports it, which argues both ways.
5. **Human agent modality.** ADR 0001 requires a fact the mesh does not record: which
5. **Human agent modality.** ADR 0015 requires a fact the mesh does not record: which
user, on which node, a human agent acts as. Where does it live — an attribute of the
agent, or of the agent-node binding?
01-RESEARCH/001-module-domain-decomposition/status.md
+7 -1
View File
@@ -1,6 +1,12 @@
---
status: ongoing
initiated: 2026-08-22
touches: [02-DESIGN/00-as-is/02-modules-and-manifests.md, 02-DESIGN/00-as-is/10-module-catalogue.md, 02-DESIGN/01-to-be/00-work-breakdown.md]
became: [adr/0015-mesh-brokers-nodes-host-agents-think.md]
---
# 001 — Module domain decomposition
- **Status:** ONGOING — ADR 0001 accepted; graduates when `02-DESIGN` carries the per-context specifications
- **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.
01-RESEARCH/002-local-mesh/analysis.md
+8 -3
View File
@@ -1,3 +1,8 @@
---
effort: 002-local-mesh
updated: 2026-08-22
---
# A mesh that runs locally — current state and obstacles
Evidence for Phase 0. Every claim here is either a file location or something measured on
@@ -231,7 +236,7 @@ over either way.
a local-mesh implementation detail — if the answer is that the mesh should own
supervision, Phase 0 should not build a container-only workaround first. Under
investigation; findings will land in [`003-service-supervision`](../003-service-supervision/)
and, if it goes ahead, ADR 0002.
and, if it goes ahead, a decision record of its own.
2. **What replaces `~/.config/hal/env` and `/services/` inside a container?** A configurable
root keeps one code path; container-specific targets keep the host paths untouched. This
@@ -248,9 +253,9 @@ over either way.
## References
- [`adr/0001`](../../adr/0001-mesh-brokers-nodes-host-agents-think.md) — the decision this
- [`adr/0001`](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) — the decision this
phase unblocks
- [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/00-work-breakdown.md) — Phase 0 tasks
- [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/01-to-be/00-work-breakdown.md) — Phase 0 tasks
and checkpoint
- `troubleshooting/provision-adoption-rotates-live-credential` — fixture B, root cause open
- `troubleshooting/deploy-reports-transport-not-effect` — the nine defects that shipped
01-RESEARCH/002-local-mesh/status.md
+9 -3
View File
@@ -1,6 +1,12 @@
---
status: graduated
initiated: 2026-08-22
touches: [02-DESIGN/00-as-is/04-delivery.md, 02-DESIGN/00-as-is/05-runtime-and-installation.md]
became: [02-DESIGN/01-to-be/01-end-to-end-testing.md, adr/0016-a-lab-node-is-a-virtual-machine.md]
---
# 002 — A mesh that runs locally
- **Status:** GRADUATED — the design is [`02-DESIGN/01-end-to-end-testing.md`](../../02-DESIGN/01-end-to-end-testing.md)
- **Initiated by:** jochen, 2026-08-22
- **Areas touched:** `install.d/`, `hal/meshware`, `hal/coordinator`, `hal/brain`,
`hal/developer` (`dev_up`), `hal/sdk` (env generation, feature handlers, artifact
@@ -9,7 +15,7 @@
## Summary
Phase 0 of [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/00-work-breakdown.md) requires
Phase 0 of [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/01-to-be/00-work-breakdown.md) requires
a mesh that comes up in containers, runs its own pipeline, and reproduces known faults on
demand. Nothing else in the decomposition starts until it exists, because every fault the
decomposition addresses was found in production — there was nowhere else to find it.
@@ -18,7 +24,7 @@ This effort establishes what already runs in a container, what is welded to the
what it would take to close the gap. It does **not** choose an approach: the central
question — how a containerised node executes a module service, when a module service is
defined today as a systemd unit shelling to `docker compose` in `/services/` — is not
answered by ADR 0001 and is recorded below rather than decided.
answered by ADR 0015 and is recorded below rather than decided.
## What was established
01-RESEARCH/003-service-supervision/analysis.md
+9 -4
View File
@@ -1,3 +1,8 @@
---
effort: 003-service-supervision
updated: 2026-08-22
---
# Who supervises a service — the cost of leaving systemd
Measured 2026-08-22. Every claim is a file location or a count.
@@ -123,10 +128,10 @@ What it costs, honestly:
---
## 5. Why it cannot be all-or-nothing — and ADR 0001 already says so
## 5. Why it cannot be all-or-nothing — and ADR 0015 already says so
Some of what runs under systemd today **cannot** be containerised, and the reason is
already in the domain model. ADR 0001:
already in the domain model. ADR 0015:
> a non-human agent acts through a spawned session — a human agent acts through a shell or
> desktop
@@ -203,7 +208,7 @@ found by grep.
**This no longer gates Phase 0.** When this was written, the local mesh was assumed to be
built from application containers, which forced the question — there is no natural way to
run an init system inside one. The decision of 2026-08-22 to build development nodes as
**system containers** (see [`02-DESIGN/01-end-to-end-testing.md`](../../02-DESIGN/01-end-to-end-testing.md))
**system containers** (see [`02-DESIGN/01-end-to-end-testing.md`](../../02-DESIGN/01-to-be/01-end-to-end-testing.md))
removes that pressure entirely: a system container runs a real init, so the existing model
works unmodified and the lab needs no answer here to exist.
@@ -218,7 +223,7 @@ fate-sharing reason in §3.
## References
- [`002-local-mesh`](../002-local-mesh/analysis.md) — the effort this came out of
- [`adr/0001`](../../adr/0001-mesh-brokers-nodes-host-agents-think.md) — agent modality, which
- [`adr/0001`](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) — agent modality, which
decides what cannot leave the host
- `modules/hal/meshware/daemon/src/cerebellum.ts:815-828` — the self-restart workaround
- `modules/hal/meshware/systemd/hal-module@.service` — the per-module Docker lifecycle
01-RESEARCH/003-service-supervision/status.md
+9 -3
View File
@@ -1,6 +1,12 @@
---
status: ongoing
initiated: 2026-08-22
touches: [02-DESIGN/00-as-is/05-runtime-and-installation.md]
became: []
---
# 003 — Who supervises a service
- **Status:** ONGOING — evidence gathered, options costed, decision open.
**No longer blocks Phase 0** (see below).
- **Initiated by:** jochen, 2026-08-22, in response to
[`002-local-mesh`](../002-local-mesh/analysis.md) open question 1
@@ -34,7 +40,7 @@ This effort answers the cost half. It does not choose.
- **There is a third option neither of us named**, and it is the one that also solves Phase 0:
run HAL's own daemons as containers, making Docker the supervisor for everything. Local and
production then have the same shape rather than a translation layer between them.
- **It cannot be all-or-nothing**, and ADR 0001 already says why: a human agent acts through a
- **It cannot be all-or-nothing**, and ADR 0015 already says why: a human agent acts through a
shell and a desktop. Those parts are on the host by definition.
- One incidental finding: the automatic node rescue that documentation describes **does not
exist**. No unit declares `OnFailure=`, and nothing calls `hal-rescue.sh` on a timer.
@@ -43,5 +49,5 @@ Detail and costs in [`analysis.md`](analysis.md).
## Decision needed
Which supervision model the mesh adopts, recorded in ADR 0002 before Phase 0 builds
Which supervision model the mesh adopts, recorded in a decision record before Phase 0 builds
anything. The options and their costs are in `analysis.md` under "Options".
01-RESEARCH/004-lab-network/analysis.md
+5
View File
@@ -1,3 +1,8 @@
---
effort: 004-lab-network
updated: 2026-08-22
---
# Reproducing the mesh network in a lab
Established 2026-08-22 by reading the generating code and the live mesh DB. Every claim is a
01-RESEARCH/004-lab-network/status.md
+7 -1
View File
@@ -1,6 +1,12 @@
---
status: ongoing
initiated: 2026-08-22
touches: [02-DESIGN/00-as-is/01-mesh-and-transport.md, 02-DESIGN/01-to-be/01-end-to-end-testing.md]
became: [adr/0016-a-lab-node-is-a-virtual-machine.md]
---
# 004 — Reproducing the mesh network in a lab
- **Status:** ONGOING — topology established and mapped; not yet stood up
- **Initiated by:** jochen, 2026-08-22 — *"the most difficult part of our VM setup will be
the networking part"*
- **Areas touched:** `modules/wireguard`, `modules/dnsmasq-app`, `modules/traefik`,
01-RESEARCH/README.md
+37 -7
View File
@@ -4,13 +4,43 @@ Investigations that have not yet hardened into design.
## Structure
Each effort lives in `NNN-descriptive-name/` and **must** contain `status.md` with:
Each effort lives in `NNN-descriptive-name/` and **must** contain `status.md`, carrying its
state in YAML frontmatter and a prose summary below it:
- a short summary of the effort
- who initiated it
- the areas it touches
- current status: `ONGOING`, `GRADUATED`, or `ABANDONED`
```yaml
---
status: ongoing | graduated | abandoned
initiated: YYYY-MM-DD
touches: [] # design docs, subsystems or areas the effort bears on
became: [] # required when status is terminal — what it turned into
---
```
An effort graduates by producing an ADR and a `02-DESIGN` entry. It is abandoned in
place — never deleted. What was rejected, and why, is the more expensive half to
The prose says what is being investigated, why, and what it touches. It does not restate the
status — status lives in one place, and two places is one too many.
Further documents in the same folder hold the work itself: notes, evidence, option analyses,
draft designs.
## Lifecycle
| status | Meaning |
|---|---|
| `ongoing` | Investigation in progress. |
| `graduated` | Checked against `00-GENESIS`, decided in `adr/`, and specified in `02-DESIGN` — see `became:`. |
| `abandoned` | Stopped or superseded. Nothing is deleted. |
An effort graduates by producing a decision record **and** a `02-DESIGN` entry. It is abandoned
in place — never deleted. What was rejected, and why, is the more expensive half to
rediscover.
Starting and closing efforts is playbook territory:
[`00-GENESIS/process/01-research.md`](../00-GENESIS/process/01-research.md) and
[`02-graduation.md`](../00-GENESIS/process/02-graduation.md).
## Rules
- Markdown only. Do not skip or reuse a sequence number.
- **Evidence, not assertion.** An effort that measured nothing has not finished.
- Research describes real observations but **never identifies the mesh it observed**. The shape
of a finding survives anonymisation intact.
02-DESIGN/00-as-is/00-overview.md
+98
View File
@@ -0,0 +1,98 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0001-nodes-communicate-over-a-broker.md
- adr/0002-everything-is-a-module.md
- adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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.
02-DESIGN/00-as-is/01-mesh-and-transport.md
+113
View File
@@ -0,0 +1,113 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0001-nodes-communicate-over-a-broker.md
- adr/0003-the-mesh-database-is-the-source-of-truth.md
---
# The mesh and its transport
Two things make a set of machines into a mesh: a database that holds every binding, and a
broker that carries every message. Neither is optional and neither is replaceable at present.
## The mesh database
One relational database holds the bindings. Its content divides cleanly:
| Holds | Describes |
|---|---|
| Node records | Which nodes exist, and each node's own properties — its name in the mesh, whether it carries a public name, its identity text |
| Assignments | Which node hosts which module, at which selection, and whether it starts automatically |
| Overrides | Per-node, per-module values that take precedence over anything the manifest generates |
| Mesh settings | Values every node reads — where the broker is, where the forge is, where the registry is |
| Grants | Which consumer holds which resource from which provider, with the credential |
The runtime loads this at startup. If the database cannot be reached it falls back to a local
cache and continues.
**The repository contains none of this.** It defines what exists; the database defines what
runs where. This is what makes the repository node-agnostic, and it is the property that lets
anything about the mesh be published at all.
### What the cache costs
Running from cache is the difference between a node that survives a database outage and one
that stops. It is the right trade and it has a cost that is worth naming: a node running from
cache looks identical to a node running from the database. There is no age on the cache and
nothing reports divergence, so a node can be running yesterday's assignment set indefinitely
without any signal that it is.
### Where the settings are
A mesh-level setting is a value every node needs and no node owns — the broker's location, the
forge's, the registry's. These live in the database rather than in any node's configuration,
so a node learns where the broker is from the mesh rather than from a file, and moving the
broker is a database change rather than a fleet-wide edit.
The circularity is real: a node must reach the database to learn where the broker is, and the
database is itself a module the mesh provisions. It is resolved by the initialisation script
that stands up the first node, which is the reason such a script exists separately from
everything else.
## The broker
Every node connects **outbound** to a single broker. Nothing ever connects to a node.
Each node declares a topic exchange named for itself and consumes from its own request queue.
A shared mesh exchange carries traffic addressed to no particular node — pipeline commands and
the events they emit.
Three message shapes, and only three:
- **Requests** expect a reply. This is how a capability on another node is called.
- **Commands** instruct that a stage of work be done. They are addressed by what is to be done
and consumed by whichever node is meant to do it.
- **Events** state that something happened, addressed to nobody. Anything interested subscribes.
### Consequences the design accepts
A node behind a household connection with no inbound route participates exactly as a publicly
named one does. This is the property the transport was chosen for.
A call to a node that is down **waits** rather than failing. Usually this is what is wanted. It
is also how the mesh's most confusing stalls happen: a command queued for a node that never
returns is a stall with no error anywhere, and the pipeline has produced this shape more than
once — an empty pipeline that never completes blocks every pipeline queued behind it.
Two consumers accidentally sharing one queue silently split the traffic between them, each
receiving half of what it expects. This has happened between a module's daemon and its
capability server.
The broker is a single point of failure and a single point of trust. Its credential is
mesh-wide, so rotating it is a mesh-wide operation, and doing it wrong has taken the broker
down.
## Reaching a capability on another node
A node hosts some capabilities and can reach the rest.
At startup, a node asks every peer what it hosts. For anything hosted elsewhere it creates a
local stand-in that forwards over the broker. For anything hosted both locally and elsewhere
it wraps the local one so a caller can name a target.
The effect is that a caller does not know where a capability runs. The important half is what
does **not** move: the work happens where the capability is, so its credentials never leave
that host. A remote call transports a request and a reply, never a secret.
Discovery happens at startup and is bounded by a short timeout. A peer that is slow or absent
at that moment is simply not discovered, and the node runs without that capability until it
restarts. Nothing re-discovers on a schedule.
## Names and reachability
Nodes address each other by names that resolve on the mesh's own overlay, not on whatever the
underlying network provides. A node's mesh name is its overlay address; its public name, if it
has one, is a separate fact used by things outside the mesh.
Two lessons are embedded in that separation, both learned the expensive way. A name resolved
by local multicast discovery introduces a delay and a failure mode that appears on one node and
not others, so mesh names are not multicast names. And a node must not pin its own public name
locally: the duplicate record breaks resolution for everything else that needs it.
02-DESIGN/00-as-is/02-modules-and-manifests.md
+113
View File
@@ -0,0 +1,113 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0002-everything-is-a-module.md
- adr/0006-schema-changes-are-numbered-migrations.md
- adr/0007-no-npm-workspace.md
---
# Modules, manifests and features
Everything the mesh installs is a module: a directory with a manifest. There is no second
mechanism.
## What a manifest declares
| Declares | Meaning |
|---|---|
| Identity | Name and version. **Version is owned by the builder** — a hand-edited version is a defect, and reviewers revert it. |
| Environment | Every variable the module reads, with how each is produced: a static default, a generated secret, a value pulled from the node's own record, or a template composed from the others. A variable not declared here is invisible to the mesh and will not be generated, injected or audited. |
| What it provides | The resource type this module can provision for others, and the network on which it is reachable. |
| What it requires | Resources it needs from other modules, and the mapping from each resource's connection fields onto its own environment variables. |
| Service shape | The primary container, and the data directories that must exist with the right ownership before it starts. |
| Exposure | The public names this module's interfaces answer on, declared portably so the reverse proxy configuration can be generated rather than written. |
| Images | Container images this module builds, so the pipeline builds and publishes them before publishing the module. |
## Features are the unit of work
A module is not the unit the pipeline addresses. A **feature** is.
A feature is a kind of content a module can carry: a service, a set of capabilities, a
long-running process, managed configuration files, migrations, firewall rules, an installable
application. One module can carry several.
Features are **detected from directory contents**, not declared. A module with a capabilities
directory has that feature; a module with a daemon directory has that one. An explicit
declaration was supported and is now discouraged, because a declared list and the directory it
describes drift, and the directory is the one that is true.
Every pipeline command and event names a feature. There is no per-module build.
### What detection costs
Detection makes the manifest shorter and the truth singular, and it makes the directory
structure load-bearing in a way that is not obvious from reading a manifest. Renaming a
directory changes what a module *is*, silently. The recurring failure is a hook named for a
feature the module does not carry: it is skipped without complaint, and the change it was
supposed to make simply never happens.
An unknown key in a manifest is likewise accepted in silence — which is how a firewall rule
can appear to restrict a port and restrict nothing (see
[`04-ISSUES/003`](../../04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md)).
## Kinds of module
The kinds are not a type system — they are what the detected features add up to.
- **A service module** carries a container definition. It gets a runtime directory, generated
environment, data directories, and is started under supervision.
- **A capability module** carries capabilities and no service. It contributes what a node can
do, locally and to its peers.
- **A flag module** carries nothing but a manifest. Its presence in a node's assignment is the
entire content: it gates behaviour elsewhere.
- **Combinations** are ordinary. A database module is a service *and* a capability provider
*and* a provisioner.
## Selections
A module can ship variants of the same feature and a node takes the one that fits it — a build
for one accelerator or another, a configuration for a public node or a private one. The
artifact stays selection-blind; the choice is a property of the assignment, held in the mesh
database.
This is one of the areas where behaviour has repeatedly diverged from intent, in both
directions: selection files that were never packaged into the artifact at all, and a stale
staged override on a node that silently won over the newly selected one. Both classes are
recorded in the knowledge base; both presented as "the change did not apply" with no error.
## Dependencies between modules
Modules depend on each other, above all on the shared library they all build against. There is
**no workspace** ([ADR 0007](../../adr/0007-no-npm-workspace.md)): each module is a standalone
package consuming published dependencies, including the mesh's own.
The pipeline resolves modules into dependency **levels** and completes a level before starting
the next, so a module always builds against its dependencies as just published.
The cost is a publish-and-consume round trip for every cross-package change, and the absence of
any repository-wide build. One thing that assumed a repository-wide build has stayed broken
since (see
[`04-ISSUES/005`](../../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md)).
## Persistent state
A module that owns state owns its migrations: numbered, written in the module's own language,
compiled with it, frozen once they have run anywhere, and idempotent so that re-running is safe
([ADR 0006](../../adr/0006-schema-changes-are-numbered-migrations.md)).
Two kinds exist and the distinction matters: migrations against the module's **own** local
state, and migrations against a **provisioned** resource, which run on the node that consumes
the resource rather than on the node that built the module.
## A documented rule with no enforcement
Every module exposing capabilities is documented as required to declare the mesh's core runtime
as a dependency. **Zero of the catalogue's modules do.**
This is recorded here rather than quietly corrected, because it is the clearest instance of the
rule this repository states about itself: a rule whose enforcement does not exist is
indistinguishable from a wrong one, and costs more, because people believe it. Whether the rule
or the catalogue is wrong has not been decided.
02-DESIGN/00-as-is/03-provisioning.md
+88
View File
@@ -0,0 +1,88 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0005-capabilities-are-provisioned-on-declaration.md
- adr/0004-managed-files-are-generated-never-edited.md
---
# Provisioning
A module states what it needs. The mesh makes it exist, generates the credential, records the
grant, and puts the values where the module will read them. Nobody writes a credential and
nobody writes a topology.
This is the mesh's core concern rather than its plumbing — the property everything else is
built on.
## The declaration
A **provider** declares the resource type it can create and the network on which that resource
is reachable from a container.
A **consumer** declares, per requirement: the provider module, the resource type, optionally a
name and a target node, and a mapping from the resource's connection fields onto its own
environment variables.
The consumer must also declare those variables as empty in its environment section. A mapped
field with no declared variable is dropped — the value is produced and then discarded, because
the generator only emits variables the manifest knows about.
## What happens
Inside the pipeline the sequence is orchestrated by the coordinator and is not optional:
1. The provisioner creates the resource and its credential, records the grant, and writes the
mapped values as database overrides.
2. The synchroniser regenerates the module's environment from those overrides.
3. Only then is the service started.
Each step waits for the previous one's event. A module that declares no requirements skips the
first step entirely — which is correct, and means the absence of provisioning is
indistinguishable from provisioning that did not run.
Outside the pipeline the same two steps exist as direct operations, for debugging. They are
not the normal path.
## What can be provisioned
Providers exist for relational databases of two kinds, an object store, a cache, message-broker
virtual hosts and access, an identity provider's clients, and a download category. Each returns
the connection fields a consumer maps from — host, port, user, password, and whatever else the
resource type implies.
A provider with no registered provisioner still records a grant, with an empty connection. This
is deliberate and easy to misread: the grant exists, so the requirement looks satisfied, and
nothing was created.
## Cross-node grants
A requirement may name the node whose provider should satisfy it. The grant records consumer
node and provider node separately, so a module on one node holding a database on another is
the ordinary case rather than a special one.
For a containerised consumer, the provisioner returns the provider's routable name rather than
a loopback address — the value has to be correct from **inside** a container on another
machine.
## Where this hurts
**Rotation has no fan-out.** A resource whose credential is shared by several consumers can be
rotated by provisioning a new one, and the peers holding the old credential are not told. This
has locked the mesh out of its own broker, and has caused a node's adoption to rotate a live
shared password without informing anything that held it. Granting is easy; regranting is not
modelled.
**A frozen password outlives its generation.** A generated password is written once. If the
resource's persistent data directory already exists from an earlier initialisation, the stored
credential and the generated one diverge, and the symptom is an authentication failure that
looks like a configuration error.
**Migrations against a provisioned resource run on the consumer's node**, not the build node,
and read the deployed artifact rather than the source tree. Both facts were wrong in the
implementation for a period during which new provisioning migrations silently never ran.
**A grant is not a check.** The record says a resource was provisioned. Nothing verifies it
still exists, still has the recorded credential, or is reachable from where the consumer runs.
02-DESIGN/00-as-is/04-delivery.md
+100
View File
@@ -0,0 +1,100 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0014-build-publish-and-deploy-are-three-silos.md
- adr/0013-an-artifact-is-build-output.md
- adr/0008-a-failed-step-fails-the-job.md
---
# Delivery — from a push to a running node
One trigger, three silos, and a fan-out point that is the most consequential boundary in the
mesh.
## The trigger
A push to the forge. The forge calls a webhook; the receiving module verifies its signature
and emits an event. The coordinator resolves which modules the pushed commits affect, orders
them into dependency levels, and creates a pipeline per level.
There is no second path. A manual trigger exists for a module the push detection missed, and
using it routinely is a sign the detection is wrong rather than a workflow.
Detection is the pipeline's most fragile input. It has failed for reasons that have nothing to
do with the change: a webhook truncating its commit list on a large merge, a forge address
whose port broke the module-path matching. The characteristic outcome is the bad one — **a
merge that created no pipeline, and nothing said so**.
## Three silos
Cardinality is the whole point, and the three differ
([ADR 0014](../../adr/0014-build-publish-and-deploy-are-three-silos.md)):
| Silo | Runs | Where | Does |
|---|---|---|---|
| **build** | once per module feature | the build node | compile and bundle into a self-contained output |
| **publish** | once per module feature | the build node | package that output and upload it; a package-registry feature publishes here |
| **deploy** | once per module feature **per node** | every assigned node | install, configure, start, verify |
Commands and events are addressed per feature, not per module.
Build hands over a **staged tree**, not a package. Packaging belongs to publish, so a failed
upload retries by re-packaging rather than by re-sending something stale, and build never needs
to know how each module composes its artifact. The handover is a tree in a known location,
because the build's own working directory is reference-counted and may be gone by the time a
later stage runs.
## The artifact
The artifact is **build output** — compiled and bundled with its dependency graph inlined —
never a filtered copy of source ([ADR 0013](../../adr/0013-an-artifact-is-build-output.md)).
A deploy is extract-and-run and touches no network.
The consequence is the whole cost of the decision: **anything not in the build output does not
ship.** Every file kind had to be brought into that rule separately, and each was discovered by
something silently not happening after deploy — migrations reading a source layout, provisioning
scripts reading a source layout, selection files never packaged at all.
## The fan-out, and the build node
After publish, work fans out to every assigned node. The build node is the only node that has
already passed through two silos when this happens, and that asymmetry has its own defect
class: anything advancing a node's stage must account for **both** pre-fan-out stages. Code
that knew only about the first parked the build node forever while every other node deployed
cleanly — and the recovery sweeper, which knew the same subset, reported nothing to recover.
A recovery mechanism that knows less than the thing it guards is worse than none, because it
reports success over a stall it cannot see.
## Levels
A level completes before the next begins, so a module builds against its dependencies as they
were just published. The shared library is at level zero, which means anything that breaks it
breaks the first module of every cascade.
## What green proves
**A green pipeline proves transport, not effect.** The stages report that a message was
dispatched and accepted, which is not the same as the thing being running, correct, or present.
This is the mesh's most consistent failure shape and it is not incidental to the design — it is
what the stage reporting currently measures. Documented instances include a service reported
started when the container command merely returned, an image pull failure that did not fail the
deploy, a package install that 404ed from every mirror while the job went green (see
[`04-ISSUES/001`](../../04-ISSUES/001-failed-package-install-reports-success/00-report.md)),
and a node left on old code after a failed artifact download with a version marker that had
already advanced.
A verify stage exists to close this gap. It has been built and, for a period, was never
scheduled, because the coordinator's stage list did not include it.
## What is not covered
The end-to-end harness for this pipeline has not built since the workspace was removed, and
nothing reports that nothing runs it
([`04-ISSUES/005`](../../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md)). The
pipeline's coverage is currently assumed rather than checked — which is the same class of claim
this repository exists to make people stop making.
02-DESIGN/00-as-is/05-runtime-and-installation.md
+102
View File
@@ -0,0 +1,102 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0002-everything-is-a-module.md
- adr/0011-the-installer-owns-linking.md
---
# The node runtime, and how a node comes into being
Every node runs the same runtime. What differs is its assignment.
## Two modes, coexisting
The runtime runs in two modes at once on any node that needs both.
**Daemon** mode is a headless consumer: it connects to the broker, consumes the node's request
queue, routes each request to a local capability, and emits the node's lifecycle events. This
is what makes a node a participant — it is reachable whether or not anyone is logged in.
**Interactive** mode exposes the node's capabilities to a session on that machine over a local
protocol. Its capability surface is larger, because it includes stand-ins for every capability
discovered on peers.
The two are the same code with the same catalogue. A capability is written once and is
available to both.
## Anatomy naming, and what it obscures
The runtime's components are named after brain anatomy: an entry point that bootstraps, a
headless listener, an interactive surface, an installer daemon, and a provisioner daemon.
This is the mesh's most-cited naming problem and it belongs in the as-is layer because it is
what a reader will actually encounter. The names are evocative and describe nothing: the most
suggestive word in the system names the node runtime, and the component whose manifest says
"mesh messaging" is documented elsewhere as the interactive runtime. Anatomy makes attractive
names and poor boundaries.
[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) replaces this with names
taken from what each part owns. Until then, this is the vocabulary in the code.
## Starting a module
For each assigned module the runtime, at startup:
1. Reads the manifest, if there is one — a flag module has nothing to read.
2. Skips a module's capabilities if a variable they require is unset. This is quiet by design
and hard to distinguish from a module that has no capabilities.
3. Loads the capabilities the module carries.
4. For a service module, ensures it is installed and running.
Installation is idempotent and does the unglamorous work: ensure the runtime directory,
reconcile the link from the catalogue's definition into it, generate the environment, run any
outstanding local migrations, create data directories with the right ownership, then start the
service under supervision.
**The installer is the only thing that creates a link** ([ADR
0011](../../adr/0011-the-installer-owns-linking.md)). It reconciles rather than assumes: a
missing link is created, a stale one repointed, and a real file found where a link belongs is
adopted into the node's override area and replaced. Nothing else — not a hook, not a fix, not a
person debugging — creates one.
## Supervision
Services run under the host's init system via a templated unit, one instance per module. It is
a thin layer: the unit starts and stops a container group.
Whether the mesh keeps this, drops the per-module layer, containerises the daemons, or writes
its own supervisor is **open** — costed in research effort 003 and deliberately undecided. It
no longer gates anything.
Two failures worth knowing about, both in the shape of "the change did not apply". A
per-instance copy of the unit template shadows the template, so edits to the template do
nothing. And a session-scoped one-shot job loses the environment it was given, because the
import is one-time and not persisted.
## How a node comes into being
Three bootstrap scripts, and which one runs depends on the situation:
- **First node.** Nothing exists yet, so the script stands up the database the rest of the
mesh reads from, publishes the catalogue, and starts the mesh. This resolves the
circularity of a mesh whose source of truth is itself a provisioned module.
- **Joining.** The node registers, takes its assignment from the database, and syncs.
- **Rescue.** A node that cannot reach the mesh is brought back far enough to.
Bringing a node into being is therefore a **database operation with a script attached**, not a
checkout. There is no per-node content in the repository to copy.
Adoption of a pre-existing machine's configuration was the original path and is now a legacy
one, explicitly out of scope for the lab
([`01-to-be/01-end-to-end-testing.md`](../01-to-be/01-end-to-end-testing.md)).
## Node identity
Each node carries an identity text in its own record, which the daemon writes onto the node at
startup so that a session on that machine knows which node it is on and how that node
presents itself. It carries identity only; shared rules live separately.
Like everything else derived onto a node, it is generated and not edited there.
02-DESIGN/00-as-is/06-configuration-and-secrets.md
+86
View File
@@ -0,0 +1,86 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0004-managed-files-are-generated-never-edited.md
- adr/0005-capabilities-are-provisioned-on-declaration.md
---
# Configuration and secrets
Every value a module reads at runtime comes from a file on a node's disk. Every one of those
files is **generated**.
## The rule
A managed file is derived from the mesh database. A synchroniser rewrites it when the values
behind it change. The write path is the mesh operation that owns the value; the file is an
output ([ADR 0004](../../adr/0004-managed-files-are-generated-never-edited.md)).
An edit to a managed file survives until the next synchronisation and is then overwritten
silently, taking whatever it was fixing with it — bringing back the bug the edit had removed,
with a delay, and with no error to connect the two events.
There is a way to ask whether a given file is managed. That question has to be asked, because
the answer is not visible from the file.
## What is managed
Generated environment files for each module, service definitions in each module's runtime
directory, managed configuration files a module declares, and node-level settings. The list is
not a category — it is whatever a synchroniser claims, which is why the question is asked of
the tooling rather than answered from a rule.
## How a value is decided
Values resolve by precedence, highest first:
1. **A database override** — set deliberately, or written by a provisioner.
2. **The value already in the generated file** — preserved for anything without an override.
3. **A generated value** — a random secret, a template composed from other variables, or a
value pulled from the node's own record.
4. **The manifest default.**
Two consequences follow, and both are subtle enough to have caused confusion.
The second rule is what keeps a generated password **stable** across regenerations. It is not
an oversight; without it every regeneration would issue a new secret and break whatever holds
the old one.
The same rule means that **changing a manifest's default does not change anything already
using it**. The existing file's value wins. The new default reaches only installations that
never had one.
Removing a declaration is worse than changing it: the old override row and the file it produced
are both left behind. Configuration is additive in practice, whatever the manifest says.
## Secrets
Generated secrets are produced by the mesh, never authored. Provisioned credentials arrive as
database overrides written by the provisioner and are marked as such, so they can be
distinguished from a deliberate override and cleaned up when the grant is removed
([ADR 0005](../../adr/0005-capabilities-are-provisioned-on-declaration.md)).
Nothing in the repository contains a credential. The repository has no per-node content at all,
which is what makes that guarantee structural rather than a matter of care.
Two known weaknesses, both recorded rather than resolved:
**Generated environment files were world-readable.** The mode passed at write time only applies
when the file is created, so regeneration left the previous mode in place. The class of bug is
worth remembering beyond the instance: a permission set at creation is not a permission
maintained.
**Rotation is not a mesh operation.** Secrets can be generated and granted; there is no
mechanism that rotates one and informs everything holding it. Where a rotation has been done,
it has been done by hand, and doing it wrong has taken services down.
## Node-level and mesh-level values
A node-level value applies to everything on one node. A mesh-level value applies everywhere and
is read by every node — the broker's location is the canonical example, and a wrong one is how
a mesh fails to form.
Neither is a file that anyone edits. Both are database records that produce files.
02-DESIGN/00-as-is/07-knowledge.md
+78
View File
@@ -0,0 +1,78 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions: []
---
# Knowledge
The mesh keeps two knowledge stores. They are not redundant, and knowing which is which is the
difference between finding an answer in one search and rediscovering it over several hours.
## The operational memory
A store of operational notes, written and read by whoever — human or agent — is working. Each
note is a slug and a body: how something works, what went wrong, what the fix was, what
assumption turned out to be false.
It is indexed on **symptoms**. The entry someone needs is usually titled after the error they
are staring at, which is why the standing instruction is to search the literal error text
before forming a hypothesis rather than after one fails.
Its content is overwhelmingly the record of previous debugging: a large body of
troubleshooting entries, module conventions, and standing notes about work that is open. It is
the mesh's institutional memory of *what has already gone wrong*.
The cost of skipping it is documented in the mesh's own record: entries have been rediscovered
from scratch, over hours, in sessions where the search was skipped because the trail felt
confident. It fires hardest on familiar ground, not unfamiliar ground.
## The structured archive
A second store, structured rather than flat: spaces, pages, revisions, tiers, and full-text
search. Where the operational memory is a note, this is a document with an owner and a
lifecycle.
Content is promoted through tiers — private, then team, then platform — with a librarian agent
owning approval and promotion at the boundary. Proposals to edit are reviewed rather than
applied.
This is where the mesh's **governed** documents live, including the constitution injected into
design sessions ([ADR 0009](../../adr/0009-the-mesh-is-governed-by-a-constitution.md)).
## Why both
The distinction is by lifecycle, not by subject.
| Operational memory | Structured archive |
|---|---|
| Written the moment something is learned | Written deliberately, reviewed |
| Flat, symptom-indexed | Structured, tiered, owned |
| Anyone writes; nothing approves | Promotion is approved |
| Truth is "this happened" | Truth is "this is agreed" |
Collapsing them would cost one of the two properties: either every hard-won note waits for
review, or governed documents can be changed by anyone mid-incident.
## Where this repository sits
This repository is a third thing, and the objection was raised when it was created: a fourth
knowledge system repeats the mistake the split was made to fix.
The answer given was **indexing, not location** — that these documents are indexed into the
knowledge base so that a symptom search returns them alongside everything else. One source,
many surfaces.
**That indexing does not currently exist.** A search for this repository's content returns
nothing. The claim is load-bearing for the decision to separate the repository at all, and
until it is true, this repository is exactly the fourth knowledge system the objection
described. Recorded here rather than in the ledger, because it is a statement about how the
mesh's knowledge actually works today.
## The librarian
A single agent owns the archive's approvals and promotions. Its approval capabilities have at
times not been reachable as tools, which does not affect the operational memory but does mean
promotion stops silently — the store keeps accepting proposals that nothing can approve.
02-DESIGN/00-as-is/08-agents-and-work.md
+88
View File
@@ -0,0 +1,88 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0012-agents-are-persistent-employees.md
- adr/0009-the-mesh-is-governed-by-a-constitution.md
---
# Agents and work
The mesh does a large share of its own design and implementation. Agents are how, and the
model they run under is the employee model, not a worker pool.
## An agent is an employee
An agent is a singular named identity with a home node, a workspace on that node, accumulating
memory, and an explicit lifecycle
([ADR 0012](../../adr/0012-agents-are-persistent-employees.md)).
| Property | Meaning |
|---|---|
| Lifecycle state | Active, draining, or retired. Retired agents are kept. |
| Home node | Where its workspace lives. One node per agent. |
| Session cap | How much work it may hold at once. **Concurrency is a property of the agent, not a count of copies.** |
| Kind | Whether it is hirable, or is a node's own agent and exempt from hiring |
The verbs are explicit: an agent is **hired** onto a node, **reassigned** only while idle, and
**retired** by draining first — forcing it is a deliberate act that aborts work in flight.
Surge capacity lives inside the model rather than against it. A template agent is a blueprint
with no life of its own; when a queue grows past a threshold it is cloned into a real agent
with a lifetime, which drains and retires when that expires. A temporary employee is still an
employee.
Because there is a continuing subject, **policy becomes possible**: an agent that violates a
rule can be warned, and a warned agent can be dismissed. A pool cannot be warned.
## Some agents are human
There is one kind of participant. What differs is **modality** — a non-human agent acts through
a spawned session and the record; a human agent acts through a shell, a desktop, or a message.
Both hold identity, both act, both accumulate memory.
The mesh does not currently record modality completely. Which user, on which node, a human
agent acts as is **required by the model and not stored** — an open question carried over from
[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md).
## Work
Work is expressed as tasks moving through workflows. A workflow names the states a kind of work
passes through and what must be true to leave each one; a task carries its acceptance criteria
and its trail.
Several workflow shapes exist for different sizes of work — a single implementation, a larger
container of related work, and shapes that add analysis or design stages ahead of
implementation.
The area's characteristic defects are **transition** defects rather than logic defects: a task
bouncing between review and implementation because a guard was evaluated on stale state, a
result that cannot be recorded in the same act as the transition it justifies. The workflow
engine's correctness is about atomicity, and that is where it has been wrong.
## Meetings
Some work is decided in a **meeting**: several agents in turns, with distinct roles, over a
template that names the phases.
This is where governance meets execution. The constitution is injected into every eligible
meeting turn — agents do not fetch it, it arrives — and a check phase verifies the meeting's
output against it before the meeting may proceed
([ADR 0009](../../adr/0009-the-mesh-is-governed-by-a-constitution.md)). A named violation
blocks progress.
Meeting turns run on the orchestrator's node regardless of where the participating agents are
pinned. That is a known divergence between the model and its execution, not a design intent.
## What this rests on that is not built
The work domain shares one large schema with several other domains. That is the concrete
instance of a rule stated in [`how-we-build.md`](../../00-GENESIS/how-we-build.md) — *contexts
integrate through the record, never through a shared schema* — being violated by the mesh's
own largest component, and it is the reason work that belongs to one domain keeps having to be
implemented in another.
[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement.
Until it does, this is the shape.
02-DESIGN/00-as-is/09-interfaces-and-observability.md
+78
View File
@@ -0,0 +1,78 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0001-nodes-communicate-over-a-broker.md
- adr/0008-a-failed-step-fails-the-job.md
---
# Interfaces and observability
How the mesh is reached, and how anyone can tell what it is doing.
## Capabilities are the primary interface
The mesh's primary interface is not a web console. It is a set of **capabilities**, exposed to
a session and callable in language.
A capability is contributed by a module and is available on any node, wherever it actually
runs: local ones directly, remote ones through a stand-in created at startup that forwards over
the broker. The caller does not know the difference, and the credentials never move.
This is the mesh's stated vision made concrete — an agent states an intent and the mesh works
out which node holds the thing. It is also why a capability's **schema** is load-bearing in a
way that is easy to underestimate: a parameter name that collides with the transport's own
reserved names breaks the call, and a validation-library version mismatch has silently dropped
every argument while the call still appeared to succeed.
## The board
A web interface presents the mesh — nodes, modules, pipelines, agents, work. It is a **view**.
Its own guidance is that shared logic belongs in the mesh's library rather than inline in the
board, precisely so the board does not quietly become a second implementation of the mesh's
rules.
## Public exposure
Nodes carrying a public name run a reverse proxy as the sole entry point. A module declares the
names its interfaces answer on, portably, and the proxy's configuration is **generated** from
those declarations rather than written — generated files are marked as such and anything
hand-written beside them is left alone.
Nodes without a public role use a local equivalent with locally-trusted certificates. The
generation step degrades quietly on a node with no proxy, which is intended and is one more
place where "nothing happened" is the correct outcome and looks identical to a failure.
Certificate issuance currently always targets the public authority's production endpoint,
which consumes real quota for every experiment
([`04-ISSUES/004`](../../04-ISSUES/004-certificate-issuance-targets-production/00-report.md)).
## Health
Nodes run checks and report. The mesh's health surface answers whether things are up.
What it does **not** answer is whether they are correct, and that gap is the recurring theme of
this whole system: the deploy path reports transport rather than effect, so absence reads as
success. A check that confirms a service is running does not confirm the service is running the
code that was just deployed, and a node has been left on old code with a version marker that
had already advanced.
## Thoughts
Every node's daemon runs a periodic loop that surfaces observations from that node's own
context. They are stored in the mesh and can inform a session or trigger action.
It is the one part of the mesh that is not request-driven — the mesh noticing things rather
than being asked.
## The honest summary
Observability tells you the mesh is **up**. Establishing that it is **right** currently means
reading the operational record and checking by hand.
That is the gap the lab is designed to close
([`01-to-be/01-end-to-end-testing.md`](../01-to-be/01-end-to-end-testing.md)): a place where a
change can be run end to end and a verdict produced, cheaply enough that producing one is
routine.
02-DESIGN/00-as-is/10-module-catalogue.md
+90
View File
@@ -0,0 +1,90 @@
---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- adr/0002-everything-is-a-module.md
- adr/0010-applications-live-in-their-own-repository.md
- adr/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](../../adr/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](../../adr/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](../../adr/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](../../adr/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.
02-DESIGN/00-as-is/README.md
+30
View File
@@ -0,0 +1,30 @@
# 02-DESIGN / 00-as-is
The mesh as it stands. These documents describe what runs, including the parts nobody would
choose again — an as-is layer that only records the good decisions is a brochure.
They are written from the implementation and from the operational record, not from intent.
Where the two disagree, the implementation wins and the disagreement is stated.
| Document | Covers |
|---|---|
| [`00-overview.md`](00-overview.md) | The whole in one pass — what a node is, what a module is, how work reaches it |
| [`01-mesh-and-transport.md`](01-mesh-and-transport.md) | The mesh database, the broker, discovery, and how a call reaches another node |
| [`02-modules-and-manifests.md`](02-modules-and-manifests.md) | The module, the manifest, and features as the unit of work |
| [`03-provisioning.md`](03-provisioning.md) | Declared requirements, provisioners, credentials, and cross-node grants |
| [`04-delivery.md`](04-delivery.md) | Push to running: the three silos, levels, and what a green pipeline proves |
| [`05-runtime-and-installation.md`](05-runtime-and-installation.md) | The node runtime, its modes, and how a node comes into being |
| [`06-configuration-and-secrets.md`](06-configuration-and-secrets.md) | Managed files, value resolution, and where secrets live |
| [`07-knowledge.md`](07-knowledge.md) | The two knowledge stores, and what each is for |
| [`08-agents-and-work.md`](08-agents-and-work.md) | Agents as employees, tasks, workflows, and the meeting model |
| [`09-interfaces-and-observability.md`](09-interfaces-and-observability.md) | How the mesh is reached and watched — tools, board, proxy, health, thoughts |
| [`10-module-catalogue.md`](10-module-catalogue.md) | The catalogue's shape, and what its shape says |
## What these documents are not
They are not a runbook. Operational procedure — how to fix one occurrence of something — lives
in the knowledge base, which is indexed on symptoms and is the right place to search when
something is broken.
They are not exhaustive. A subsystem is described to the depth at which its **design** is
visible; below that is code.
02-DESIGN/00-work-breakdown.md → 02-DESIGN/01-to-be/00-work-breakdown.md
+10 -2
View File
@@ -1,6 +1,14 @@
---
layer: to-be
status: designed
code: [hal]
updated: 2026-08-23
decisions: [adr/0015-mesh-brokers-nodes-host-agents-think.md]
---
# Work breakdown — the decomposition
How ADR 0001 gets built, in what order, and where a human must look.
How [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) gets built, in what order, and where a human must look.
Ordering is not preference. Each phase removes a constraint the next one needs gone.
@@ -74,7 +82,7 @@ The decomposition is impossible while a feature is a singleton per module.
| # | task | done when |
|---|---|---|
| 1.1 | ADR 0002 — named features, per-node opt-in | accepted |
| 1.1 | Decision record — named features, per-node opt-in (next free number) | accepted |
| 1.2 | Manifest: declared `features:` with type + directory | a module declares two of one kind and both build |
| 1.3 | Selection: `always` / flavor-selected / `optional` | a node installs a subset; artifacts stay flavor-blind |
| 1.4 | `requires:` moves onto the feature | a schema feature's database is not provisioned where the feature is not installed |
02-DESIGN/01-end-to-end-testing.md → 02-DESIGN/01-to-be/01-end-to-end-testing.md
+9 -1
View File
@@ -1,3 +1,11 @@
---
layer: to-be
status: designed
code: [hal]
updated: 2026-08-23
decisions: [adr/0016-a-lab-node-is-a-virtual-machine.md]
---
# End-to-end testing
**What is under test is a module.** The mesh is the harness.
@@ -350,6 +358,6 @@ reads credentials from host paths, because there is nowhere else to put a mesh.
is, a workstation stops being collateral.
**The supervision question stops gating anything.**
[`01-RESEARCH/003-service-supervision`](../01-RESEARCH/003-service-supervision/analysis.md)
[`01-RESEARCH/003-service-supervision`](../../01-RESEARCH/003-service-supervision/analysis.md)
remains open on its own merits — and once this exists, its options are cheap to try rather
than expensive to argue about.
02-DESIGN/01-to-be/README.md
+22
View File
@@ -0,0 +1,22 @@
# 02-DESIGN / 01-to-be
The mesh being built toward. Every statement here traces to a record in
[`adr/`](../../adr/); nothing arrives by drafting.
A document here describes an intention. What currently runs is in
[`00-as-is/`](../00-as-is/), and the two are never merged — when something ships, the as-is
document is written and this one's status becomes `implemented`.
| Document | Covers | Rests on |
|---|---|---|
| [`00-work-breakdown.md`](00-work-breakdown.md) | How the decomposition gets built, in what order, and where a human must look | [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) |
| [`01-end-to-end-testing.md`](01-end-to-end-testing.md) | The lab: a real mesh a change can be run against before it reaches nodes | [ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md) |
## Not yet written
- **The eight bounded contexts.** [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md)
decides the decomposition; the per-context specifications do not exist yet. The work
breakdown says in what order they are needed.
- **Domain grouping outside the core.** [ADR 0017](../../adr/0017-modules-outside-the-core-are-grouped-by-domain.md)
settles the principle and explicitly does not settle the domain list. That is a research
effort, not a design document, until it concludes.
02-DESIGN/README.md
+46 -5
View File
@@ -2,9 +2,50 @@
The authoritative specification. Implementation is built against what is written here.
A document enters this folder only after the decision behind it is recorded in
[`adr/`](../adr/) and the research that produced it is marked `GRADUATED`.
## Two layers
Empty for now: the decomposition in ADR 0001 is decided but not yet specified. The first
entries will be the per-context designs — `hal/mesh` brokering, the `hal/stream` record,
and the feature model that `hal/delivery` owns.
| Folder | What it is |
|---|---|
| [`00-as-is/`](00-as-is/) | **The mesh that exists today.** Shipped behaviour, described as it is — including behaviour nobody would choose again. |
| [`01-to-be/`](01-to-be/) | **The mesh being built toward.** Every statement traceable to a record in [`adr/`](../adr/). |
They are never mixed. A statement about the future does not belong in an as-is document, and
an as-is document is never edited to describe an intention.
When a to-be design ships, it **does not move**. Its as-is counterpart is written or updated,
the to-be document's status becomes `implemented`, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
## Frontmatter
Every design document (not the READMEs) carries:
```yaml
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: [] # owning code repo(s), from 00-GENESIS/repos.md
updated: YYYY-MM-DD # date of the last status change, not of text edits
decisions: [] # adr/ records this document rests on
---
```
For an as-is document, `status: implemented` is the normal state — it describes something that
runs — and `code:` names where that implementation lives.
Status changes when **implementation state** changes, never because design text was edited. An
`implemented` claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is `in-progress`.
Cross-cutting views are generated from this frontmatter by the `hal-status` skill and never
written to disk.
## What belongs here
Functional analysis, architectural description, and specification — **prose and diagrams
only, no code**. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in [`adr/`](../adr/)
and the research that produced it is closed.
Subfolders are encouraged where a layer grows enough to need them.
04-ISSUES/001-failed-package-install-reports-success/00-report.md
+49
View File
@@ -0,0 +1,49 @@
---
status: open
opened: 2026-08-22
located-in: []
fixed-by:
amended-design:
---
# 001 — A failed package install does not fail the job
## Symptom
A module declared a package. The install produced, from every mirror:
```
error: failed retrieving file … 404
```
followed by:
```
-> error installing repo packages
```
The prepare job then reported **success**. The package is absent; the pipeline is green.
## Why this matters more than one missing package
The first thing the lab work asked the mesh to install demonstrated the exact fault the lab
exists to catch — a step that failed, reported success, and left the next step to run against
state that was never produced.
It is also a direct violation of a decision already taken and recorded:
[ADR 0008](../../adr/0008-a-failed-step-fails-the-job.md) says a step that fails must fail the
job. That record notes the rule is applied instance by instance and enforced by no mechanism.
This is an instance where it was never applied.
## Evidence
- Observed 2026-08-22 while declaring the virtualisation package required by
[ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md).
- A fix is written and open as a pull request, unmerged since 2026-08-20.
## Open questions
- Why is the failure swallowed — is the exit status discarded, or never checked?
- Is this specific to package installation, or does the surrounding stage swallow every
non-zero exit?
- The fix has been open for two days. What is the review path for a change of this class?
04-ISSUES/002-stale-package-index-fails-silently/00-report.md
+40
View File
@@ -0,0 +1,40 @@
---
status: open
opened: 2026-08-22
located-in: []
fixed-by:
amended-design:
---
# 002 — A declared package can fail purely because the node's index is stale
## Symptom
A package install ran without first synchronising the node's package index. It therefore
requested a version the mirrors had already superseded, and received a 404 from every one of
them.
The package exists. The declaration is correct. The node's view of what exists is old.
## Why this matters
The failure has nothing to do with the module, the manifest or the mirror. It is a property of
when the node last synchronised, which nothing in the mesh manages or reports. Two nodes given
the same declaration on the same day can produce different outcomes, and neither says why.
Combined with [issue 001](../001-failed-package-install-reports-success/00-report.md), the
failure is not only environmental but silent: today the node ends up without the package and
the job is green.
## Evidence
- Observed 2026-08-22, same declaration as issue 001.
- Documented as a recurring shape in the knowledge base under package installation failures,
where it is recorded as appearing in two disguises.
## Open questions
- Should the mesh own package-index freshness as a node property, the way it owns module
versions — or is an index sync part of the install step?
- A partial sync is unsafe on the platform in use; a full upgrade is the only sanctioned fix.
Does that make index freshness a scheduled node concern rather than a pipeline one?
04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md
+40
View File
@@ -0,0 +1,40 @@
---
status: open
opened: 2026-08-22
located-in: []
fixed-by:
amended-design:
---
# 003 — A firewall rule's `scope:` is read by no code
## Symptom
Five module manifests declare a `scope:` key on firewall rules. The key is not part of the
firewall rule type and nothing reads it. Real scoping is expressed by a different field.
A manifest can therefore appear to restrict a port and restrict nothing.
## Why this matters
This is the failure mode [`how-we-build.md`](../../00-GENESIS/how-we-build.md) names directly:
*an unenforced rule is indistinguishable from a wrong one, and costs more, because people
believe it.* Here it is worse than unenforced — the declaration reads as a restriction, so a
reviewer checking whether a port is scoped will find that it is, and be wrong.
It also says something about the manifest as a whole: an unknown key is accepted silently. Any
misspelled or invented key behaves this way, and this one was found by reading rather than by
any check.
## Evidence
- Five manifests carry the key. Zero code paths consume it.
- Recorded as an observation on 2026-08-22.
## Open questions
- Should the manifest reject unknown keys outright? That is the general fix; this is one
instance of it.
- Were the five declarations intended to restrict something that is currently open? Each needs
checking against what the node actually exposes — the declaration cannot be trusted either
way.
04-ISSUES/004-certificate-issuance-targets-production/00-report.md
+37
View File
@@ -0,0 +1,37 @@
---
status: open
opened: 2026-08-22
located-in: []
fixed-by:
amended-design:
---
# 004 — Certificate issuance always targets the authority's production endpoint
## Symptom
The reverse proxy sets no staging endpoint for its certificate resolver. Issuance therefore
goes to the public authority's production endpoint in every case, including experiments.
## Why this matters
Production issuance is rate-limited per domain and per account. Every certificate experiment on
a real node consumes quota that is not replenished quickly, and exhausting it is not
recoverable by retrying — it removes the ability to issue a certificate anyone actually needs.
The consequence lands hardest on exactly the work most likely to iterate: standing up a new
node, changing how names resolve, or testing the lab's certificate authority split
([ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md)).
## Evidence
- The resolver configuration declares no staging endpoint.
- Observed 2026-08-22.
## Open questions
- Should the endpoint be a node property — production for nodes serving real traffic, staging
everywhere else — rather than a fixed proxy setting?
- The lab issues its own certificates and so does not consume public quota at all. Does that
make this a problem only for experiments run outside the lab, and therefore an argument for
running them inside it?
04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md
+47
View File
@@ -0,0 +1,47 @@
---
status: open
opened: 2026-08-22
located-in: [hal]
fixed-by:
amended-design:
---
# 005 — The end-to-end pipeline harness has not built since the workspace was removed
## Symptom
The repository's end-to-end pipeline test harness depends on a workspace that no longer
exists. It has not been buildable since 2026-06-04. Nothing runs it, and nothing reports that
nothing runs it.
## Why this matters
The delivery pipeline is the mesh's most consequential machinery — every module reaches every
node through it — and its only end-to-end coverage has been silently dead for over two and a
half months.
That interval is not incidental. Several of the pipeline's most expensive defects landed
inside it: packaging that was never actually split from build, migrations and provisioning
scripts reading a source layout that no longer ships, selection files never packaged at all.
Whether this harness would have caught any of them is unknown — which is itself the point. The
coverage was assumed, not checked.
## Evidence
- The workspace was removed by pull request #240 on 2026-06-04
([ADR 0007](../../adr/0007-no-npm-workspace.md)).
- The harness has not built since that date.
- Recorded in the knowledge base as a standing entry, not as a fixed incident.
## Relationship to the lab
[`02-DESIGN/01-to-be/01-end-to-end-testing.md`](../../02-DESIGN/01-to-be/01-end-to-end-testing.md)
designs end-to-end testing on a lab mesh, which would replace this harness rather than repair
it. That is a reason to decide its fate deliberately, not a reason to leave it broken and
unmentioned: until the lab exists, this is the coverage the pipeline is presumed to have.
## Open questions
- Repair, or retire in favour of the lab? Leaving it in the repository unbuilt is the one
option that keeps the false impression of coverage.
- Was anything relying on it, or had it already stopped running before the workspace removal?
04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md
+57
View File
@@ -0,0 +1,57 @@
---
status: open
opened: 2026-08-23
located-in: [hal, hal-hq]
fixed-by:
amended-design:
---
# 006 — This repository is not indexed into the knowledge base, and the claim that it is holds up a decision
## Symptom
[`README.md`](../../README.md) states, as the answer to the objection against creating this
repository:
> 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.
Searching the knowledge base for this repository's content returns nothing.
## Evidence
Verified 2026-08-23, two searches against the mesh's operational memory:
| Query | Result |
|---|---|
| The full title of a decision record in this repository | No results |
| A distinctive phrase from the decision ledger | No results |
No entry, no partial match, no stale copy. The indexing does not exist and appears never to
have existed.
## Why this is an issue and not a task
The claim is **load-bearing**. Decision 27 separates HQ into its own repository, and the
objection it answers was that a fourth knowledge system repeats the mistake the mesh's
knowledge consolidation was created to fix. The recorded answer is *"indexing, not location"* —
that the split is safe **because** these documents remain searchable alongside everything else.
Without the indexing, the objection stands unanswered and this repository is precisely the
fourth knowledge system it was argued not to be. Either the indexing is built, or decision 27's
reasoning is amended to something that is true.
It is also, exactly, the failure this repository names in its own rules: a document stating a
rule about the mesh must say how the rule is checked. This one stated a mechanism and nobody
checked it — including in the same commit that wrote the rule.
## Open questions
- Where would the indexing run? The operational memory is written through a mesh capability;
is this a periodic sync of a repository into it, or a search surface that reads the
repository directly?
- Which store — the flat symptom-indexed memory, the structured archive, or both? They have
different lifecycles ([`02-DESIGN/00-as-is/07-knowledge.md`](../../02-DESIGN/00-as-is/07-knowledge.md)),
and this content is governed rather than incidental.
- Public repository, private mesh: the sync direction must not become a path for mesh-specific
content to arrive **into** these documents.
04-ISSUES/README.md
+46
View File
@@ -0,0 +1,46 @@
# 04-ISSUES
The front door for "something is wrong" at the level of the mesh's design or governance.
Diagnosis happens here, where the whole mesh is in view; the fix lands in the owning code
repository.
## What belongs here
| Belongs here | Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| The owner is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
The knowledge base already holds the operational record and is indexed on symptoms. **This
folder is not a second copy of it.** An issue here is a question HQ must *answer*; an entry
there is an incident someone must *clear*. An issue whose answer is a general lesson belongs in
both.
## Structure
```
NNN-short-name/
00-report.md the symptom as observed, with the evidence; status in frontmatter
01-diagnosis.md the investigation trail, dated, including what was ruled out
```
## Frontmatter, on `00-report.md`
```yaml
---
status: open | diagnosing | located | resolved | wontfix
opened: YYYY-MM-DD
located-in: [] # owning repo(s) or module(s), filled by diagnosis
fixed-by: # pull request or commit reference, filled at resolution
amended-design: # design doc path, when the root cause was a design gap
---
```
## Rules
- Anyone may open an issue. No localisation is required to report one.
- The full flow is playbook [`00-GENESIS/process/03-issues.md`](../00-GENESIS/process/03-issues.md).
- Closed issues are never deleted — they are the mesh's symptom-to-component memory.
- `wontfix` is legitimate and requires a sentence saying why.
AGENTS.md
+50
View File
@@ -0,0 +1,50 @@
# Agent instructions — hal-hq
This repository is the source of truth for the HAL mesh's mission, research, design and
decisions. Implementation lives in the code repositories (see
[`00-GENESIS/repos.md`](00-GENESIS/repos.md)).
Before changing anything here, read the playbooks in
[`00-GENESIS/process/`](00-GENESIS/process/) — every workflow (research, graduation, design
amendment, issues, build handoff, constitution sync) is documented there, and agents operate
through them. Thin skills in `.claude/skills/` wrap these playbooks for invocation
(`hal-new-research`, `hal-graduate`, `hal-new-issue`, `hal-diagnose`, `hal-amend-design`,
`hal-handoff`, `hal-sync-constitution`, `hal-status`); each defers to its playbook as
authoritative and adds only the mechanical scaffolding.
## Ground rules
- **Markdown only.** No new top-level folders without explicit confirmation.
- **Status lives in YAML frontmatter** — on research overviews (`status`, `became`), design
docs (`layer`, `status`, `code`, `updated`), issue reports (`status`, `located-in`,
`fixed-by`, `amended-design`) and decision records (`status`, `date`, `deciders`).
Never create a central status file; cross-cutting views are generated from frontmatter.
- **`adr/` records are immutable.** Supersede with a new record; never edit meaning. Fixing a
broken link or path is allowed.
- **Design docs are prose and diagrams only** — no code. A manifest field may be named; a
manifest may not be pasted.
- **Two layers, never mixed.** [`02-DESIGN/00-as-is/`](02-DESIGN/00-as-is/) describes the mesh
that exists; [`02-DESIGN/01-to-be/`](02-DESIGN/01-to-be/) describes the one being built
toward. Every design doc says which it is in `layer:`. A statement about the future does not
belong in an as-is document, and an as-is document is never edited to describe an intention.
- **`00-GENESIS/how-we-build.md` is the source of the mesh constitution.** The knowledge-base
constitution page is derived from it — see playbook
[`05-constitution-sync.md`](00-GENESIS/process/05-constitution-sync.md). Never edit the
derived page directly.
## This repository is public
Nothing here may contain routable addresses, real domain names, hosting providers, node
names, absolute paths, usernames, credentials, or operational detail useful only to an
attacker. Use documentation ranges (RFC 5737, RFC 1918) and role names — `anchor`,
`home-server`, `workstation`, `laptop`, `the build node`, `the broker node`.
The test: would this paragraph still teach a stranger running an entirely different mesh?
If yes, it belongs. If it only makes sense to someone who knows this installation, it is
either a note in the wrong place or a disclosure. The full rule is in
[`README.md`](README.md).
## A rule states how it is checked
If a document states a rule about the mesh, it says how that rule is verified. An unenforced
rule is indistinguishable from a wrong one, and costs more, because people believe it.
CLAUDE.md
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
DECISIONS.md
+51 -31
View File
@@ -18,10 +18,10 @@ no pointer is one small enough that this line is the whole record.
| # | Decision | Decided | Where |
|---|---|---|---|
| 1 | The mesh brokers capabilities; nodes host; agents think. Eight bounded contexts replace 33 platform modules. | jochen | [ADR 0001](adr/0001-mesh-brokers-nodes-host-agents-think.md) |
| 2 | Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality. | jochen | [ADR 0001](adr/0001-mesh-brokers-nodes-host-agents-think.md) |
| 3 | noxflow dissolves; `hal/work` inherits tasks and workflows. | jochen | [ADR 0001](adr/0001-mesh-brokers-nodes-host-agents-think.md) |
| 4 | Third-party modules leave this repository — they run *on* the mesh, not *of* it. | jochen | [ADR 0001](adr/0001-mesh-brokers-nodes-host-agents-think.md) |
| 1 | The mesh brokers capabilities; nodes host; agents think. Eight bounded contexts replace 33 platform modules. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) |
| 2 | Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) |
| 3 | noxflow dissolves; `hal/work` inherits tasks and workflows. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) |
| 4 | Third-party modules leave this repository — they run *on* the mesh, not *of* it. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) |
| 5 | ~~Documentation lives inside the code repository under `hq/`.~~ | jochen | **Superseded by #27** |
## 2026-08-22 — the lab
@@ -31,24 +31,24 @@ no pointer is one small enough that this line is the whole record.
| 6 | Phase 0 is a **development environment**, not a fixture rig — it is what the host-borrowing dev tooling becomes. | jochen | [002](01-RESEARCH/002-local-mesh/status.md) |
| 7 | The delivery trigger is a **real forge** inside the lab, not a synthetic event — the webhook relay is part of what is under test. | jochen | [002](01-RESEARCH/002-local-mesh/status.md) |
| 8 | ~~A lab node is a **system container**, promotable to a virtual machine.~~ | jochen | **Superseded by #10** |
| 9 | Adoption is a legacy path and is out of scope. Bringing nodes into being is the lab runner's job instead. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 10 | A lab node is a **virtual machine** running the real install. Supersedes #8: the scale argument for system containers was invented rather than required, and a virtual machine dissolves the fidelity question instead of answering it. | jochen | [ADR 0002](adr/0002-a-lab-node-is-a-virtual-machine.md) |
| 9 | Adoption is a legacy path and is out of scope. Bringing nodes into being is the lab runner's job instead. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 10 | A lab node is a **virtual machine** running the real install. Supersedes #8: the scale argument for system containers was invented rather than required, and a virtual machine dissolves the fidelity question instead of answering it. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) |
| 11 | The environment is called **the lab**. | jochen | — |
| 12 | The lab is driven by `incus` — for virtual machines, snapshots and bridges through one interface, and because it also runs system containers if a scale run is ever needed. | jochen | [ADR 0002](adr/0002-a-lab-node-is-a-virtual-machine.md) |
| 13 | The simulated public segment uses **TEST-NET-3** (`203.0.113.0/24`). Not cosmetic: an RFC1918 public segment makes the hub test as unreachable and the mesh silently never forms. | — | [ADR 0002](adr/0002-a-lab-node-is-a-virtual-machine.md), [004](01-RESEARCH/004-lab-network/analysis.md) |
| 14 | The lab **issues its own certificates**, keeping production's two-authority split rather than collapsing it. | jochen | [ADR 0002](adr/0002-a-lab-node-is-a-virtual-machine.md) |
| 12 | The lab is driven by `incus` — for virtual machines, snapshots and bridges through one interface, and because it also runs system containers if a scale run is ever needed. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) |
| 13 | The simulated public segment uses **TEST-NET-3** (`203.0.113.0/24`). Not cosmetic: an RFC1918 public segment makes the hub test as unreachable and the mesh silently never forms. | — | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md), [004](01-RESEARCH/004-lab-network/analysis.md) |
| 14 | The lab **issues its own certificates**, keeping production's two-authority split rather than collapsing it. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) |
## 2026-08-22 — what the lab is for
| # | Decision | Decided | Where |
|---|---|---|---|
| 15 | **The module is what is under test; the mesh is the harness.** The loop is: change a module, run it end to end, get a verdict. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 16 | **Nothing new drives delivery.** A lab mesh has its own coordinator; the pipeline that runs is the real one. A second delivery path would be blind to exactly the faults worth catching. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 17 | A **test runner** is a legitimate component *used by* the coordinator — lab lifecycle and assertion execution. The line is the pipeline: a runner that decides what to build is a fork of the coordinator. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 18 | The runner has **two callers** — the coordinator, and a person developing the mesh — so it needs both a run-to-verdict verb and a leave-it-standing verb. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 19 | **A module carries its own assertions**, stated once, in the verification stage the coordinator already dispatches. Running them where failing is free is what makes writing them worth doing. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 20 | A test declares the mesh it needs; **size ranges from one node upward**, chosen by the question rather than by what the mesh happens to have. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 21 | The real topology is **one test among many**, not the baseline. Anything only testable there is a gap in the vocabulary. | jochen | [design](02-DESIGN/01-end-to-end-testing.md) |
| 15 | **The module is what is under test; the mesh is the harness.** The loop is: change a module, run it end to end, get a verdict. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 16 | **Nothing new drives delivery.** A lab mesh has its own coordinator; the pipeline that runs is the real one. A second delivery path would be blind to exactly the faults worth catching. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 17 | A **test runner** is a legitimate component *used by* the coordinator — lab lifecycle and assertion execution. The line is the pipeline: a runner that decides what to build is a fork of the coordinator. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 18 | The runner has **two callers** — the coordinator, and a person developing the mesh — so it needs both a run-to-verdict verb and a leave-it-standing verb. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 19 | **A module carries its own assertions**, stated once, in the verification stage the coordinator already dispatches. Running them where failing is free is what makes writing them worth doing. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 20 | A test declares the mesh it needs; **size ranges from one node upward**, chosen by the question rather than by what the mesh happens to have. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
| 21 | The real topology is **one test among many**, not the baseline. Anything only testable there is a gap in the vocabulary. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) |
## 2026-08-22 — working agreements
@@ -56,25 +56,45 @@ no pointer is one small enough that this line is the whole record.
|---|---|---|---|
| 22 | **Never install packages by hand.** A package is declared in the module manifest and arrives the way every other package does. | jochen | — |
| 23 | **Never open a pull request unprompted.** A permissions list saying it is allowed is not a request. | jochen | — |
| 24 | **Every merge is a human checkpoint**, without exception. | jochen | [`02-DESIGN/00-work-breakdown.md`](02-DESIGN/00-work-breakdown.md) |
| 25 | Work in an **isolated worktree**, never a shared checkout. | jochen | `CLAUDE.md` |
| 24 | **Every merge is a human checkpoint**, without exception. | jochen | [`02-DESIGN/01-to-be/00-work-breakdown.md`](02-DESIGN/01-to-be/00-work-breakdown.md) |
| 25 | Work in an **isolated worktree**, never a shared checkout. | jochen | [`how-we-build`](00-GENESIS/how-we-build.md) §2 |
| 26 | Decisions are recorded **here**, thoroughly, as they are taken. | jochen | this file |
| 27 | HQ is **its own repository**, `hal-hq`. Supersedes #5: the original objection was to a fourth knowledge *system*, which indexing answers rather than location. Cadence, reviewers, and a scope wider than one repository all argue for separation. | jochen | [`README`](README.md) |
| 28 | **This repository is public.** Written for a reader who is not its author and has no access to the mesh it describes. No routable addresses, real domains, hosting providers, node names, absolute paths, or operational detail useful only to an attacker. Supersedes the previous rule that research may name instances. | jochen | [`README`](README.md) |
---
## Observations — not decisions, but they should not be lost
## 2026-08-23 — how this repository works
Things established by measurement that no decision has yet answered.
| # | Decision | Decided | Where |
|---|---|---|---|
| 29 | Design splits into two layers that are never mixed — **`00-as-is` describes the mesh that exists, `01-to-be` the one being built toward**. A design that ships does not move; its as-is counterpart is written and both stand. | jochen | [`02-DESIGN/README`](02-DESIGN/README.md) |
| 30 | The as-is layer is written **from the implementation and the operational record**, not from intent, and records shipped behaviour nobody would choose again. An as-is layer that keeps only the good decisions is a brochure. | jochen | [`02-DESIGN/00-as-is/README`](02-DESIGN/00-as-is/README.md) |
| 31 | **HQ is the source of the mesh constitution.** The governed page injected into design sessions is derived from `how-we-build.md` and never edited directly. Same one-source-many-surfaces argument as #27. | jochen | [playbook 05](00-GENESIS/process/05-constitution-sync.md) |
| 32 | Every workflow is a **playbook** in `00-GENESIS/process/`, wrapped by a thin skill that defers to it. Agents operate through the playbooks and not outside them. | jochen | [`process/00-overview`](00-GENESIS/process/00-overview.md) |
| 33 | Issues get a **front door**, `04-ISSUES` — design-level and governance faults only. Operational lessons stay in the knowledge base, which is indexed on symptoms. This repository is not a second copy of it. | jochen | [`04-ISSUES/README`](04-ISSUES/README.md) |
| 34 | Decision records are a **chronological ledger**. Fourteen decisions already taken in implementation were back-filled as records 0001–0014, each marked `reconstructed` and carrying its evidence; the two existing records renumbered to 0015 and 0016. | jochen | [`adr/README`](adr/README.md) |
| 35 | **Status lives in frontmatter.** No central status files; cross-cutting views are generated on demand. This file is a ledger of decisions as taken — an index, and the home of decisions too small to warrant a record — and explicitly not a status board. | jochen | [`process/00-overview`](00-GENESIS/process/00-overview.md) |
| 36 | The ADR index is **generated, not maintained**. The hand-written one had already drifted after a single addition. | jochen | [`adr/README`](adr/README.md) |
| 37 | Modules outside the platform core are grouped **by domain, not by single function**, extending #1. The principle is settled; the domain list deliberately is not. | jochen | [ADR 0017](adr/0017-modules-outside-the-core-are-grouped-by-domain.md) |
| 38 | ~~The overview in the code repository contradicts the symlink rule.~~ Withdrawn as wrong: the rule forbids creating a link by hand; the installer links deliberately. | jochen | [ADR 0011](adr/0011-the-installer-owns-linking.md) |
| Observed | What it means |
---
## Observations
Things established by measurement that no decision has yet answered now live in
[`04-ISSUES`](04-ISSUES/), one numbered folder each, so they can be diagnosed, owned and
closed rather than accumulating in a table nobody can resolve.
| Issue | What it means |
|---|---|
| **A failed package install does not fail the job.** Declaring `incus` produced `error: failed retrieving file … 404` from every mirror, then `-> error installing repo packages`, and the prepare job reported **success**. The package is absent; the pipeline is green. | The first thing the lab was asked to install demonstrated the exact fault the lab exists to catch. A fix is already written and open as PR #848, unmerged since 2026-08-20. |
| **The package database is stale on at least one node.** The install ran without a sync, so it requested a version the mirrors had already superseded — 404 from every mirror. | A declared package can fail purely because the node's index is old, and today that failure is silent. |
| **`scope:` on firewall rules is read by no code.** Declared in five manifests; not part of the rule type. Real scoping is `from:`. | A manifest can appear to restrict a port and restrict nothing. |
| **The reverse proxy sets no `caServer`**, so certificate issuance targets the public authority's production endpoint rather than staging. | Every certificate experiment on a real node consumes production issuance quota. |
| **`test/pipeline/` has been unbuildable since 2026-06-04**, when the npm workspace it depends on was removed. Nothing runs it. | The repository's only end-to-end pipeline test has been silently dead for two and a half months. |
| [001](04-ISSUES/001-failed-package-install-reports-success/00-report.md) | A failed package install does not fail the job. The first thing the lab was asked to install demonstrated the exact fault the lab exists to catch. |
| [002](04-ISSUES/002-stale-package-index-fails-silently/00-report.md) | A declared package can fail purely because the node's index is old, and today that failure is silent. |
| [003](04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md) | A manifest can appear to restrict a port and restrict nothing. |
| [004](04-ISSUES/004-certificate-issuance-targets-production/00-report.md) | Every certificate experiment on a real node consumes production issuance quota. |
| [005](04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md) | The repository's only end-to-end pipeline test has been silently dead since 2026-06-04. |
| [006](04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md) | This repository is not indexed into the knowledge base — the claim that holds up decision 27. |
## Deliberately not decided
@@ -84,8 +104,8 @@ Recorded so they are not mistaken for oversights.
|---|---|
| Which supervision model the mesh adopts — keep the host init system, drop the redundant per-module layer, containerise the daemons, or write a supervisor. | Open. Options costed in [003](01-RESEARCH/003-service-supervision/analysis.md). **No longer gates the lab.** |
| Whether the lab verdict is a workflow guard or an advisory check on the pull request. | Open, and deliberately trivial — a policy detail, changeable in an afternoon, not an architectural choice. |
| `hal/scheduler` — infrastructure or part of `hal/work`. | Open, from ADR 0001. |
| Which context owns the executor. | Open, from ADR 0001. |
| Catalogue destination — one repository or many. | Open, from ADR 0001. Phase 4. |
| What `hal/sdk` keeps after extraction. | Open, from ADR 0001. Phase 3. |
| Where human agent modality is recorded — which user, on which node, a human agent acts as. | Open, from ADR 0001. Required by the model; not yet stored. |
| `hal/scheduler` — infrastructure or part of `hal/work`. | Open, from ADR 0015. |
| Which context owns the executor. | Open, from ADR 0015. |
| Catalogue destination — one repository or many. | Open, from ADR 0015. Phase 4. |
| What `hal/sdk` keeps after extraction. | Open, from ADR 0015. Phase 3. |
| Where human agent modality is recorded — which user, on which node, a human agent acts as. | Open, from ADR 0015. Required by the model; not yet stored. |
README.md
+44 -12
View File
@@ -7,17 +7,39 @@ why. Implementation lives in `modules/`; the reasoning behind it lives here.
| Folder | Purpose |
|--------|---------|
| [`00-GENESIS`](00-GENESIS/) | Mission and foundational context. The northern star for every decision. |
| [`00-GENESIS`](00-GENESIS/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. 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. |
| [`02-DESIGN`](02-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](02-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](02-DESIGN/01-to-be/) — the one being built toward. |
| [`adr`](adr/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. |
| [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. |
| [`DECISIONS.md`](DECISIONS.md) | The ledger: every decision as it was taken, indexing the records and holding the ones too small to warrant one. |
## The flow
```
idea ──► 01-RESEARCH ──► decision (adr/) ──► 02-DESIGN/01-to-be ──► built (code repo)
│ │ │
│ │ └─► 02-DESIGN/00-as-is once shipped
│ └────► abandoned (recorded, kept)
└─(small/obvious, decision recorded in DECISIONS.md)────► 02-DESIGN directly
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
00-GENESIS/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions
```
Implementation lives in the code repositories — see
[`00-GENESIS/repos.md`](00-GENESIS/repos.md). Every workflow is a playbook in
[`00-GENESIS/process/`](00-GENESIS/process/); agents operate through them and not outside them.
## 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.
- Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only after
analysis against GENESIS confirms alignment, and only through a recorded decision.
- **Status lives in frontmatter**, never in a central status file. Cross-cutting views are
generated on demand, never hand-maintained.
- **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.
@@ -25,9 +47,12 @@ why. Implementation lives in `modules/`; the reasoning behind it lives here.
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.
- **The as-is layer records what is, not what should be** — including behaviour nobody would
choose again. A layer that keeps only the good decisions is a brochure.
- 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 has a rule requiring every capability-exposing module to declare the core
runtime as a dependency; zero modules do. An unenforced rule is indistinguishable from a
wrong one.
### This repository is public
@@ -54,10 +79,17 @@ It began inside the code repository, on the reasoning that HAL already has a mes
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.
**That objection was about a fourth knowledge *system*, and the answer offered was indexing
rather than location** — that these documents would be indexed into the knowledge base, so a
symptom search returns them beside everything else. One source, many surfaces. Where the source
is authored is then a separate question.
**That indexing does not exist.** It was checked on 2026-08-23 and returns nothing; it appears
never to have existed. Until it does, the objection stands unanswered and this repository is
the fourth knowledge system it was argued not to be. Recorded as
[`04-ISSUES/006`](04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md), and
left standing here rather than quietly reworded, because a claim that held up a decision and
was never checked is precisely the failure this repository exists to name.
Answered separately, a repository of its own is the better home:
@@ -65,7 +97,7 @@ Answered separately, a repository of its own is the better home:
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
- **The scope is wider than one repository.** [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
monorepo entirely. Documentation that governs several repositories cannot live inside one
of them.
adr/0001-nodes-communicate-over-a-broker.md
+68
View File
@@ -0,0 +1,68 @@
---
status: accepted
date: 2026-02-25
deciders: jochen
reconstructed: true
---
# 1. Nodes communicate over a message broker, not over HTTP
> Reconstructed after the fact from the evidence cited below. The decision was taken in
> implementation, not in a record; this document states what was decided and why, not a
> deliberation that happened.
## Context
The mesh is a set of machines that must call each other's capabilities. On the day the
repository was founded there was no inter-node transport at all — each node was configured
independently and shared nothing at runtime.
Three properties were required and are visible in everything built since:
- A node behind a household NAT must participate fully. It can dial out; nothing can dial in.
- A node that is asleep, rebooting or upgrading must not cause a caller to fail — the request
should wait, not error.
- Adding a node must not require editing anything on the nodes that already exist.
## Considered options
1. **HTTP APIs between nodes.** Rejected. Every node becomes a server that every other node
must be able to reach, which the NAT case makes impossible without inbound tunnels to each
participant. It also makes node liveness a caller's problem: a request to a sleeping node
is an error rather than a wait.
2. **Polling a shared database.** Rejected. Latency is the poll interval, load is constant and
independent of demand, and request/reply has to be built on top of it by hand.
3. **A central message broker with per-node exchanges.** Chosen.
## Decision
All inter-node communication goes through a message broker. Every node owns a topic exchange
named for itself and a request queue; a shared mesh exchange carries commands and events that
are not addressed to one node.
Three message shapes, and only three:
- **RPC** — request/reply, for calling a capability that lives on another node.
- **Commands** — instructions to do a stage of work, addressed by what is to be done.
- **Events** — statements that something happened, addressed to nobody.
Every node dials the broker outbound. Nothing dials a node.
## Consequences
- NAT stops being an architectural concern. A node's reachability is a property of the broker
connection, not of its network position.
- A call to a node that is down waits in that node's queue instead of failing. This is usually
right and occasionally the wrong thing entirely — a queued command for a node that never
returns is a stall with no error, which is the failure shape this mesh keeps rediscovering.
- The broker is a single point of failure and a single point of trust. Its credential is
mesh-wide, so rotating it is a mesh-wide operation.
- Tools never leave the host: a remote call proxies over the broker and the credentials stay
where the capability is.
## References
- The broker was stood up on 2026-02-25, the second day of the repository.
- Knowledge base: `mesh` (transport, exchanges, queue naming), `troubleshooting/amqp-credential-rotation`.
- The stall shape is recorded in `troubleshooting/empty-pipeline-blocks-the-queue` and
`troubleshooting/daemon-and-tool-server-share-a-request-queue`.
adr/0002-everything-is-a-module.md
+73
View File
@@ -0,0 +1,73 @@
---
status: accepted
date: 2026-03-14
deciders: jochen
reconstructed: true
---
# 2. Everything is a module, and one manifest describes all of them
> Reconstructed after the fact from the evidence cited below.
## Context
The mesh carries several kinds of thing: containerised services with data and ports, pure
capability providers with no service at all, and bare markers whose only content is that a
node has them. Before this decision these were separate concepts with separate handling —
the earlier vocabulary was *capabilities*, and services were installed by a different path
than tools.
Every distinct kind of thing needs its own install path, its own change detection, its own
place in the delivery pipeline, and its own documentation. Three kinds means three of each,
and every new feature has to be built three times or, more commonly, once — leaving two kinds
quietly unsupported.
## Considered options
1. **Separate concepts per kind** — a service registry, a tool registry, a node feature flag
list. Rejected: it is what existed, and the cost was paid in every cross-cutting change.
2. **One manifest, kind inferred from directory contents.** Chosen.
3. **One manifest with an explicit `type:` field on every module.** Partly adopted — a service
still declares itself — but the general rule became inference, because a declared list and
the directory it describes drift, and the directory is the one that is true.
## Decision
Everything the mesh installs is a **module**: a directory with a manifest. The manifest
declares identity, environment variables, what the module provides, what it requires, and how
it is exposed. What kind of module it is follows from what the directory contains:
| Contains | Is |
|---|---|
| a compose definition | a service |
| a tools directory | a capability provider |
| a daemon or unit directory | a long-running process |
| a configs directory | a source of managed files |
| nothing but a manifest | a flag — presence is the whole content |
A module may be several of these at once. Each is a **feature**, and the delivery pipeline
addresses features, not modules.
The mesh's own components are modules on exactly these terms. They get no privileged install
path, no separate registry, and no exemption from the pipeline.
## Consequences
- One mechanism to learn, one to document, one to fix. A pipeline improvement reaches
everything the mesh carries.
- Dogfooding stops being a discipline and becomes structural: if the mesh's own components
need an exception, the machinery is unfinished, and that is visible immediately.
- Feature detection from directory contents means a directory rename silently changes what a
module *is*. This has bitten repeatedly — a hook named for a feature the module does not
have is skipped without complaint.
- The manifest becomes load-bearing and grows. It is now the largest single point of
coupling in the mesh.
## References
- `Rename capabilities → modules across the entire codebase`, 2026-03-14.
- `Merge fail2ban, ufw, firewall apps into modules`, 2026-03-15 — the first modules to arrive
by conversion rather than by creation.
- Knowledge base: `modules`, `modules/manifest-reference`, `conventions/modules`.
- The rename-breaks-detection shape: `troubleshooting/hooks-named-for-missing-feature`,
`troubleshooting/health-check-tools-index-false-positive`.
adr/0003-the-mesh-database-is-the-source-of-truth.md
+65
View File
@@ -0,0 +1,65 @@
---
status: accepted
date: 2026-04-02
deciders: jochen
reconstructed: true
---
# 3. The mesh database is the source of truth; the repository is node-agnostic
> Reconstructed after the fact from the evidence cited below.
## Context
Two things must be known to run the mesh: **what exists** — which modules there are, what each
declares, how each is built — and **what runs where** — which node hosts which module, with
which settings, at which version.
The repository is the natural home of the first. It was initially also the home of the second:
per-node directories held that node's configuration, and adopting a machine meant committing
its files. That has three costs. A node cannot be changed without a commit, so runtime state
and source share a review cadence they do not share a rhythm with. Two nodes cannot be
reconciled, because nothing holds both. And the repository becomes an inventory of the
installation, which is exactly the content that cannot be made public.
## Considered options
1. **Per-node directories in the repository.** Rejected — it is what existed. Every binding
change is a commit and a deploy, and the repository accumulates an inventory of one
particular mesh.
2. **Configuration files distributed to nodes and edited there.** Rejected. There is then no
authority: two nodes disagreeing have no arbiter, and drift is invisible until something
breaks.
3. **A mesh database as the single authority, cached locally for resilience.** Chosen.
## Decision
A single database holds every binding: which node hosts which module, at which selection, with
which environment overrides, plus mesh-level settings that all nodes read. The runtime loads
its configuration from that database at startup and falls back to a local cache when the
database is unreachable.
**The repository defines what exists. The database defines what runs where.** No node-to-module
mapping is ever committed.
A node is therefore not described anywhere in source. Bringing one into the mesh is a database
operation.
## Consequences
- The repository becomes node-agnostic, and can be published without disclosing an
installation. This repository's public stance rests on that property.
- A binding changes without a commit, a build, or a deploy.
- The local cache means a node survives losing the database, but a node running from cache is
running from a snapshot with no indication of its age. Divergence is silent by construction.
- The database is the hardest dependency in the mesh. It is also a module, provisioned like
any other, which makes its bootstrap circular — resolved by the first-node initialisation
script, and the reason such a script exists.
- Nothing on a node is authoritative. That is what makes the next decision necessary.
## References
- `Phase 3: rename core modules to hal/ namespace`, 2026-04-02, and the mesh configuration
tables that landed with it.
- Knowledge base: `mesh` — "The repo is node-agnostic. It contains no per-node assignments."
- The stale-cache shape: `troubleshooting/installed-version-and-deployments-are-stale`.
adr/0004-managed-files-are-generated-never-edited.md
+63
View File
@@ -0,0 +1,63 @@
---
status: accepted
date: 2026-04-03
deciders: jochen
reconstructed: true
---
# 4. Managed files are generated onto nodes and never edited there
> Reconstructed after the fact from the evidence cited below.
## Context
[ADR 0003](0003-the-mesh-database-is-the-source-of-truth.md) put every binding in the mesh
database. But the things that consume those bindings — environment files, service
definitions, daemon configuration, firewall rules — are files on a node's disk, because that
is what the software reading them requires.
So the same value exists twice: authoritatively in the database, and materialised in a file.
Any edit to the file is a change to a copy. Before this decision, environment values could be
pushed from a node back into the database, which made the direction ambiguous in both
directions at once.
## Considered options
1. **Bidirectional sync** — a node's edits flow back to the database. Rejected, and removed.
Two writers and no arbiter: whichever synced last wins, and neither is authority.
2. **Files are authoritative; the database is a cache of them.** Rejected — it inverts
ADR 0003 and returns to state that cannot be reconciled across nodes.
3. **Strictly one-directional: the database is written, files are generated.** Chosen.
## Decision
Every managed file is **derived**. A synchroniser regenerates it from the mesh database
whenever the underlying values change. The write path is the mesh tool that owns the value;
the file is an output.
This applies to generated environment files, service definitions, managed configuration, and
anything else a synchroniser lists as its own.
An edit to a managed file survives until the next synchronisation and is then overwritten,
without a warning, taking whatever it was fixing with it.
## Consequences
- **A file edited on a node is a bug with a delay on it.** This is now one of the mesh's core
values, and it is a consequence of this decision rather than a stance taken independently.
- To change a value you must know which tool owns it. That is a real cost, paid every time,
and the reason the mesh provides a way to ask whether a given file is managed.
- Debugging by editing a file no longer works, and fails in the most confusing way available:
it works, and then stops working later for no locally visible reason.
- Recovery is cheap. A node's entire managed surface can be regenerated from the database.
- Values resolve by precedence — database override, then existing file value, then generated,
then manifest default — which means an unset override does not clobber a generated
password. The subtlety is real and has caused its own confusion.
## References
- `Extract hal/env-sync module, remove syncEnvToDb`, 2026-04-03 — the commit that removed the
node-to-database direction.
- Knowledge base: `conventions/no-direct-file-mutation`, `provisioning` (resolution priority).
- Regeneration gaps: `troubleshooting/changed-manifest-default-not-rerendered`,
`troubleshooting/config-removed-from-manifest-not-pruned`.
adr/0005-capabilities-are-provisioned-on-declaration.md
+67
View File
@@ -0,0 +1,67 @@
---
status: accepted
date: 2026-04-06
deciders: jochen
reconstructed: true
---
# 5. Capabilities are provisioned on declaration, not configured by hand
> Reconstructed after the fact from the evidence cited below.
## Context
Most modules need something another module holds — a database, a cache, a bucket, a message
vhost, an identity client. Wiring that by hand means creating the resource, creating a user,
generating a credential, putting it in the consumer's configuration, and repeating all of it
on every node the consumer runs on.
Every step is a place to make a mistake that surfaces much later, and the credential ends up
written somewhere it can be read.
## Considered options
1. **Manual setup, documented.** Rejected. Documentation of a manual procedure is a
description of the mistakes people will make.
2. **A shared credential per resource type**, distributed to all consumers. Rejected: no
isolation, and rotation becomes a mesh-wide outage.
3. **Declared requirements, satisfied by the provider module.** Chosen.
## Decision
A module declares what it **provides** and what it **requires**. A requirement names the
provider, the resource type, optionally a name and a target node, and a mapping from the
resource's connection fields to the consumer's environment variables.
The mesh satisfies it: a provisioner belonging to the provider creates the resource and its
credential, records the grant, and writes the mapped values as database overrides. The
synchroniser from [ADR 0004](0004-managed-files-are-generated-never-edited.md) then
materialises them. Neither the credential nor the topology is ever written by hand.
A requirement may name a provider on another node. The grant records consumer and provider
nodes separately, so cross-node wiring is the same declaration.
## Consequences
- **Provisioning becomes a core concern of the mesh, not plumbing.** A module asks for a
capability; where it lives is the mesh's problem. This is the property
[ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) later builds the whole domain model
around.
- Credentials are never authored, so they are never authored badly, and they are never in the
repository.
- Each consumer gets its own credential, so revocation is per-consumer.
- Rotation is where this bites. A shared secret rotated for a new consumer invalidates the
peers holding the old one, and this has taken the mesh down. The declaration model makes
granting easy and says nothing about fan-out.
- A module with no requirements skips the stage entirely, which is correct and also means the
absence of provisioning is indistinguishable from provisioning that did not run.
## References
- `Remove shell/ helper library; split brain into independent workspaces`, 2026-04-06 — the
provisioner daemon becomes its own component.
- `Coordinator refactor: centralize pipeline orchestration`, 2026-04-04 — the provision-then-
environment-then-start sequence becomes the coordinator's.
- Knowledge base: `provisioning`, `provisioning/requires`.
- The rotation failure: `troubleshooting/provision-rotation-invalidates-peers`,
`troubleshooting/provision-adoption-rotates-live-credential`.
adr/0006-schema-changes-are-numbered-migrations.md
+68
View File
@@ -0,0 +1,68 @@
---
status: accepted
date: 2026-05-14
deciders: jochen
reconstructed: true
---
# 6. Schema and state changes are numbered migrations, in the same language as the code
> Reconstructed after the fact from the evidence cited below.
## Context
Modules own persistent state. That state has to change as they change, across nodes that are
at different versions, some of which have data that predates the change.
Two things were being done that do not survive contact with a second node. Schema was created
at startup, so what a table looked like depended on which version last started. And migrations
were shell scripts, so they could not use the types, connection handling or helpers the module
already had, and were not compiled or checked with it.
## Considered options
1. **Startup SQL / create-if-missing.** Rejected. It converges only for a node that started
with the newest version. A node that never restarts never migrates; a node that restarts on
an old version can undo a change.
2. **Shell migrations.** Rejected. Unchecked, untyped, and a separate dialect from the module
they belong to. Also, as later discovered, packaged differently — and therefore
occasionally not packaged at all.
3. **Numbered migrations in the module's own language, compiled with it.** Chosen.
## Decision
Every schema or state change is a numbered migration file, written in the same language as the
module and compiled with it. There is no startup schema creation and no ad-hoc statement.
Rules that come with it:
- The initial migration is **frozen** once it has run anywhere. It is never modified; a change
is a new number.
- Every statement is **idempotent** — guarded so that re-running is safe.
- A change needs **both** a baseline for a fresh installation and an incremental migration for
installations that already exist. Code referencing a column requires that the migration
creating it exists.
- Migration numbers are unique. A duplicate prefix is a defect, not a style issue.
## Consequences
- A node at any version converges to the current schema by running the migrations it has not
run.
- Migrations are checked by the same compiler as the code, and a migration that does not
compile fails the build rather than the deployment.
- The rules are enforced unevenly. Duplicate prefixes have shipped repeatedly and been fixed by
renumbering afterwards; the mesh now validates for them, which is the check this rule needed
in order to be real.
- A migration directory is a feature like any other, which means it is packaged like any other
— and when packaging is wrong, migrations silently do not ship. This has happened.
- Freezing the initial migration means a fresh installation replays the entire history. That
cost grows and nothing currently bounds it.
## References
- `fix(agents): convert workflow migrations to TypeScript` (#50), 2026-05-14.
- `feat(dev_validate): guard against duplicate migration numeric prefixes` (#379), 2026-06-26 —
the rule acquiring a check.
- Knowledge base: `migrations/schema-drift`, `noxflow/troubleshooting/migration-number-collision`.
- Packaging failures: `troubleshooting/shell-migrations-never-packaged`,
`troubleshooting/provision-migration-never-applied`.
adr/0007-no-npm-workspace.md
+65
View File
@@ -0,0 +1,65 @@
---
status: accepted
date: 2026-06-04
deciders: jochen
reconstructed: true
---
# 7. No workspace — each module is a standalone package consuming published dependencies
> Reconstructed after the fact from the evidence cited below.
## Context
Modules depend on each other, above all on the shared library every module builds against.
A workspace was the obvious way to express that: sibling packages, resolved locally, one
install at the root.
It produced a divergence that is worth stating precisely, because it is not obvious. In
development, a workspace member importing a sibling resolves to that sibling's **local source**.
In the pipeline, each module is built alone, from a clone, without its siblings present — so
the same import resolves to the **published version**. The two environments were therefore
building different code from identical source, and the failure appeared only in the pipeline,
in a module that had not been touched.
## Considered options
1. **Keep the workspace and make the pipeline replicate it** — clone every module, build the
graph. Rejected: it makes every build a whole-repository build, which is the cost the
per-module pipeline exists to avoid, and it does not extend to modules in their own
repositories.
2. **Keep the workspace and pin siblings to published versions.** Rejected as the worst of
both: the workspace's local resolution silently overrides the pin, so the divergence
remains while looking solved.
3. **No workspace. Every module is standalone and consumes published dependencies.** Chosen.
## Decision
There is no workspace. Each module is an independent package that declares its dependencies
and consumes them from the private registry, including the mesh's own shared library.
A cross-package change is therefore two steps: publish the producer, then consume it. The
pipeline does the first on push and resolves the levels so that a module always builds against
its dependencies' freshly published versions.
## Consequences
- Development and the pipeline resolve imports identically. The divergence is gone by
construction rather than by discipline.
- A module in its own repository is not a special case. It builds exactly as a module in the
monorepo does — which is what makes [ADR 0010](0010-applications-live-in-their-own-repository.md)
cheap.
- A cross-package change costs a publish-and-consume round trip. This is the real price, paid
on every shared-library change.
- There is no repository-wide install and no repository-wide build. Anything that assumed one
broke, and one thing that assumed one has stayed broken: the end-to-end pipeline harness has
not built since this decision landed. See
[`04-ISSUES/005`](../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md).
## References
- `fix(noxflow): kill npm workspace, restore encryption inside PgAdminRepo` (#240),
2026-06-04. The reason is recorded in the root package manifest, which still carries the
note explaining why no workspace exists.
- The divergence it fixed is named there: workspace members importing each other resolved to
local unbuilt source in the pipeline.
adr/0008-a-failed-step-fails-the-job.md
+71
View File
@@ -0,0 +1,71 @@
---
status: accepted
date: 2026-06-05
deciders: jochen
reconstructed: true
---
# 8. A step that fails must fail the job
> Reconstructed after the fact from the evidence cited below.
## Context
The mesh's expensive faults are not crashes. They are the operations that reported success and
did nothing: an artifact that partially downloaded and was extracted anyway, a package that
404ed from every mirror while the job went green, a hook that never ran because it was named
for a feature the module does not declare, a deploy that reported the transport succeeded
rather than that the effect happened.
Each of these was found long after it happened, by someone investigating an unrelated symptom.
The cost is not the failure; it is the interval between the failure and anyone learning of it,
during which decisions are made on the assumption that the thing worked.
## Considered options
1. **Continue on error and report at the end.** Rejected — it is largely what existed. A
summary nobody reads is not a report, and later steps run against the state the failed step
should have produced.
2. **Continue on error, and let health checks catch the divergence.** Rejected. It converts a
precise, located failure into a vague one discovered elsewhere, and requires a health check
for every possible partial state.
3. **Fail the step, fail the job, say which step.** Chosen.
## Decision
A step that fails stops the sequence it is part of, and the failure is surfaced where the work
was requested — not only in a log.
Concretely, and these are the forms it takes:
- A scripted sequence gates each step on the previous one. A directory change that fails must
stop the commands that assumed it.
- An artifact that does not fully download is not extracted.
- A stage reports the **effect** it achieved, not that it dispatched a message. "Started" must
mean the thing is running, not that a command returned.
- A template that cannot resolve a variable is not written half-rendered.
**Prefer failing to lying.** A green result that is not true costs more than a red one.
## Consequences
- Failures are noisier and land earlier, on the person who caused them.
- Some jobs that used to complete now stop. In every case examined so far, that job was
producing a partial result that something downstream trusted.
- This is a rule the mesh has adopted repeatedly rather than once, because each instance is
written in a different place — a shell hook, a download path, a deploy stage. It is not
enforced by a mechanism, and cannot currently be checked in general. New instances are still
being found; the package-install case remains open as
[`04-ISSUES/001`](../04-ISSUES/001-failed-package-install-reports-success/00-report.md).
## References
- `fix(installer): fail loudly when feature artifact download fails` (#244), 2026-06-05.
- `A flavor template with an unresolved variable is written to disk instead of failing`
(#710), 2026-08-08.
- Knowledge base: `troubleshooting/deploy-reports-transport-not-effect`,
`troubleshooting/service-started-is-not-ready`,
`troubleshooting/green-pipeline-means-transport-not-effect`,
`troubleshooting/silent-failures-and-stale-state`.
- The core value it became: [`00-GENESIS/mission.md`](../00-GENESIS/mission.md), "Failure must
be loud."
adr/0009-the-mesh-is-governed-by-a-constitution.md
+63
View File
@@ -0,0 +1,63 @@
---
status: accepted
date: 2026-07-10
deciders: jochen
reconstructed: true
---
# 9. The mesh is governed by a constitution, injected where work is decided
> Reconstructed after the fact from the evidence cited below.
## Context
By mid-2026 the mesh was doing a large share of its own design and implementation work through
agents. The rules those agents were expected to follow existed — in operating instructions, in
convention documents, in the knowledge base — but they were **retrieved**: an agent had to know
a rule existed in order to look it up.
Rules that must be looked up are followed by whoever already knows them, which is precisely the
population that does not need them. The rules being violated were the ones nobody thought to
search for.
## Considered options
1. **Documentation plus review.** Rejected — it is what existed. Review catches a violation
after the work is done, and only if the reviewer knows the rule.
2. **Lint and automated checks only.** Rejected as insufficient, not wrong. A check catches
what can be expressed mechanically; most of these rules are about judgement — what belongs
in a repository, when a criterion counts as verified.
3. **A canonical rule set, injected into context wherever work is decided, with a check phase
before output is accepted.** Chosen.
## Decision
A single canonical document states the mesh's non-negotiable rules. It is **injected
proactively** into every eligible design and analysis session — agents do not fetch it, it
arrives — and a check phase verifies the session's output against it before the work proceeds.
It is a governed document, not a page. Changing it requires a proposal, sign-off by reviewers
who are not the proposer, and a recorded decision. Drive-by edits are reverted.
Scoped override pages may **tighten** it for a team or product. They may never relax it.
## Consequences
- A rule reaches the work whether or not anyone remembered it existed.
- The check phase makes a violation a blocking outcome rather than a review comment.
- Two copies of the same rules now exist: this document, and the reasoning in HQ that earned
them. The enforced copy wins by default, so the reasoned copy quietly stops being true —
which is why [`00-GENESIS/how-we-build.md`](../00-GENESIS/how-we-build.md) is now the source
and the governed page is derived from it, via playbook
[`05-constitution-sync.md`](../00-GENESIS/process/05-constitution-sync.md).
- Injection costs context on every eligible turn, and grows with the document. Nothing
currently bounds that.
- The amendment process requires two reviewers, which a mesh with one human operator satisfies
only by counting agents. That tension is real and unresolved.
## References
- The governed page was authored 2026-07-10 and carries its own amendment process.
- `feat(noxflow): HAL architectural conformance gate for reviewer + architect` (#296),
2026-06-10 — the check phase, predating the document it checks against.
- Knowledge base: `platform/constitution`.
adr/0010-applications-live-in-their-own-repository.md
+64
View File
@@ -0,0 +1,64 @@
---
status: accepted
date: 2026-07-10
deciders: jochen
reconstructed: true
---
# 10. Applications live in their own repository; the monorepo is for the mesh
> Reconstructed after the fact from the evidence cited below.
## Context
The module system makes adding anything to the monorepo trivial — a directory and a manifest.
That ease is the problem. Standalone applications, sites and side-projects accumulated beside
the mesh's own components, and once there they inherited the monorepo's review cadence, its
pipeline detection, and its history.
The mesh's own code and an application that merely runs on the mesh have nothing in common
except the manifest format. They change for different reasons, are reviewed by different
criteria, and have no reason to share a branch.
## Considered options
1. **Everything in the monorepo.** Rejected — it is what existed. The monorepo becomes an
inventory of one installation's applications, and every application change queues behind
mesh review.
2. **A second monorepo for applications.** Rejected: the same coupling with an extra name.
Applications have no more in common with each other than with the mesh.
3. **One repository per application, registered with the mesh as a build source.** Chosen.
## Decision
Every standalone application, site or side-project lives in its own repository, with a manifest
at the root. It registers with the mesh as a build source and is then built, provisioned,
deployed and verified by exactly the same pipeline as anything in the monorepo.
The monorepo holds the mesh: the runtime, the core modules, the delivery machinery, and the
shared infrastructure the mesh itself provisions against.
Creating an application directory in the monorepo is a convention violation, and reviewers
reject it.
## Consequences
- An application's cadence is its own. It is not reviewed as mesh code and does not queue
behind mesh work.
- The separation is safe **only because** the pipeline and provisioning are identical either
side of it — which [ADR 0007](0007-no-npm-workspace.md) is what makes true. Without
standalone packages this decision would fork the build.
- The monorepo stops being an inventory of the installation, which is a precondition for
publishing anything about it.
- Discovery gets harder: there is no single listing of everything the mesh runs, and the
registry of build sources becomes the closest thing to one.
- A module source that is not registered is silently skipped by the pipeline. The cost of
being outside the monorepo is that being forgotten is possible.
## References
- The rule is stated in the governed constitution page authored 2026-07-10, §3, as a
convention violation reviewers must reject.
- [ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) decision 4 extends this from *new*
applications to the modules already in the monorepo.
- Knowledge base: `troubleshooting/unregistered-module-source`.
adr/0011-the-installer-owns-linking.md
+58
View File
@@ -0,0 +1,58 @@
---
status: accepted
date: 2026-07-10
deciders: jochen
reconstructed: true
---
# 11. The installer owns linking; nothing else creates a symlink
> Reconstructed after the fact from the evidence cited below. The incident that earned the rule
> predates the record, and its date is not established here.
## Context
A service's definition lives in the module catalogue; its runtime directory and persistent data
live outside it. The mesh connects the two by linking the definition into the runtime location
— deliberately, so that runtime state and source stay separate while the running service reads
a current definition.
A link is also the easiest thing in the world to create by hand while fixing something, and a
container engine resolves a bind mount through it. A hand-made link pointed a volume somewhere
it should not have, and **production data was lost**.
## Considered options
1. **Copy instead of linking.** Rejected. A copy goes stale silently, which trades data loss
for a service running a definition nobody can find.
2. **Allow links, document the hazard.** Rejected. The hazard is not knowable at the moment of
the mistake — the link looks right and the resolution happens inside the container engine.
3. **One component owns linking; everyone else is forbidden.** Chosen.
## Decision
The installer creates and repairs every link the mesh needs. It reconciles them: a missing
link is created, a stale one is repointed, and a real file found where a link belongs is
adopted into the node's override location and replaced.
**Nothing else creates a symlink** — not a hook, not a fix, not an agent, not a person
debugging. The prohibition is absolute because the judgement required to make a safe exception
is exactly the judgement that was not available at the moment it mattered.
## Consequences
- The class of failure is closed, at the cost of a rule that reads as arbitrary to anyone who
has not seen the incident. That is why it is recorded here rather than only asserted.
- Links become reconcilable state rather than incidental filesystem facts.
- The rule is stated for humans and agents and is enforced by convention, not mechanism. A
check does not exist.
- The rule is regularly misread as "the mesh does not use symlinks", which is false and makes
the design documentation look self-contradictory. It uses them; it centralises who may make
them.
## References
- Recorded as a non-negotiable in the governed constitution page, §2: *"Symlinks to repos or
service directories have caused production data loss via Docker volume path resolution. The
installer handles all linking. Never create symlinks manually."*
- Knowledge base: `services` — the reconciliation behaviour, including adoption of real files.
adr/0012-agents-are-persistent-employees.md
+74
View File
@@ -0,0 +1,74 @@
---
status: accepted
date: 2026-07-12
deciders: jochen
reconstructed: true
---
# 12. An agent is a persistent employee, not an instance of a pool
> Reconstructed after the fact from the evidence cited below.
## Context
Agents were originally a **pool**: a named kind of worker, scaled to some number of
interchangeable instances. Work went to whichever instance was free.
That model has no place to put the things that turn out to matter. An agent that accumulates
knowledge of a domain cannot keep it, because the next task lands on a different instance. An
agent cannot own a workspace, because there are several of it. It cannot be held to a policy —
warned for a violation, then dismissed — because there is no continuing subject to warn.
Scaling was also solving a problem the mesh does not have. Instances were being multiplied to
get concurrency, when concurrency is a property of how much work one agent may hold at once.
## Considered options
1. **Keep the pool, attach memory to the pool.** Rejected: shared memory across
interchangeable workers is a knowledge base, not an agent's experience, and the mesh
already has one.
2. **Keep the pool, make instances sticky.** Rejected as a pool pretending to be identities —
identity by scheduling accident, lost on any restart.
3. **One agent is one persistent identity, with concurrency as a property of it.** Chosen.
## Decision
An agent is a **singular, named, persistent identity**: a home node, a workspace on that node,
accumulating memory, and a lifecycle — hired, active, draining, retired. Not a pool member.
Concurrency is a property of the agent, not a count of copies: an agent has a cap on how many
sessions it may hold at once.
Lifecycle is explicit and has verbs. An agent is hired onto a node; it may be reassigned while
idle; it is retired by draining first, and forced only deliberately. Retired agents are not
deleted.
Surge capacity is expressed within the model rather than against it: a template agent is a
blueprint, cloned into a real agent with a lifetime when a queue grows, drained and retired
when it expires. A temporary employee is still an employee.
Some agents are **human**. What differs is modality — how the agent acts — not category. A node
itself is an agent of a kind exempt from the hiring lifecycle.
## Consequences
- Memory, workspace and reputation have a subject to belong to. Policy becomes possible: an
agent that violates a rule can be warned, and warned agents can be dismissed.
- The mesh gained a hiring model, and with it the question of who may hire.
- Scaling by adding instances is gone. If one agent is saturated, either its session cap rises
or another agent is hired — both deliberate acts.
- The transition was not free. Lifecycle columns had to reach every query that selects an
agent, and the ones that were missed failed at the moment of hiring rather than at startup.
- This is the decision [ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) generalises:
one kind of participant, differing only in modality.
## References
- `docs(adr): agents as persistent employees + MINERVA librarian` (#495), 2026-07-12 — the
original record, in the code repository.
- `feat(B4): one persistent employee, N sessions — rename max_instances → max_sessions` (#547)
and `feat(noxflow): B3 — workspace provisioner for agent employee model` (#549), 2026-07-20.
- `feat(noxflow): warn-then-fire agents who merge to main without review` (#209), 2026-06-01 —
policy that presumes a continuing subject, predating the model that provides one.
- Knowledge base: `agents/employee-lifecycle`, `agents/temp-surge`, `agents/workspace-layout`.
- The migration cost: `troubleshooting`/`noxflow-agent-enriched-select-missing-lifecycle-columns` (#546).
adr/0013-an-artifact-is-build-output.md
+63
View File
@@ -0,0 +1,63 @@
---
status: accepted
date: 2026-08-04
deciders: jochen
reconstructed: true
---
# 13. An artifact is build output, never a source tree
> Reconstructed after the fact from the evidence cited below.
## Context
A module is built once and deployed to every node assigned to it. What travels between those
two events is the artifact.
For a long time the artifact was a filtered copy of the module's source directory. Deploying it
therefore meant resolving and installing its dependencies **on the target node** — which
requires the target to reach a package registry, at deploy time, for every node, every deploy.
A node with no route to the registry could not deploy code that had already been built
successfully.
## Considered options
1. **Ship source, install dependencies on the target.** Rejected — it is what existed. Deploy
becomes a network operation with a failure mode per node, and the code that runs is
assembled independently on each one.
2. **Ship source plus its resolved dependency tree.** Rejected: large, slow, and it ships the
dependency resolution's platform assumptions along with it.
3. **Ship a self-contained build output; a failed bundle fails the build.** Chosen.
## Decision
The artifact is the module's **build output directory** — compiled and bundled, with its
dependency graph inlined. Deploy is extract-and-run and touches no network.
A build that cannot produce a self-contained output **fails**. It does not fall back to
shipping a dependency tree, because a fallback that works is a fallback that is never fixed —
an application of [ADR 0008](0008-a-failed-step-fails-the-job.md).
## Consequences
- A node can deploy without reaching a registry. What was built is what runs, identically, on
every node.
- Deploys are faster and their failure modes are local.
- **Everything not in the build output does not ship.** This is the decision's whole cost, and
it was paid several times before it was understood: migrations that read the source layout,
provisioning scripts that read the source layout, selection files never packaged at all. Each
worked in development, where the source is present, and silently did nothing after deploy.
- Any file a module needs at runtime must be deliberately placed into the build output. The
rule "the artifact is `dist/`" has to be applied to every file kind, not just compiled code,
and that generalisation was the expensive part.
- Bundling has its own failure modes that a compiler will not catch — a bundler can exit
successfully and produce output that cannot load.
## References
- `build: bundle artifacts so a deploy is extract-and-run` (#673), 2026-08-04.
- The consequences, in order: `Provision migrations and seeds read the source layout, not the
artifact` (#699), `Local migrations read the source layout too` (#700), both 2026-08-07.
- Knowledge base: `pipeline/artifacts-are-build-output`, `pipeline/bundling`,
`troubleshooting/shell-migrations-never-packaged`, `troubleshooting/flavors-never-packaged`,
`troubleshooting/esbuild-silent-tla-breakage`.
adr/0014-build-publish-and-deploy-are-three-silos.md
+78
View File
@@ -0,0 +1,78 @@
---
status: accepted
date: 2026-08-04
deciders: jochen
reconstructed: true
---
# 14. Build, publish and deploy are three silos with different cardinality
> Reconstructed after the fact from the evidence cited below.
## Context
Delivery had been treated as one pipeline that a module passes through. It is not: its stages
run a different number of times.
- Compiling happens **once per module feature**, on the build node.
- Packaging and uploading happens **once per module feature**, on the build node.
- Installing, configuring, starting and verifying happens **once per module feature per node**.
Conflating them is what made earlier versions slow and hard to reason about. Work that should
happen once was being repeated per node, and the fan-out point was implicit rather than a
boundary anything could observe.
The split had been declared before it was real. Packaging still happened inside the build,
which meant the boundary existed in the documentation and not in the code.
## Considered options
1. **One pipeline, stages that know their own cardinality.** Rejected — it is what existed.
Cardinality is then a property of each stage's implementation, and nothing can reason about
the pipeline as a whole.
2. **Two silos: build-and-publish, then deploy.** Rejected. It leaves packaging inside build,
so build must know every module, every feature, and how each composes its artifact —
exactly the coupling the split exists to remove. A failed upload then retries by re-sending
a stale package instead of re-packaging.
3. **Three silos, with an explicit handover between each.** Chosen.
## Decision
Delivery is three silos, and the boundaries are real:
| Silo | Runs | Where |
|---|---|---|
| **build** | once per module feature | the build node |
| **publish** | once per module feature | the build node |
| **deploy** | once per module feature **per node** | every assigned node |
Commands and events are addressed **per feature**, not per module.
Build compiles and hands over a **staged tree** — not a package. Publish applies the module's
packaging rules, packages that tree, and uploads it. Publishing to a package registry *is*
publishing, so a module whose artifact is a package publishes in the publish silo, not the
build one.
Modules are resolved into dependency **levels**, and a level completes before the next begins,
so a module always builds against its dependencies' freshly published versions.
## Consequences
- Work that should happen once happens once. The fan-out point is explicit and observable.
- A failed upload retries by re-packaging, because packaging belongs to the stage that
uploads.
- The handover is a staged tree in a known location rather than the build's working directory,
which is reference-counted and cannot be assumed to still exist when a later stage runs.
- The build node is now the only node that has already passed through two silos when the
fan-out happens. Anything tracking a node's stage must account for **both** pre-fan-out
stages; code that knew only about the first parked the build node forever while every other
node deployed cleanly.
- A recovery mechanism that knows a subset of the stages it guards is worse than none — it
reports success over a stall it cannot see.
## References
- `publish owns packaging — the silos were not actually split` (#677), 2026-08-04.
- Knowledge base: `pipeline/three-silos` — including the note that the older architecture
documents claimed otherwise and were stale until 2026-08-06.
- The build-node stage-tracking failure was observed on pipeline #5557.
adr/0001-mesh-brokers-nodes-host-agents-think.md → adr/0015-mesh-brokers-nodes-host-agents-think.md
+7 -4
View File
@@ -1,8 +1,11 @@
# 1. The mesh brokers capabilities; nodes host; agents think
---
status: accepted
date: 2026-08-22
deciders: jochen
reconstructed: false
---
- **Status:** Accepted
- **Date:** 2026-08-22
- **Deciders:** jochen
# 15. The mesh brokers capabilities; nodes host; agents think
## Context
adr/0002-a-lab-node-is-a-virtual-machine.md → adr/0016-a-lab-node-is-a-virtual-machine.md
+9 -6
View File
@@ -1,12 +1,15 @@
# 2. A lab node is a virtual machine running the real install
---
status: accepted
date: 2026-08-22
deciders: jochen
reconstructed: false
---
- **Status:** Accepted
- **Date:** 2026-08-22
- **Deciders:** jochen
# 16. A lab node is a virtual machine running the real install
## Context
[ADR 0001](0001-mesh-brokers-nodes-host-agents-think.md) makes a local mesh a prerequisite
[ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) makes a local mesh a prerequisite
rather than a convenience: *"everything that manifests between nodes is discoverable only in
production, which is where every fault of 2026-08-22 was found."*
@@ -128,7 +131,7 @@ than staging means every certificate experiment on a real node consumes issuance
the four host couplings that only obstruct a container-shaped node
- [`01-RESEARCH/004-lab-network`](../01-RESEARCH/004-lab-network/analysis.md) — the topology
being reproduced and the endpoint constraint
- [`02-DESIGN/01-end-to-end-testing.md`](../02-DESIGN/01-end-to-end-testing.md) — what the lab
- [`02-DESIGN/01-end-to-end-testing.md`](../02-DESIGN/01-to-be/01-end-to-end-testing.md) — what the lab
is for
- `modules/wireguard/hooks/index.ts:206-240` — the endpoint rule, and the incident comments
recording what it cost to get right
adr/0017-modules-outside-the-core-are-grouped-by-domain.md
+93
View File
@@ -0,0 +1,93 @@
---
status: proposed
date: 2026-08-23
deciders: jochen
reconstructed: false
extends: 0015-mesh-brokers-nodes-host-agents-think.md
---
# 17. Modules outside the platform core are grouped by domain, not by single function
## Context
[ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) recomposes the platform's own modules
into bounded contexts named after their aggregates, and sends the rest out of the monorepo on
the grounds that they run *on* the mesh rather than being *of* it.
That leaves the larger half unaddressed. Around three quarters of the catalogue are modules
that are neither part of the mesh's domain nor standalone applications: a firewall, a VPN, an
SSH daemon and a resolver; a file manager, a media player and a system monitor; a set of
media-library services. Today each is its own module, because one module is the unit of *one
piece of software*, and no other grouping exists.
The result is that the catalogue's shape records what was installed, not what anything is for.
Four modules that together constitute "how a node is reachable" have no relationship the mesh
can see: they cannot be assigned, versioned, reasoned about or replaced as one thing, and a
change to how the mesh handles connectivity has to be made four times.
This is the same failure ADR 0015 names for the core — *boundaries drawn by deployment accident
rather than by domain* — appearing outside it.
## Considered options
1. **Leave them as they are.** Rejected. The core gets domain boundaries and everything else
keeps accident boundaries, so the catalogue becomes harder to read after the refactor than
before it.
2. **One module per piece of software, with a tag or category field.** Rejected. A label is not
a boundary: it does not change what can be assigned, versioned or replaced as a unit, and it
drifts from the thing it labels.
3. **Group them into domain modules, each owning the software that serves one purpose.**
Proposed here.
4. **Extend ADR 0015's contexts to cover everything.** Rejected. Those contexts are named for
the mesh's own aggregates; a media library is not an aggregate of the mesh, and forcing it
into that model repeats the metaphor-naming mistake ADR 0015 exists to correct.
## Decision
*Proposed — the principle is settled; the domain list is not. See "Open" below.*
Modules that are not part of the platform core are grouped into **domain modules**. A domain
is named for the concern it serves, and owns the software that serves it. The unit stops being
one piece of software and becomes one purpose.
This extends ADR 0015 rather than replacing it. The eight bounded contexts for the mesh's own
domain stand unchanged. This decision covers what ADR 0015 leaves outside them.
Naming follows the same rule as the core: **name the domain for what it does, not for what it
is made of**. Connectivity, not a VPN implementation.
## Consequences
- A domain becomes assignable, versionable and replaceable as one thing. Changing how nodes
reach each other is a change to one module.
- The catalogue's shape starts describing purpose. A reader can tell what a mesh is *for* from
its module list.
- Swapping an implementation stops being a module replacement, with the data-volume and
provisioning consequences that carries, and becomes a change inside a domain.
- The count drops sharply, which is a symptom of the improvement rather than the point of it.
- **Grouping conceals.** A domain module hides which implementation is in use, and every
operational question — which port, which unit, which credential — gains an indirection.
- The migration is not free and has no obvious increments: a domain is only useful once
everything belonging to it has moved.
- Some modules genuinely serve one purpose and are already correctly sized. Grouping for its
own sake would be the same error in the other direction.
## Open
**The domain list is not settled and this record does not invent one.** What is decided is the
principle; what is not decided is the set. Candidate groupings are visible in the catalogue —
connectivity and reachability, node presentation and desktop, media libraries, observation and
metrics, storage and data services — but naming them here would be reconstructing a decision
that has not been taken.
Settling the list is a research effort, not an act of this record. Until it concludes, this
ADR stays `proposed`.
## References
- [ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) — the core decomposition this
extends, and its rule about naming a context after its aggregate.
- [ADR 0010](0010-applications-live-in-their-own-repository.md) — standalone applications are
already out of scope here; they are not domains and do not group.
- [`02-DESIGN/00-as-is/10-module-catalogue.md`](../02-DESIGN/00-as-is/10-module-catalogue.md)
— the catalogue's current shape, which is the evidence for the problem.
adr/README.md
+40 -17
View File
@@ -1,30 +1,53 @@
# Architecture Decision Records
One file per decision, numbered, never deleted. A superseded ADR gets its status changed
and a pointer to what replaced it — the reasoning that was rejected is the expensive half
to rediscover.
One file per decision, numbered, never deleted. A superseded record has its `status:` changed
and gains a pointer to what replaced it — **its text is never edited**. The reasoning that was
rejected is the expensive half to rediscover.
## Format
The records are a **ledger**: they run in the order the decisions were taken, oldest first.
## Frontmatter
```yaml
---
status: proposed | accepted | superseded
date: YYYY-MM-DD # when the decision was taken, not when it was written down
deciders: name
reconstructed: true|false # true when the record was written after the fact from evidence
superseded-by: # adr/NNNN-....md, when status is superseded
extends: # adr/NNNN-....md, when this record widens an earlier one
---
```
## Body
```
# N. Title in plain language
- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
- **Date:** YYYY-MM-DD
- **Deciders:**
## Context what is true today, with evidence
## Context what was true, with evidence
## Considered Options numbered, each with why it was rejected
## Decision what we are doing
## Consequences what follows, including what gets harder
## References code, data, prior art
## Decision what was decided
## Consequences what follows, including what got harder
## References commits, pull requests, knowledge-base entries, prior art
```
State evidence, not assertion. "Zero of 124 modules declare `brain` as a dependency"
outranks "the dependency rule is not followed".
State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"*
outranks *"the dependency rule is not followed"*.
## Reconstructed records
Records 0001–0014 were written on 2026-08-23, after the decisions they describe. Those
decisions were taken in implementation rather than in a document; the records state what was
decided and the evidence it was decided from, and each carries `reconstructed: true` and says
so in its first lines.
A reconstructed record is not a transcript. Where the deliberation is not recoverable, the
options section states what the alternatives were and why the chosen one won on the evidence
available — not a discussion that did not happen. Where a date is not establishable it says so
rather than guessing.
## Index
| ADR | Title | Status |
|-----|-------|--------|
| [0001](0001-mesh-brokers-nodes-host-agents-think.md) | The mesh brokers capabilities; nodes host; agents think | Accepted |
The index is **generated, not maintained** — run the `hal-status` skill, which reads the
frontmatter of every record. A hand-written index drifts from the folder it describes, and
this one had already done so after a single addition.