131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
# The survey — seats, the forge, the registries, as the code has them
|
|
|
|
*2026-09-23. Read from the code and the records, not from memory. Every claim here was checked
|
|
against a file.*
|
|
|
|
## What a seat is
|
|
|
|
The glossary calls a seat *a named position at a scope with a capacity*, and a claim *a module
|
|
taking a spot on it*. **Capacity does not exist in the code.** There is no capacity field and no
|
|
bench; every claim is exclusive. The "shared seat" of the design is the word `provides` wearing
|
|
that name.
|
|
|
|
Claiming does two things and no others:
|
|
|
|
- **It refuses a second claimant when a node's modules are resolved** — within one node at any
|
|
scope, and against every other node for mesh and site scope.
|
|
- **It answers one question, once:** the controller finds where the broker is by looking for the
|
|
module claiming the broker's seat.
|
|
|
|
No host is ever told about a seat. It is a resolution-time predicate.
|
|
|
|
Two mechanical asymmetries matter. A mesh-scoped seat's exclusivity is defended only by nodes
|
|
that *resolve*: a node whose modules fail to resolve contributes nothing, so a broken node does
|
|
not hold its seat against a second claimant. And a site-scoped seat does nothing at all when
|
|
either node has no site.
|
|
|
|
## The seats that exist
|
|
|
|
Twelve claims, twelve names. Four are mesh-scoped: the controller, the store, the broker, the
|
|
catalogue. All four are things the mesh runs **for its own working**, and three of them are raised
|
|
by genesis and adopted in place — which is the argument of the record that named them.
|
|
|
|
The node-scoped ones split in two: a **role on this machine** (the build machine, the packet
|
|
filter, the intrusion prevention, the private network) and **a scarce machine resource** (the
|
|
resolver's configuration file, the DNS port). The second kind is a claim for the reason a port is:
|
|
there is one of it on the machine.
|
|
|
|
Two oddities worth stating:
|
|
|
|
- The image store claims its seat at **node** scope while providing its service at **mesh** scope.
|
|
The record that discussed this left open whether it should hold that claim at all.
|
|
- **Nothing claims the two public ports.** The proxy binds them and claims nothing, which is the
|
|
hole the route handover fell into.
|
|
|
|
## The forge, and what it serves
|
|
|
|
The forge serves three things: git over https, git over ssh on its own port, and an npm registry.
|
|
**Only the npm half is in the mesh's vocabulary** — the forge provides `package-registry` and says
|
|
where it answers. Git is served and declared nowhere: no provision, no `serves`, nothing that can
|
|
require it. The only trace is the public label in its route contribution, which the mesh is
|
|
explicitly not meant to interpret.
|
|
|
|
The image store is a separate module and a separate provision, plain HTTP, trusted because it is
|
|
reachable only over the private network.
|
|
|
|
A second module also provides `package-registry`. Two providers of one provision is not a refusal
|
|
but an ambiguity, and the mesh already has the command that settles it: pin one.
|
|
|
|
## Where the builder's three addresses come from
|
|
|
|
| What it needs | How it finds it |
|
|
|---|---|
|
|
| the broker | a sealed secret of its own |
|
|
| the image store | **a real provision binding**, resolved by the mesh |
|
|
| the package registry | **a file in its own manifest**, naming the module, `127.0.0.1` and the port |
|
|
| the source repository | nothing at all — a person types a clone URL per build |
|
|
|
|
The installer says this plainly in a comment: *the one binding nothing resolves: the builder dials
|
|
the forge by a number it carries.* Genesis can override the port of that literal, and nothing
|
|
else: not the forge's identity, not its address.
|
|
|
|
`package-registry` therefore has **zero consumers**. The builder does not require it. The
|
|
provision is fully built — two providers, grants, a served description including the registry's
|
|
path — and nothing asks for it.
|
|
|
|
## How a module's source is found
|
|
|
|
It is not found; it is supplied. The clone URL arrives as an argument, travels to the build machine
|
|
and reaches `git clone` unexamined. No credential is attached, so a private forge works only if the
|
|
build machine's own git configuration already authenticates. Each module remembers the URL it was
|
|
built from, so there are as many forge addresses as modules, each frozen at whatever was typed.
|
|
|
|
At genesis there are four independent source URLs, one per flag, unrelated to each other.
|
|
|
|
If the forge moves or is renamed: every stored URL goes stale independently, each failing at its
|
|
own clone, and there is no command to re-point them. Genesis keeps working, because it takes URLs
|
|
as flags — which is the existing record's position: the forge is reached *by a name outside the
|
|
mesh*, and failover is repointing that name.
|
|
|
|
## What genesis's forge is
|
|
|
|
A bare container run before any module exists, because the toolchain resolves the mesh's own
|
|
packages by version from an npm registry. It holds **no seat, no manifest, no provision**. The
|
|
mesh is told one thing about it — a port — and only when that port is not the default. **On an
|
|
ordinary genesis the mesh never learns the bootstrap forge exists.**
|
|
|
|
Its successor module differs from it in five ways: container name, network, data directory, the
|
|
address it is told to call itself, and — contradicting a comment that says they are pinned
|
|
identically — **the image digest**. So assigning the module raises a second forge beside the first.
|
|
|
|
A seat cannot fix that. A seat is checked between manifests; the bootstrap forge has no manifest,
|
|
so no seat can see it. The check that is actually wanted — same name, same data, same network — is
|
|
between an installer constant and a manifest.
|
|
|
|
## Would a git seat be coherent?
|
|
|
|
In form, yes: add the claim and a second forge is refused. In effect it buys one refusal nobody
|
|
has hit, and forbids an arrangement the mesh should allow — a second forge for something other
|
|
than the mesh's own source.
|
|
|
|
Measured against the four mesh seats, it does not fit: those are singular servers the mesh runs
|
|
for itself, and a forge is an application. Nothing would *use* it, because the only seat consumer
|
|
answers "where is the broker", and a forge address is not one fact: a module's source is a
|
|
repository **and a path and a ref**.
|
|
|
|
## What the code already supports and nobody uses
|
|
|
|
- **`package-registry` with no consumers.** The builder's literal file is a hand-rolled copy of
|
|
the binding the mesh would have written for it.
|
|
- **Pinning a provider** already expresses *this* forge, of several, without forbidding the second.
|
|
- **Grants** on the forge are the credential mechanism that would hand the builder an account.
|
|
Today the installer creates that account directly, because nothing requires the provision and so
|
|
the grant has no consumer to write for.
|
|
|
|
## The reading
|
|
|
|
The question *should there be a git seat* is the wrong shape for the problem under it. Every
|
|
symptom — the literal address, the port that would not follow a node, the takeover that is not a
|
|
takeover — is about **an address and a credential nobody resolves**. A seat resolves neither. The
|
|
provision mechanism does, and is already built.
|