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

Order the records the way the system is learned

Browse Source 
Jochen asked whether the order made sense. It did not -- it followed when
things happened to be decided, which after consolidation is fictional anyway
since record 5 alone folds decisions taken across a week.

Concretely wrong before: the domain statement sat at 8, after five engineering
rules; the constitution was scattered across 5, 12 and 17; the tiers landed at
15, 16, 21 and 22 with process records in between.

Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what
runs on them and how it gets there (9-10), how it is built (11-16), how it is
checked (17-18), how we work (19-23).

Two things made this safe rather than free. It is a permutation, not a
compaction, so the renames go through temporary names -- otherwise two files
want one slot and one is lost. And the reference rewrite is a single
simultaneous pass, because almost every number moved into a slot another number
was vacating; replacing one at a time would have cascaded and pointed things at
the wrong record while still resolving.

Verified: 284 [ADR NNNN](path) links across the repository, all with matching
text and target.

The ordering principle is now stated in 19 rather than left implicit -- the
repository already said "the numbering is the flow" about its folders, and
there was no reason for the records to be the exception.
This commit is contained in:
jschoubben
2026-08-28 23:30:42 +02:00
parent e1febe8e0f
commit 333356cff3
85 changed files with 471 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/00-as-is/00-overview.md
+12 -12
View File
@@ -4,9 +4,9 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0021-the-substrate-and-the-control-plane.md
- 02-DECISIONS/0002-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0006-the-substrate-and-the-control-plane.md
---
# The mesh as it stands
@@ -28,11 +28,11 @@ onto it and can be regenerated.
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 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)).
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.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 0007](../../02-DECISIONS/0007-agents-are-persistent-employees.md)).
([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)).
## Where truth lives
@@ -40,10 +40,10 @@ The repository defines **what exists**: the modules, what each declares, how eac
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 0021](../../02-DECISIONS/0021-the-substrate-and-the-control-plane.md)).
is ever committed ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)).
Everything on a node's disk is **derived** from those two, and is regenerated rather than
edited ([ADR 0002](../../02-DECISIONS/0002-managed-files-are-generated-never-edited.md)). A node that
edited ([ADR 0011](../../02-DECISIONS/0011-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.
@@ -51,7 +51,7 @@ cost: the cache carries no indication of its own age.
Nothing dials a node. Every node dials the broker outbound, owns an exchange named for itself,
and consumes from its own request queue
([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md)). Three message shapes carry
([ADR 0002](../../02-DECISIONS/0002-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.
@@ -65,9 +65,9 @@ goes to where the capability is.
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 0023](../../02-DECISIONS/0023-delivery.md)). What travels between
([ADR 0010](../../02-DECISIONS/0010-delivery.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 0023](../../02-DECISIONS/0023-delivery.md)).
network ([ADR 0010](../../02-DECISIONS/0010-delivery.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.
@@ -78,7 +78,7 @@ A module declares what it **provides** and what it **requires**. The mesh satisf
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 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)).
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.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.
@@ -92,7 +92,7 @@ named for a feature the module does not declare, a stage that reported it had di
message rather than that the effect happened, a package that 404ed from every mirror while the
job went green.
[ADR 0023](../../02-DECISIONS/0023-delivery.md) is the response, and it is applied
[ADR 0010](../../02-DECISIONS/0010-delivery.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.
03-DESIGN/00-as-is/01-mesh-and-transport.md
+2 -2
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0021-the-substrate-and-the-control-plane.md
- 02-DECISIONS/0002-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0006-the-substrate-and-the-control-plane.md
---
# The mesh and its transport
03-DESIGN/00-as-is/02-modules-and-manifests.md
+5 -5
View File
@@ -4,9 +4,9 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0003-schema-changes-are-numbered-migrations.md
- 02-DECISIONS/0004-no-npm-workspace.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0013-schema-changes-are-numbered-migrations.md
- 02-DECISIONS/0014-no-npm-workspace.md
---
# Modules, manifests and features
@@ -81,7 +81,7 @@ recorded in the knowledge base; both presented as "the change did not apply" wit
## Dependencies between modules
Modules depend on each other, above all on the shared library they all build against. There is
**no workspace** ([ADR 0004](../../02-DECISIONS/0004-no-npm-workspace.md)): each module is a standalone
**no workspace** ([ADR 0014](../../02-DECISIONS/0014-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
@@ -96,7 +96,7 @@ since (see
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 0003](../../02-DECISIONS/0003-schema-changes-are-numbered-migrations.md)).
([ADR 0013](../../02-DECISIONS/0013-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
03-DESIGN/00-as-is/03-provisioning.md
+2 -2
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0002-managed-files-are-generated-never-edited.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0011-managed-files-are-generated-never-edited.md
---
# Provisioning
03-DESIGN/00-as-is/04-delivery.md
+5 -5
View File
@@ -4,9 +4,9 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0023-delivery.md
- 02-DECISIONS/0023-delivery.md
- 02-DECISIONS/0023-delivery.md
- 02-DECISIONS/0010-delivery.md
- 02-DECISIONS/0010-delivery.md
- 02-DECISIONS/0010-delivery.md
---
# Delivery — from a push to a running node
@@ -31,7 +31,7 @@ merge that created no pipeline, and nothing said so**.
## Three silos
Cardinality is the whole point, and the three differ
([ADR 0023](../../02-DECISIONS/0023-delivery.md)):
([ADR 0010](../../02-DECISIONS/0010-delivery.md)):
| Silo | Runs | Where | Does |
|---|---|---|---|
@@ -50,7 +50,7 @@ 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 0023](../../02-DECISIONS/0023-delivery.md)).
never a filtered copy of source ([ADR 0010](../../02-DECISIONS/0010-delivery.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
03-DESIGN/00-as-is/05-runtime-and-installation.md
+5 -5
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0010-the-mesh-creates-no-symlinks.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0012-the-mesh-creates-no-symlinks.md
---
# The node runtime, and how a node comes into being
@@ -38,7 +38,7 @@ suggestive word in the system names the node runtime, and the component whose ma
"mesh messaging" is documented elsewhere as the interactive runtime. Anatomy makes attractive
names and poor boundaries.
[ADR 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md) replaces this with names
[ADR 0001](../../02-DECISIONS/0001-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
@@ -57,14 +57,14 @@ outstanding local migrations, create data directories with the right ownership,
service under supervision.
**The installer is the only thing that creates a link** ([ADR
0011](../../02-DECISIONS/0010-the-mesh-creates-no-symlinks.md)). It reconciles rather than assumes: a
0011](../../02-DECISIONS/0012-the-mesh-creates-no-symlinks.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.
That is the as-is. The intent is to remove linking altogether and derive a real file instead,
which the reconciliation machinery already makes possible
([ADR 0010](../../02-DECISIONS/0010-the-mesh-creates-no-symlinks.md), proposed). What is described above
([ADR 0012](../../02-DECISIONS/0012-the-mesh-creates-no-symlinks.md), proposed). What is described above
is what runs today.
## Supervision
03-DESIGN/00-as-is/06-configuration-and-secrets.md
+4 -4
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0002-managed-files-are-generated-never-edited.md
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0011-managed-files-are-generated-never-edited.md
- 02-DECISIONS/0009-modules-and-the-graph.md
---
# Configuration and secrets
@@ -17,7 +17,7 @@ files is **generated**.
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 0002](../../02-DECISIONS/0002-managed-files-are-generated-never-edited.md)).
output ([ADR 0011](../../02-DECISIONS/0011-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,
@@ -61,7 +61,7 @@ are both left behind. Configuration is additive in practice, whatever the manife
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 0019](../../02-DECISIONS/0019-modules-and-the-graph.md)).
([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.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.
03-DESIGN/00-as-is/07-knowledge.md
+1 -1
View File
@@ -40,7 +40,7 @@ owning approval and promotion at the boundary. Proposals to edit are reviewed ra
applied.
This is where the mesh's **governed** documents live, including the constitution injected into
design sessions ([ADR 0005](../../02-DECISIONS/0005-the-mesh-is-governed-by-a-constitution.md)).
design sessions ([ADR 0020](../../02-DECISIONS/0020-the-mesh-is-governed-by-a-constitution.md)).
## Why both
03-DESIGN/00-as-is/08-agents-and-work.md
+6 -6
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0007-agents-are-persistent-employees.md
- 02-DECISIONS/0005-the-mesh-is-governed-by-a-constitution.md
- 02-DECISIONS/0003-agents-are-persistent-employees.md
- 02-DECISIONS/0020-the-mesh-is-governed-by-a-constitution.md
---
# Agents and work
@@ -17,7 +17,7 @@ model they run under is the employee model, not a worker pool.
An agent is a singular named identity with a home node, a workspace on that node, accumulating
memory, and an explicit lifecycle
([ADR 0007](../../02-DECISIONS/0007-agents-are-persistent-employees.md)).
([ADR 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)).
| Property | Meaning |
|---|---|
@@ -45,7 +45,7 @@ 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 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md).
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md).
## Work
@@ -70,7 +70,7 @@ 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 0005](../../02-DECISIONS/0005-the-mesh-is-governed-by-a-constitution.md)). A named violation
([ADR 0020](../../02-DECISIONS/0020-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
@@ -84,5 +84,5 @@ integrate through the record, never through a shared schema* — being violated
own largest component, and it is the reason work that belongs to one domain keeps having to be
implemented in another.
[ADR 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement.
[ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement.
Until it does, this is the shape.
03-DESIGN/00-as-is/09-interfaces-and-observability.md
+2 -2
View File
@@ -4,8 +4,8 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0001-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0023-delivery.md
- 02-DECISIONS/0002-nodes-communicate-over-a-broker.md
- 02-DECISIONS/0010-delivery.md
---
# Interfaces and observability
03-DESIGN/00-as-is/10-module-catalogue.md
+8 -8
View File
@@ -4,16 +4,16 @@ status: implemented
code: [hal]
updated: 2026-08-23
decisions:
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0006-applications-live-in-their-own-repository.md
- 02-DECISIONS/0019-modules-and-the-graph.md
- 02-DECISIONS/0009-modules-and-the-graph.md
- 02-DECISIONS/0015-applications-live-in-their-own-repository.md
- 02-DECISIONS/0009-modules-and-the-graph.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 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md)).
([ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md)).
The count is not the finding. The **shape** is.
@@ -55,11 +55,11 @@ connectivity is made four times.
the unit of one piece of software, because that is the only granularity the module system
offers.
This is the same failure [ADR 0008](../../02-DECISIONS/0008-mesh-brokers-nodes-host-agents-think.md)
This is the same failure [ADR 0001](../../02-DECISIONS/0001-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 0019](../../02-DECISIONS/0019-modules-and-the-graph.md), which
[ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md), which
deliberately does not yet settle the domain list.
## Where the shape came from
@@ -90,7 +90,7 @@ never stated as assumptions — they were just how the thing already worked.
**This is the most useful single fact for anyone changing the catalogue**, and it is why the
linking principle in particular reads as a deliberate architectural choice when it is an
inheritance. See [ADR 0010](../../02-DECISIONS/0010-the-mesh-creates-no-symlinks.md), whose case
inheritance. See [ADR 0012](../../02-DECISIONS/0012-the-mesh-creates-no-symlinks.md), whose case
this strengthens: the argument for links was never made *for a mesh*.
It also explains the measurement in
@@ -108,7 +108,7 @@ which is what makes dogfooding structural rather than a discipline, and what mak
module out of the repository safe.
**Placement is already decided.** A standalone application belongs in its own repository
([ADR 0006](../../02-DECISIONS/0006-applications-live-in-their-own-repository.md)), and reviewers reject
([ADR 0015](../../02-DECISIONS/0015-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.
03-DESIGN/00-as-is/11-the-lab.md
+7 -7
View File
@@ -4,11 +4,11 @@ status: implemented
code: [mesh-lab]
updated: 2026-08-25
decisions:
- 02-DECISIONS/0009-the-lab.md
- 02-DECISIONS/0009-the-lab.md
- 02-DECISIONS/0009-the-lab.md
- 02-DECISIONS/0009-the-lab.md
- 02-DECISIONS/0009-the-lab.md
- 02-DECISIONS/0016-the-lab.md
- 02-DECISIONS/0016-the-lab.md
- 02-DECISIONS/0016-the-lab.md
- 02-DECISIONS/0016-the-lab.md
- 02-DECISIONS/0016-the-lab.md
---
# The lab, as it stands
@@ -63,7 +63,7 @@ is built.
**The drawing was never designed.** `diagram` renders a scenario as draw.io, from the
declaration or from the running instance, and it exists because it was asked for during the
build. It has tests and a decision record ([ADR 0014](../../02-DECISIONS/0014-a-picture-is-read-from-what-runs.md),
build. It has tests and a decision record ([ADR 0018](../../02-DECISIONS/0018-a-picture-is-read-from-what-runs.md),
proposed) but no document in the to-be layer. It is recorded here because it runs, not because
it was planned.
@@ -117,7 +117,7 @@ and snapshots roughly 76× slower, which does not make the lab slow, it makes it
`npm run check` — typecheck over source *and* tests, then the offline suite, then integration
against a real hypervisor. Mocking the hypervisor is forbidden
([ADR 0013](../../02-DECISIONS/0013-a-test-defends-a-decision.md), proposed): a test that fakes
([ADR 0017](../../02-DECISIONS/0017-a-test-defends-a-decision.md), proposed): a test that fakes
the system under integration asserts that the fake behaves as expected.
Integration tests **skip with a reason** on a machine that cannot raise scenarios, rather than