diff --git a/03-DESIGN/01-to-be/22-the-work-ahead.md b/03-DESIGN/01-to-be/22-the-work-ahead.md new file mode 100644 index 0000000..777a5b5 --- /dev/null +++ b/03-DESIGN/01-to-be/22-the-work-ahead.md @@ -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. diff --git a/03-DESIGN/01-to-be/README.md b/03-DESIGN/01-to-be/README.md index ebc054a..a12de17 100644 --- a/03-DESIGN/01-to-be/README.md +++ b/03-DESIGN/01-to-be/README.md @@ -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