jschoubben
e20a09ae80
The design, rather than an account of what exists. A module provides names and requires names, and that single relation absorbs three things this effort had listed separately: requiring another module is requiring a concrete name, requiring a resource is requiring an abstract one, and an interface is simply a name with more than one provider. Nothing has to declare that it is an interface — it either has one provider or several. The move that does the most work: a NODE provides names too. Its profile is a set of them — display-server, container-runtime, an architecture — so a module requiring a display server is satisfied by the node exactly as one requiring a database is satisfied by another module. One resolution instead of two, and a graphical application cannot land on a node without a display server for the same reason, through the same code, that it cannot land without its libraries. Which makes the host's capability detection an input to resolution rather than something a person reads. It was built to be read; it turns out to be a provides-list. `excludes` is the one genuinely new relation, because it is not derivable: two modules that both provide message-bus look interchangeable when installing both would break the machine. Constraints are not placement. They say what must be true of a node, never which node — which is the mistake the measurement found in the current catalogue, where a module pins its database to a named node so a second node cannot provide it without editing the consumer. What it deletes, for the design: the module/resource distinction, the interface as a kind of thing, capability checking as a separate mechanism, domain grouping — folders assert relationships where edges record them, so a domain becomes a query over the graph rather than a directory somebody keeps true — and possibly tiers, if a tier is just a computed level. What it does not delete, stated so it is not discovered later: a resolver still has to exist, with version constraints and conflicts, and the design owes an answer on what it delegates rather than reimplements.
5.6 KiB
One kind of edge
A design, not an account of what exists. analysis.md measured the current
catalogue and its value here is two lessons rather than its machinery: a field that means
depends on should say so, and placement does not belong in a manifest.
The idea
A module provides names. A module requires names. That is the only edge.
Everything the effort listed as separate declarations turns out to be one relation with different kinds of name on either end.
postgres provides postgres, database
lavinmq provides lavinmq, message-bus
kitty provides kitty, terminal
anthropic provides anthropic, ai-assistant
meshboard requires database, message-bus
vscode requires terminal, display-server
A name is either concrete — a module's own name, so requires: postgres means that module
and no other — or abstract, so requires: database means whatever provides it. The
difference is not in the schema; it is whether more than one thing offers the name.
That single relation absorbs three things the effort had listed separately:
| Was going to be | Is |
|---|---|
| requires another module | requires a concrete name |
| requires a resource — a database, a bucket | requires an abstract name |
| an interface, with adapters providing it | an abstract name several modules provide |
The interface stops being a kind of module. It is a name with more than one provider, and nothing has to declare that it is one.
The node provides names too
The move that makes capabilities stop being a separate system.
A node's profile is a set of provided names. display-server. container-runtime.
amd64. A module requiring display-server is satisfied by the node, exactly as a module
requiring database is satisfied by another module.
So there is one resolution rather than two: is this name provided by anything available here? A graphical application cannot be installed on a node with no display server for the same reason, and through the same code, that it cannot be installed without its libraries.
And it means the host's capability detection — which already reports what a machine can be asked to do, with a reason for each verdict — is the node's provides-list. It was built to be read by a person; it turns out to be an input to resolution.
What a module declares
name: meshboard
provides: [meshboard]
requires: [database, message-bus, container-runtime]
excludes: []
runs: # what applying it means
- container: ...
constraints: # what must be true of a node that runs it
- architecture: amd64
excludes is the one genuinely new relation: naming something that cannot coexist with
this. It is not derivable from requires and provides, and without it two modules that both
provide message-bus look interchangeable when installing both would break the machine.
constraints are not placement. They say what must be true of a node, never which node.
Which node runs what is an inventory decision, and the measurement found the current catalogue
deciding it in the manifest — a module pinning its database to a named node, so that a second
node cannot provide it without editing the module that consumes it. That is the mistake this
separation exists to avoid.
What it deletes
The question the effort opened with, answered for the design rather than for what exists.
- The distinction between requiring a module and requiring a resource. One relation.
- The interface as a kind of thing. A name with several providers.
- Capability checking as a separate mechanism. The node is a provider.
- Domain grouping (ADR 0017). Folders assert relationships; edges record them. A domain is then a query over the graph — what changes together — rather than a directory somebody has to keep true.
- Tiers as a separate concept, possibly. A tier is a level in the graph, and levels are computed. Whether the coarse boundary is still worth naming is below.
What it does not delete, and should not
A resolver still has to exist, and it will need version constraints, conflict handling and a story for when two modules provide one name and nothing says which to use. That is the long-solved and easily-botched part, and the design should say what it delegates to the platform's package manager rather than reimplementing.
Open
- When two modules provide one name, who chooses? The consumer names
databaseand gets something. Whether the choice is a node setting, a mesh setting, or an explicit pin is the substance of the interface idea, and this proposal does not settle it. - Are tiers a view of the graph, or a boundary that survives it? If tiers are levels, the concept is derived and the word is a convenience. If the tier rule — a tier may depend only on tiers below it — is meant to be enforceable, it is a constraint on the graph rather than a description of it, and it has to be stated as one.
- Does a name need a type?
databaseandterminalare both abstract names, and a consumer of the first needs credentials while a consumer of the second needs a command to run. Whether that difference lives in the name, in a type beside it, or in what the provider hands back is undecided. - What does a node provide that is not a capability? Its architecture is a provided name under this scheme, and so is its operating system. That may be elegant or may be one abstraction too far; nothing here tests it.