The work ahead: four phases, dependency-ordered, each ending at a run

Everything decided this cycle and not yet built. Phase 0 gets the installer green, because nothing else is testable end to end without it. Phase 1 makes the protocol one thing and fixes the Go/TS drift the installer's own provisioning exercises. Phase 2 stands up the private package registry ADR 0014 assumes and publishes the SDK into it. Phase 3 adopts the substrate so one postgres and one lavinmq serve everything, which is the hardest and needs all three above. Order is dependency, not preference. Each phase ends at a run rather than a paragraph, because a phase that ends at a claim is how things went missing this cycle without anything complaining. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
2026-09-15 23:41:42 +02:00
parent 03fc13b84b
commit 2e1ae061b5
2 changed files with 84 additions and 0 deletions
@@ -0,0 +1,83 @@
+---
+layer: to-be
+status: in-progress
+updated: 2026-09-15
+decisions:
+  - 02-DECISIONS/0067-genesis-is-a-pivot.md
+  - 02-DECISIONS/0074-the-wire-is-specified-not-the-types.md
+  - 02-DECISIONS/0075-two-stores-and-which-provides-what.md
+  - 02-DECISIONS/0014-no-npm-workspace.md
+---
+
+# The work ahead
+
+Everything decided this cycle and not yet built, in the order its dependencies allow. Each phase
+ends at something provable on a running mesh, because a phase that ends at a claim is a phase that
+went missing without anything complaining.
+
+## Phase 0 — the installer completes, once
+
+**Why first.** Nothing below is testable end to end without an installer that finishes. It has been
+failing on regressions of mine — a stale carried builder, a diagnostic on the parsed stdout — not
+on the mesh.
+
+- [ ] 0.1 rebuild the builder image, and **verify the change is in it** (`grep`, not trust `make`)
+- [ ] 0.2 re-carry it, run the one-node installer, watch the phase-two base build with its own logs
+- [ ] 0.3 diagnose and fix whatever the base build actually does — the original hang, now visible
+- [ ] 0.4 all 22 checks green, twice, so it is reproducible rather than lucky
+
+**Done when.** A bare machine becomes a working mesh by running the installer, and the run passes
+again.
+
+## Phase 1 — the protocol is one thing, and correct
+
+**Why here.** The Go control plane and the TypeScript SDK disagree about what a grant carries
+(`consumer` is the module in one, the node in the other). That is exercised by the installer's own
+provisioning — the catalogue's database — so it belongs before more is built on it.
+
+- [ ] 1.1 extract the wire contracts to one specification the two implementations both conform to
+- [ ] 1.2 make Go and TypeScript agree — one meaning for `consumer`, the envelope's six headers
+      emitted by both
+- [ ] 1.3 an executable conformance suite, per capability, both existing SDKs made to pass it
+- [ ] 1.4 the `x-schema` header written, so a body's shape can version (ADR 0074)
+
+**Done when.** A fixture emitted by one implementation is read identically by the other, checked in
+both test suites.
+
+## Phase 2 — the private package registry, and the SDK in it
+
+**Why here.** ADR 0014 says a module consumes its dependencies, the SDK included, from the private
+registry. Nothing installs one, so the SDK comes from a git URL (issue 053). Needs the installer
+(Phase 0) and gitea.
+
+- [ ] 2.1 gitea provides `package-registry` in full — the endpoints, an account the builder may
+      publish with
+- [ ] 2.2 the builder publishes the SDK there on build, by version
+- [ ] 2.3 modules consume it by version; the git URL and the sibling-path lock are gone
+- [ ] 2.4 a second language's SDK published the same way, proving the path is not TypeScript-only
+
+**Done when.** A module builds against the SDK resolved from the mesh's own registry, and issue 053
+closes.
+
+## Phase 3 — nothing is special after installation
+
+**Why last.** The hardest and riskiest, and it needs everything above: an installer that completes,
+a protocol that agrees, a registry to publish to. Issue 051.
+
+- [ ] 3.1 the store is adopted — raised at genesis, then held as the `postgres` module; one server,
+      the control plane's records and every module's database in it
+- [ ] 3.2 the broker is adopted — one `lavinmq`, the `/` vhost for the mesh bus, a vhost per
+      consumer that requires `amqp`; the second server gone
+- [ ] 3.3 an upgrade of each, proven: a store the control plane reads from, a broker over the
+      broker, each with a stated window
+- [ ] 3.4 `status` can say the substrate is behind its source, which today it cannot form
+
+**Done when.** A mesh built from bare metal runs one postgres and one lavinmq, and can upgrade
+either — so the twelve-module floor has no specialty left in it.
+
+## The through-line
+
+Each phase leaves the mesh more able to describe and rebuild itself, and each ends at a run rather
+than a paragraph. The order is dependency, not preference: the installer carries everything, the
+protocol is what everything speaks, the registry is what everything is built from, and adoption is
+what makes the last two things ordinary.
@@ -31,6 +31,7 @@ document is written and this one's status becomes `implemented`.
 | [`19-the-module-protocol.md`](19-the-module-protocol.md) | What a module's code and the mesh say to each other; an SDK is an implementation of it | [ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md), [ADR 0042](../../02-DECISIONS/0042-the-shape-of-an-event-on-the-wire.md), [ADR 0043](../../02-DECISIONS/0043-a-module-broker-account-is-scoped-by-emits-and-consumes.md) |
 | [`20-writing-a-module.md`](20-writing-a-module.md) | A worked guide: one module, four capabilities, four languages, and the packages it publishes | [ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md), [ADR 0040](../../02-DECISIONS/0040-what-a-module-is.md), [ADR 0039](../../02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md) |
 | [`21-the-installation-in-full.md`](21-the-installation-in-full.md) | Every step from a bare machine to a mesh that maintains itself, and what is not yet true | [ADR 0067](../../02-DECISIONS/0067-genesis-is-a-pivot.md), [ADR 0073](../../02-DECISIONS/0073-the-installer-carries-a-builder.md), [ADR 0014](../../02-DECISIONS/0014-no-npm-workspace.md) |
+| [`22-the-work-ahead.md`](22-the-work-ahead.md) | Everything decided and not yet built, in dependency order, each phase ending at a run | [ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md), [ADR 0075](../../02-DECISIONS/0075-two-stores-and-which-provides-what.md), [ADR 0014](../../02-DECISIONS/0014-no-npm-workspace.md) |

 ## Not yet written