jschoubben
b4607dfc03
Decided after measuring what renumbering actually costs: 96 references in code comments across two repositories, none of which would have failed to compile. They would have pointed at the wrong reasoning, which is worse than a broken link because nothing reports it. So a number identifies a record and never changes. It cannot also be a position -- a position moves when the set changes, and an identity that moves is not one. The reading order moves into an index generated from each record's `topic:`. Six topics, in the order somebody learns the system. The index is WRITTEN rather than only generated on demand, which reverses what this repository previously said. The reason it said otherwise is that a hand-written index drifts -- but a reader looking at the folder on a forge sees the folder, not a command, and the drift objection is answered by checking rather than by refusing to write one. That is §5's own rule: a rule states how it is checked. Two checks, both confirmed to bite. index.py fails when the written order no longer matches the records. records.py fails when a record has no topic or one nobody defined -- the quiet failure being a record that vanishes from the order rather than appearing in the wrong place.
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
---
|
|
topic: building it
|
|
status: accepted
|
|
date: 2026-07-10
|
|
deciders: jochen
|
|
reconstructed: true
|
|
---
|
|
|
|
# 15. 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 0014](0014-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 0001](0001-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`.
|