jschoubben
cb1954e7b5
**0024 accepted.** Model access was decided, built, and proven in the lab, and two design documents rest on it; only the status had never moved. The gate is green again. **The work breakdown rewritten.** It planned a decomposition of the existing system in place — extract contexts, declared features, shrink the shared library. That is not the work. A replacement is being built beside it, and only the old Phase 0 survived contact with reality, so the one document meant to say what happens next was describing a system being retired. Now ordered by what "modules move across one at a time until the old registry is off" actually requires: - Phase 0 is marked done against the twenty-two lab assertions, **and carries its own limitation**: every module exercised was written to test the mechanism, so the vocabulary was shaped by its own fixtures. - Phase 1 is the vocabulary gaps found by asking what real modules need — an object-store provision, a session as a licence consumer, a network shape with ordering, public certificate issuance. - Phase 2 is one module, then a week of running it, because the point of going first is to find what Phase 1 missed. - Phase 3 picks modules that each prove something the first did not; the mail system is last because it is the one that may send work back into the declaration language. - Phase 4 is switching the registry off, named as a phase so it is not mistaken for the goal. Keeps the rules of engagement unchanged — they were about how work is done, not what it is — with one addition: stop and ask before anything that touches a machine outside the lab. Adds a section on keeping the list true, since the document it replaces was wrong for weeks and nothing said so. A claim here is counted, not reasoned, and a phase is done when the lab says so.
174 lines
9.2 KiB
Markdown
174 lines
9.2 KiB
Markdown
---
|
|
layer: to-be
|
|
status: designed
|
|
code: []
|
|
updated: 2026-08-31
|
|
decisions:
|
|
- 02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md
|
|
- 02-DECISIONS/0005-the-node-host.md
|
|
- 02-DECISIONS/0009-modules-and-the-graph.md
|
|
- 02-DECISIONS/0016-the-lab.md
|
|
- 02-DECISIONS/0028-the-substrate-supplies-the-control-plane-and-nothing-else.md
|
|
---
|
|
|
|
# Work breakdown — replacing what provisions the mesh
|
|
|
|
*Rewritten 2026-08-31. The previous version planned a decomposition of the existing system in
|
|
place: extract contexts, convert modules to declared features, shrink its shared library. That is
|
|
not what is being done — a replacement is being built beside it, and the old plan's Phase 0 was
|
|
the only part that survived contact with it. So the document that was supposed to say what happens
|
|
next had been describing work on a system being retired.*
|
|
|
|
## The goal, in one sentence
|
|
|
|
**Modules move to the new mesh one at a time, until the old registry can be switched off.**
|
|
|
|
Everything below is ordered by what that requires. Nothing here is a rewrite of the old system;
|
|
its modules are the input.
|
|
|
|
## Phase 0 — a mesh that runs — **done**
|
|
|
|
Not *the code exists*. Twenty-two assertions on real machines in the lab, each confirmed to fail
|
|
when the behaviour is removed ([ADR 0016](../../02-DECISIONS/0016-the-lab.md),
|
|
[ADR 0017](../../02-DECISIONS/0017-a-test-defends-a-decision.md)).
|
|
|
|
| what is proven | |
|
|
|---|---|
|
|
| **a mesh comes into being** | a bare machine becomes one; others join with nothing but a token |
|
|
| **credentials** | delivered to both ends with the mesh holding neither; rotated so the old one stops working |
|
|
| **declarations survive reality** | a stopped machine is waited for; one that fell behind catches up unnamed; unassigning takes away exactly what it should; what the mesh says nothing about is left alone |
|
|
| **failure is legible** | a machine that cannot do what it was told is named, with why |
|
|
| **the mesh runs itself** | its own artifact store, and a builder that is a module the mesh assigns |
|
|
| **names and reachability** | internal names, wildcards under a machine, containers reaching other machines, certificates the mesh issued, filtering that matches exactly what was declared |
|
|
| **delivery** | a new commit reaches a machine already running the old one |
|
|
| **model access** | answered by a record, with a key the mesh cannot read |
|
|
|
|
**What Phase 0 does not prove, and it is the important sentence in this document:** every module
|
|
exercised above was written to test the mechanism. **No module from the existing system has ever
|
|
run on this.** The vocabulary was shaped by the things used to test it — the same fault as a
|
|
fixture agreeing with the code it checks
|
|
([`04-ISSUES/005`](../../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md)), at the
|
|
scale of a design.
|
|
|
|
## Phase 1 — the vocabulary a real module needs
|
|
|
|
Found by taking real modules and asking what they would require. Each is a gap in what can be
|
|
*expressed*, not a defect in what is built.
|
|
|
|
| # | task | done when |
|
|
|---|---|---|
|
|
| 1.1 | An **object-store provision** — a module can ask for a bucket ([ADR 0028](../../02-DECISIONS/0028-the-substrate-supplies-the-control-plane-and-nothing-else.md)) | a module requiring it is refused where nothing provides it, and given credentials where something does |
|
|
| 1.2 | **A session as a consumer of a licence** | the two sessions on one machine hold different licences and each uses its own ([`14-model-access.md`](14-model-access.md), [ADR 0026](../../02-DECISIONS/0026-the-mesh-has-a-session-of-its-own.md)) |
|
|
| 1.3 | A **network** shape, and ordering within a module | a module of several containers reaches itself, and one that must start after another does |
|
|
| 1.4 | **Public certificate issuance** | a name reachable from outside is served with a certificate from a public authority, obtained against a **staging** endpoint unless told otherwise ([`04-ISSUES/004`](../../04-ISSUES/004-certificate-issuance-targets-production/00-report.md)) |
|
|
|
|
**1.1 blocks the first module; 1.3 and 1.4 block later ones** and are listed now so they are not
|
|
met as surprises. 1.3 is what a mail system needs and nothing else so far does.
|
|
|
|
**Checkpoint:** each is demonstrated in the lab before the module needing it is attempted.
|
|
|
|
## Phase 2 — the first real module
|
|
|
|
| # | task | done when |
|
|
|---|---|---|
|
|
| 2.1 | Port an **object store** module | it runs on the new mesh, serves a bucket to another module, and its credential rotates |
|
|
| 2.2 | Run it beside the existing one | both exist; nothing depends on the new one yet |
|
|
| 2.3 | Move one dependent onto it | something real reads and writes through the new mesh's copy |
|
|
|
|
**Checkpoint, and it is a human one:** it runs for a week before anything else moves. The point of
|
|
going first is to find what Phase 1 missed, and a week is roughly how long that takes to show.
|
|
|
|
## Phase 3 — the modules that prove the shape
|
|
|
|
Each exercises something the first one does not.
|
|
|
|
| # | task | proves |
|
|
|---|---|---|
|
|
| 3.1 | An **identity provider** | a module that is itself a provider — the provides/requires chain, with consumers requiring it |
|
|
| 3.2 | A **forge** | a port claim against the machine's own daemon, and a module wanting both a database and an object store |
|
|
| 3.3 | A **mail system** | several containers as one module, a private network between them, and names that are not one-per-node |
|
|
|
|
**3.3 is the hardest thing in this document** and is deliberately last. If the declaration
|
|
language turns out to be insufficient, it says so here.
|
|
|
|
## Phase 4 — switch the old registry off
|
|
|
|
| # | task | done when |
|
|
|---|---|---|
|
|
| 4.1 | Move the remainder | nothing is assigned in the old system that is not assigned in the new one |
|
|
| 4.2 | Run in parallel, the old one authoritative for nothing | a change to any module goes through the new mesh only |
|
|
| 4.3 | Switch it off | it is stopped, and nothing notices |
|
|
|
|
**4.3 is a day's work and the phases above it are not.** Naming it as a phase is what stops it
|
|
being mistaken for the goal.
|
|
|
|
## Sequencing
|
|
|
|
- **1 before 2.** Attempting a module without the vocabulary it needs produces a workaround, and a
|
|
workaround in a manifest is a design decision taken by whoever was in a hurry.
|
|
- **2 before 3, with the week.** Moving three modules before running one is how three modules
|
|
acquire the same defect.
|
|
- **3.3 last.** It is the only one that may send work back into the declaration language.
|
|
- **4 cannot start early, and there is no partial credit.** A registry still authoritative for one
|
|
module is still running.
|
|
|
|
## How this list is kept true
|
|
|
|
*This section exists because the document it replaces was wrong for weeks and nothing said so.*
|
|
|
|
**A claim here is counted, not reasoned.** The review of 2026-08-31 found a bundle described as
|
|
carrying two images that carries three, a bootstrap described as needing six shapes that uses
|
|
four, and ten documents calling themselves `designed` while naming lab-proven code. Each was
|
|
produced by describing the system from its design instead of reading it.
|
|
|
|
**A phase is done when the lab says so**, and the lab keeps a receipt of when it last ran and
|
|
against which commits. A phase marked done here whose assertions have not run is a claim about the
|
|
past.
|
|
|
|
**What is not proven gets said.** Phase 0 is done and its limitation is written into it. A list
|
|
that records only progress becomes a list nobody believes.
|
|
|
|
## Rules of engagement
|
|
|
|
Unchanged from the previous version: they were about how work is done rather than what the work
|
|
is.
|
|
|
|
### Autonomous by default
|
|
|
|
Read anything, measure anything, query read-only. Create branches, write code and tests, run the
|
|
suites, and write or update documents here.
|
|
|
|
### Always stop and ask
|
|
|
|
- **destroying or overwriting data** — dropping a table, deleting a provision, rotating a live
|
|
credential, removing a module from a node
|
|
- **merging anything** — every merge is a human checkpoint, without exception
|
|
- **anything touching a machine outside the lab**, including a configuration change that restarts
|
|
something people are using
|
|
- **a decision the records do not already answer** — record the question rather than picking and
|
|
moving on
|
|
- **any change to [`00-META`](../../00-META/)** — it is stable by nature
|
|
|
|
### Definition of done for every task
|
|
|
|
1. tests written **and failing first**, then passing
|
|
2. typecheck clean in every package the change touches
|
|
3. the behaviour demonstrated **in the lab, on real machines** — not asserted
|
|
4. documents here updated if the task changed or answered anything recorded
|
|
5. delivered, and the **effect** verified — not that a pipeline was green
|
|
|
|
### Non-negotiables
|
|
|
|
- **Never edit mesh-managed files on disk.** Use the thing that owns the file.
|
|
- **Never write to a production database directly.** Migrations for schema, application code for
|
|
data.
|
|
- **Every schema change ships twice** — consolidated schema *and* an incremental migration.
|
|
- **Expand, then contract.** Add the new shape, migrate, verify, and only then remove the old one.
|
|
- **A green pipeline proves transport, not effect.**
|
|
|
|
## What "done" looks like
|
|
|
|
The old registry is off. Every module runs on the new mesh, declared rather than scripted. A
|
|
machine that fails says what it could not do. And the number of modules grows when the work does,
|
|
not when the platform needs somewhere to put something.
|