novox/hq

Files

T

jochen dbe100ca96 ADR 0110 and 0111: a seat is a module assignment from a closed set, and a build source may live on the git seat

Seats have been doing two jobs and neither is written down. The mechanism ADR 0009 introduced is
enforced — a second holder is refused — but any well-formed name becomes a seat by being claimed,
and nothing can say which seats a mesh has or who holds them: holdings are assembled while planning
and discarded. The enumeration done while preparing this missed the control plane's own manifest,
because core modules' manifests live in its repository rather than the catalogue.

0110 closes the set. Each seat has a name, a scope, what occupying it delivers, and the record that
made it one; a claim outside the set is refused. A seat is held by a module assignment, and what the
mesh knows about the holder is what it knows about that assignment — nothing is stored beside it. A
seat may deliver a provision, and then its holder answers for it among several providers: pin, then
the holder, then the only provider, then refused. That keeps 0009's "refused, never guessed": the
seat is the choice made once, mesh-wide, instead of a pin per consumer node. The first set is the
eleven seats already claimed plus 0109's npm-package-registry, so nothing in use is refused.

Two concepts — seats for exclusion, a new word for consumable singulars — was rejected: both mean
"this mesh's one X", and the overview a person wants is one list.

0111 gives the mesh a git seat and makes a build source one of two explicit forms: a repository on
the seat's holder, recorded by its path and cloned from wherever the holder runs at build time; or
an external URL, recorded and cloned exactly as given. Recognising self-hosted sources by matching
URLs against the forge's address was rejected — it fails in the one case it exists for, after the
forge moves. Credentials for private repositories are left undecided and said so.

Design: new to-be 26 (the seats); 23 gains the seat step in resolution; 18's source entry names
the two forms; the glossary's seat and provision entries say where they meet. 0109 is carried from
its own branch so every link here resolves.

2026-09-25 20:33:14 +02:00

5.5 KiB

Raw Blame History

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
building it	accepted	2026-09-25	jochen	false	0069-a-module-is-a-repository-and-a-path.md

111. A build source is on the mesh's git seat, or it is an external repository

Context

ADR 0069 made a module a repository, a path and a ref, and the control plane records all three against the module so it can rebuild it and say when its source has moved ahead. The repository is recorded exactly as a person typed it. build <repository> hands the string to a build machine, which runs git clone on it, and the same string becomes the module's recorded source.

So a self-hosted forge's address is written into every module built from it. The mesh runs its own forge, and most of what it builds lives there. Every one of those modules carries the forge's scheme, host and port in its recorded source. Move the forge to another machine, or change the port it is published on, and every recorded source is stale at once. Nothing notices until a rebuild fails to clone.

And nothing names the mesh's git at all. gitea serves git over HTTP and over SSH, and the mesh's vocabulary contains neither. No provision, no serves, no seat, as the forge survey (research 013) found. The only trace is a label on its public route, which the mesh is explicitly not meant to interpret.

External repositories are ordinary, and must stay so. An application the mesh hosts may live on a public forge. Building it from its URL works today and must keep working unchanged.

Considered Options

1. Keep recording literal URLs. Rejected. It is the problem: the forge's address copied into every module built from it.

2. Recognise a self-hosted source by matching its URL against the forge's current address. Rejected. It infers the kind of source from the shape of a string, and the inference fails in the one case it exists for: after the forge moves, old URLs no longer match anything.

3. Two explicit forms: a repository on the holder of the git seat, or an external URL. Chosen.

Decision

The mesh has a git seat. It is mesh-scoped and delivers the git provision, per ADR 0110. Its holder provides git, serving how a repository on it is cloned: the scheme and the port. gitea claims it.

A source is on the git seat, or it is external, and the mesh records which.

build --self <owner>/<repository> builds from a repository on the seat's holder. The recorded source is the repository's path on that holder, and the seat it is on. It never contains an address. At the moment of building, the control plane composes the clone URL from where the holder runs and what it serves for git, so a moved forge changes nothing recorded.
build <url> is unchanged: an external repository, recorded and cloned exactly as given. GitHub and GitLab are the ordinary cases.

An unheld seat refuses self-hosted builds and nothing else. With nobody holding git, build --self is refused, naming the seat and saying what would hold it. External builds are unaffected. A mesh without a forge of its own builds from external repositories only, and says so rather than failing to clone.

The build machine is not told the difference. It receives a URL either way. Composing the URL is the control plane's job, because only the control plane knows where the seat's holder runs.

Consequences

The control plane's inventory gains a column saying which seat a source is on. It is empty for every module recorded before this, which is correct: they were all recorded as literal URLs.
build, build --behind and build --dry-run resolve a seat source before asking a builder. The recorded source keeps the seat form; the build log keeps the URL that was actually cloned, because that is what happened.
gitea claims git and provides it, serving HTTP clone on its web port.
Not decided: credentials for private repositories. The mesh's own repositories are public, and clone without one. A private repository still works only if the build machine's own git configuration authenticates, exactly as before. Delivering a clone credential through the git provision's grant is the obvious next step, and it is its own decision.
Not changed: modules already recorded from the forge keep their literal URLs until they are rebuilt with --self. Rewriting them in place would be the URL-matching this record rejects.

How it is checked

Rule	Checked by
A seat source records no address	A control-plane test resolves a seat source and asserts the recorded repository is the path alone.
The URL comes from the holder	A test composes the clone URL from a holder's node address and served `git` scheme and port, and a second where the port was moved on the node.
An unheld seat refuses self-hosted builds only	A test with no holder: `--self` is refused naming the seat; an external URL passes through unchanged.

References

ADR 0069: a module is a repository, a path and a ref
ADR 0110: seats, and a seat delivering a provision
Research 013: git is served and declared nowhere
mesh-controller cmd/mesh-controller/build.go, internal/builder/builder.go

5.5 KiB Raw Blame History