MV1: move contracts and sdk under modules/, importers follow

The delivery repository's contracts and SDK live under modules/ as
mesh-delivery-contracts and mesh-delivery-sdk, their Go module paths
renamed to match the folders (the TypeScript names already did), and
every importer in mesh-delivery, mesh-catalog, mesh-host, mesh-tools
and mesh-sdk follows in the same group: a design as it should be, one
path per module, checked by the group's check building every importer.

Builds: design 47 G §427, §88

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-12 05:09:56 +01:00
parent 512bb3c75c
commit 71a35a6376
769 changed files with 1277 additions and 1277 deletions
-26
View File
@@ -1,26 +0,0 @@
package graph
import (
"maps"
"slices"
"git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
)
// NodeOf is the node of the module graph a catalog graph entry carries, as the indexer took it in (design 47, *Two
// graphs*): the catalog half's holder reads its graph back from its newest trunk revision, and every part that reads the
// catalog half reads the module graph from its entries, never from the holder's state.
func NodeOf(e meshcatalog.CatalogEntry) Node {
n := Node{V: Version, FP: e.Fp, None: e.None, Repository: e.Repository, Path: e.Path, Bases: e.Bases,
Provides: e.Provides, Requires: e.Requires, Awaits: e.Awaits, Invokes: e.Invokes, Serves: e.Serves, LeftOut: e.LeftOut}
if len(e.Packages) > 0 {
n.Packages = slices.Sorted(maps.Keys(e.Packages))
}
for language, t := range e.Toolchains {
if n.Toolchains == nil {
n.Toolchains = map[string]Toolchain{}
}
n.Toolchains[language] = Toolchain{Module: t.Module, Version: t.Version, Recipe: t.Recipe}
}
return n
}
-621
View File
@@ -1,621 +0,0 @@
package graph
import (
"encoding/json"
"errors"
"fmt"
"maps"
"reflect"
"slices"
"strings"
"git.novox.be/novox/mesh-delivery/contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/sdk/trunk"
"git.novox.be/novox/mesh-sdk/go/catalogue"
nodeengine "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
)
// Version is the version of a node's value this package writes and the only one it reads.
const Version = 1
// ErrUnknownVersion is what Decode returns for a value whose version is missing or not Version.
var ErrUnknownVersion = errors.New("graph: unknown value version")
func decode(data []byte, into *Node) error {
var probe struct {
V *int `json:"v"`
}
if err := json.Unmarshal(data, &probe); err != nil {
return fmt.Errorf("graph: value does not fit its shape: %w", err)
}
if probe.V == nil || *probe.V != Version {
return fmt.Errorf("%w: this reader reads %d", ErrUnknownVersion, Version)
}
if err := json.Unmarshal(data, into); err != nil {
return fmt.Errorf("graph: value does not fit its shape: %w", err)
}
return nil
}
// checkName refuses a module name a key cannot hold (meshcatalogclient.ModulesKey's rule).
func checkName(kind, name string) error {
if _, err := meshcatalogclient.ModulesKey(name); err != nil {
return fmt.Errorf("graph: the %s name %q: %w", kind, name, err)
}
return nil
}
// checkRepository refuses a repository that is not <owner>/<name>.
func checkRepository(repository string) error {
owner, name, ok := strings.Cut(repository, "/")
if !ok || owner == "" || name == "" || strings.Contains(name, "/") {
return fmt.Errorf("graph: the repository %q is not <owner>/<name>", repository)
}
return nil
}
// The module graph (novox/hq ADR 0603 §2, ADR 0604 §1): the indexer keeps, as its state `graph`, one key per module it
// holds the inputs of, written at every recompute and deleted with the module. A key holds the module's build edges
// (its bases, the mesh packages its fingerprint takes, and per language the build module, toolchain version and recipe
// version its fingerprint names, ADR 0530 §1) and its provision edges (what its manifest provides, requires, and of what
// it requires what a want of it waits for). Nothing stores an order: a reader works it out from the edges (ADR 0603
// §1, §6). The indexer writes it and works the edges out (EdgesOf), the delivery view, the checker and the indexer's
// answers of the seat mesh-catalog read it; all three are in this repository, which uses this package by path (the
// operator, 2026-11-03: no graph-related code in mesh-sdk, only contracts). It names no module.
const (
// State is the name of the indexer's state of the module graph, as its manifest declares it: one key per module
// (Key). Its bucket is the holder's name and the state's, which the indexer and each reader name from its own
// manifest, never this package (ADR 0625 §4).
State = "graph"
// History is the revisions the graph state keeps per key (ADR 0603 §2).
History = 5
)
// Key is the key, in Bucket, of a module: `<module>`, as ModulesKey.
func Key(module string) (string, error) { return meshcatalogclient.ModulesKey(module) }
// ParseKey is the inverse of Key.
func ParseKey(key string) (string, error) {
module, err := Key(key)
if err != nil {
return "", fmt.Errorf("graph: %q is not a graph key: %w", key, err)
}
return module, nil
}
// Node is the value of a graph key: one module's edges as its last recompute computed them. FP is its new-form
// fingerprint then, or None why it has none (exactly one is set); Repository and Path say where it is (as Module), so a
// package edge is resolved to the module that publishes it (GraphPublisher). Bases are the modules it is built on;
// Packages the mesh packages (Go module paths) its fingerprint took (Module.Packages); Toolchains, by language, the
// build module and the toolchain it was computed with. Provides are the provisions its manifest offers (its own name is
// provided too and is not listed), Requires what it requires and does not require optionally, and Awaits those of
// Requires a want of it waits for (catalogue.Awaited, ADR 0570 §4): the provision edges that order a source revision.
// A bus-state entry of its manifest is a requirement of the provision BusState (ADR 0614 §5). Invokes are the seat verbs
// (`seat:<seat>.<verb>`) and module tools (`<module>.<tool>`) its manifest and its own bus accounts invoke, Serves those
// its claims serve and its own tools answer, in the same two forms (ADR 0614 §2), and LeftOut those of Invokes whose
// verb edge lies on a cycle and is left out of the graph, so no want waits on it (§3; LeaveOut works them out).
// Every list is sorted and each entry once; an encode sorts them.
type Node struct {
V int `json:"v"`
FP string `json:"fp,omitempty"`
None string `json:"none,omitempty"`
Repository string `json:"repository"`
Path string `json:"path,omitempty"`
Bases []string `json:"bases,omitempty"`
Packages []string `json:"packages,omitempty"`
Toolchains map[string]Toolchain `json:"toolchains,omitempty"`
Provides []string `json:"provides,omitempty"`
Requires []string `json:"requires,omitempty"`
Awaits []string `json:"awaits,omitempty"`
Invokes []string `json:"invokes,omitempty"`
Serves []string `json:"serves,omitempty"`
LeftOut []string `json:"left-out,omitempty"`
}
// BusState is the provision a bus-state entry of a manifest requires (ADR 0614 §5): the bus module's build that offers it
// goes before the module that asks bus state.
const BusState = "bus-state"
// Toolchain is a build edge of one language: the build module that builds it (Module) and the toolchain version
// and recipe version its fingerprint names.
type Toolchain struct {
Module string `json:"module"`
Version string `json:"version"`
Recipe string `json:"recipe"`
}
func (g Node) check() error {
switch {
case (g.FP == "") == (g.None == ""):
return fmt.Errorf("graph: a graph node has either a fingerprint or a reason for none, not both or neither")
case g.FP != "" && !strings.HasPrefix(g.FP, meshcatalogclient.SourcePrefix2):
return fmt.Errorf("graph: the graph node's fingerprint %q does not start with %s", g.FP, meshcatalogclient.SourcePrefix2)
}
if err := checkRepository(g.Repository); err != nil {
return err
}
for _, b := range g.Bases {
if err := checkName("base", b); err != nil {
return err
}
}
for _, p := range g.Packages {
if _, _, ok := trunk.PackageRepository(p); !ok {
return fmt.Errorf("graph: the graph node's package %q is no mesh package's path", p)
}
}
for language, t := range g.Toolchains {
if err := checkName("build module", t.Module); err != nil {
return fmt.Errorf("graph: the graph node's toolchain of %q: %w", language, err)
}
if language == "" || t.Version == "" || t.Recipe == "" {
return fmt.Errorf("graph: the graph node's toolchain of %q needs its language, version and recipe version", language)
}
}
for _, list := range [][]string{g.Provides, g.Requires, g.Awaits} {
if slices.Contains(list, "") {
return fmt.Errorf("graph: a graph node names an empty provision")
}
}
for _, a := range g.Awaits {
if !slices.Contains(g.Requires, a) {
return fmt.Errorf("graph: the graph node awaits %q, which it does not require", a)
}
}
for _, list := range [][]string{g.Invokes, g.Serves} {
for _, v := range list {
if !isVerb(v) {
return fmt.Errorf("graph: the graph node names %q, which is neither seat:<seat>.<verb> nor <module>.<tool>", v)
}
}
}
for _, l := range g.LeftOut {
if !slices.Contains(g.Invokes, l) {
return fmt.Errorf("graph: the graph node leaves out %q, which it does not invoke", l)
}
}
return nil
}
// isVerb says whether v is a seat verb `seat:<seat>.<verb>` or a module tool `<module>.<tool>`.
func isVerb(v string) bool {
if _, _, ok := catalogue.SeatInvoke(v); ok {
return true
}
module, tool, ok := strings.Cut(v, ".")
return ok && module != "" && tool != "" && !strings.HasPrefix(v, "seat:")
}
func sortedOnce(in []string) []string {
if len(in) == 0 {
return nil
}
out := slices.Clone(in)
slices.Sort(out)
return slices.Compact(out)
}
func (g Node) normal() Node {
g.Bases, g.Packages = sortedOnce(g.Bases), sortedOnce(g.Packages)
g.Provides, g.Requires, g.Awaits = sortedOnce(g.Provides), sortedOnce(g.Requires), sortedOnce(g.Awaits)
g.Invokes, g.Serves, g.LeftOut = sortedOnce(g.Invokes), sortedOnce(g.Serves), sortedOnce(g.LeftOut)
if len(g.Toolchains) == 0 {
g.Toolchains = nil
}
return g
}
// Encode is g as JSON at Version, its lists sorted; it refuses what Node's contract does not hold.
func Encode(g Node) ([]byte, error) {
g = g.normal()
if err := g.check(); err != nil {
return nil, err
}
g.V = Version
return json.Marshal(g)
}
// Decode reads a graph node; it refuses an unknown version (ErrUnknownVersion) and what Encode refuses.
func Decode(data []byte) (Node, error) {
var g Node
if err := decode(data, &g); err != nil {
return Node{}, err
}
if err := g.check(); err != nil {
return Node{}, err
}
return g.normal(), nil
}
// Same says whether two graph nodes are the same value once sorted, so a writer writes only when they differ.
func Same(a, b Node) bool {
a, b = a.normal(), b.normal()
a.V, b.V = 0, 0
return reflect.DeepEqual(a, b)
}
// Graph is the module graph as a reader holds it: every graph node, by module.
type Graph map[string]Node
// Providers are the modules that provide provision: each whose Provides names it, and the module of that name (a module
// provides its own name), sorted.
func (g Graph) Providers(provision string) []string {
var out []string
for name, n := range g {
if name == provision || slices.Contains(n.Provides, provision) {
out = append(out, name)
}
}
slices.Sort(out)
return out
}
// Requirers are the modules that require provision, not optionally, sorted.
func (g Graph) Requirers(provision string) []string {
var out []string
for name, n := range g {
if slices.Contains(n.Requires, provision) {
out = append(out, name)
}
}
slices.Sort(out)
return out
}
// Publisher is the module of the graph whose repository and directory publish the mesh package pkg (PackageRepository):
// the module whose directory is the package's directory or the nearest one above it (the longest match, a package
// published from inside a module's directory belonging to that module), or "" when the graph holds none.
func (g Graph) Publisher(pkg string) string {
repository, dir, ok := trunk.PackageRepository(pkg)
if !ok {
return ""
}
if dir == "" {
dir = meshcatalogclient.RootPath
}
best, bestLen := "", -1
for _, name := range slices.Sorted(maps.Keys(g)) {
n := g[name]
if n.Repository != repository {
continue
}
switch {
case n.Path == dir:
return name
case n.Path == meshcatalogclient.RootPath:
if bestLen < 0 {
best, bestLen = name, 0
}
case strings.HasPrefix(dir, n.Path+"/") && len(n.Path) > bestLen:
best, bestLen = name, len(n.Path)
}
}
return best
}
// buildEdges are the modules n's build edges reach: its bases, the publisher of each of its packages, and the build
// module of each language.
func (g Graph) buildEdges(n Node) []string {
out := slices.Clone(n.Bases)
for _, p := range n.Packages {
if m := g.Publisher(p); m != "" {
out = append(out, m)
}
}
for _, t := range n.Toolchains {
out = append(out, t.Module)
}
return sortedOnce(out)
}
// Dependents are the modules whose build edges reach module, directly or through other modules' (a base of a base, a
// module built by a build module that stands on module), sorted and without module itself (ADR 0604 §1): what a
// change of module builds again.
func (g Graph) Dependents(module string) []string {
reverse := map[string][]string{}
for _, name := range slices.Sorted(maps.Keys(g)) {
for _, to := range g.buildEdges(g[name]) {
reverse[to] = append(reverse[to], name)
}
}
seen := map[string]bool{module: true}
queue := []string{module}
var out []string
for len(queue) > 0 {
at := queue[0]
queue = queue[1:]
for _, from := range reverse[at] {
if !seen[from] {
seen[from] = true
out = append(out, from)
queue = append(queue, from)
}
}
}
slices.Sort(out)
return out
}
// Servers are the modules whose Serves names invoke (a seat verb or a module tool), sorted.
func (g Graph) Servers(invoke string) []string {
var out []string
for name, n := range g {
if slices.Contains(n.Serves, invoke) {
out = append(out, name)
}
}
slices.Sort(out)
return out
}
// waits are the modules name waits for, sorted: its bases, for each provision it awaits every other module that provides
// it (ADR 0603 §1), and with verbs for each invoke the module serving it (ADR 0614 §2), those it leaves out (§3) left
// out unless all is set.
func (g Graph) waits(name string, verbs, all bool) []string {
n := g[name]
out := slices.Clone(n.Bases)
for _, a := range n.Awaits {
for _, p := range g.Providers(a) {
if p != name {
out = append(out, p)
}
}
}
if verbs {
for _, v := range n.Invokes {
if !all && slices.Contains(n.LeftOut, v) {
continue
}
for _, s := range g.Servers(v) {
if s != name || all {
out = append(out, s)
}
}
}
}
return sortedOnce(out)
}
// Before are the modules name waits for, by the graph's ordering edges, sorted: its bases, for each provision it awaits
// (bus state among them, ADR 0614 §5) every other module that provides it (ADR 0603 §1), and for each verb it invokes
// and the graph keeps, every other module that serves it (ADR 0614 §2, §3). A toolchain or package edge orders nothing:
// it is a trigger, never a wait (ADR 0614 §6).
func (g Graph) Before(name string) []string { return g.waits(name, true, false) }
// LeaveOut sets each node's LeftOut (ADR 0614 §3): every invoke whose verb edge lies on a cycle of the edges a part waits
// on (bases, awaited provisions, every verb edge), whichever module the edge starts from, a module invoking what it
// serves itself included. An edge lies on a cycle when the module it reaches reaches the module it starts from: both are
// in one strongly connected part of the graph. What is left of the graph then has no cycle through a verb edge, so the
// check's refusal (Cycle) never meets one.
func (g Graph) LeaveOut() {
part := g.parts(func(name string) []string { return g.waits(name, true, true) })
for _, name := range slices.Sorted(maps.Keys(g)) {
n := g[name]
n.LeftOut = nil
for _, v := range n.Invokes {
for _, s := range g.Servers(v) {
if part[s] == part[name] {
n.LeftOut = append(n.LeftOut, v)
break
}
}
}
g[name] = n.normal()
}
}
// parts numbers each module by the strongly connected part of edges it is in (Tarjan's), so two modules have one number
// when each reaches the other.
func (g Graph) parts(edges func(string) []string) map[string]int {
index, low, part := map[string]int{}, map[string]int{}, map[string]int{}
onStack := map[string]bool{}
var stack []string
next, parts := 0, 0
var visit func(string)
visit = func(name string) {
index[name], low[name] = next, next
next++
stack = append(stack, name)
onStack[name] = true
for _, to := range edges(name) {
if _, ours := g[to]; !ours {
continue
}
if _, seen := index[to]; !seen {
visit(to)
low[name] = min(low[name], low[to])
} else if onStack[to] {
low[name] = min(low[name], index[to])
}
}
if low[name] == index[name] {
for {
top := stack[len(stack)-1]
stack = stack[:len(stack)-1]
onStack[top] = false
part[top] = parts
if top == name {
break
}
}
parts++
}
}
for _, name := range slices.Sorted(maps.Keys(g)) {
if _, seen := index[name]; !seen {
visit(name)
}
}
return part
}
// Cycle is the first cycle of the graph's ordering edges (Before), as the modules it passes through with the first named
// again at its end (a -> b -> a), or nil for none (ADR 0603 §2: the check refuses it and names it). The ordering edges
// are what a part waits on, provisions, bus state and the verb edges the graph keeps (ADR 0614 §6), and bases, since a
// module built on another's artifact can never build in a cycle of bases: modules ordered on each other would each wait
// for the other for good. A verb edge the graph leaves out (LeaveOut) is none, and neither is a toolchain edge (ADR 0603
// §3: nothing waits on a build module) or a package edge (ADR 0614 §6: a trigger). The modules are visited in sorted
// order, so the same graph names the same cycle.
func (g Graph) Cycle() []string {
edges := g.Before
const (
unseen = iota
onPath
done
)
state := map[string]int{}
var path []string
var visit func(string) []string
visit = func(name string) []string {
state[name] = onPath
path = append(path, name)
for _, to := range edges(name) {
if _, ours := g[to]; !ours {
continue
}
switch state[to] {
case onPath:
i := slices.Index(path, to)
return append(slices.Clone(path[i:]), to)
case unseen:
if c := visit(to); c != nil {
return c
}
}
}
path = path[:len(path)-1]
state[name] = done
return nil
}
for _, name := range slices.Sorted(maps.Keys(g)) {
if state[name] == unseen {
if c := visit(name); c != nil {
return c
}
}
}
return nil
}
// EdgesOf is the graph node of manifest's own edges: its bases (each module its build stands on), what it provides,
// what it requires and does not require optionally, a bus-state entry as a requirement of BusState (ADR 0614 §5), and of
// those what a want of it waits for (catalogue.Awaited, as the assigner judges it; BusState whenever a provider offers
// it), providers answering the manifests that provide a provision; and the verbs and tools it invokes and serves
// (InvokesOf, ServesOf). The fingerprint, place, packages, toolchains and the verb edges left out (LeaveOut, over the
// whole graph) are the indexer's to add; this is the part a reader of manifests alone (the checker) works out the same way.
func EdgesOf(manifest catalogue.Manifest, providers func(provision string) []catalogue.Manifest) Node {
var n Node
if manifest.Build != nil {
for _, on := range manifest.Build.On {
if on.Module != "" {
n.Bases = append(n.Bases, on.Module)
}
}
}
for _, o := range manifest.Provides {
n.Provides = append(n.Provides, o.Name)
}
for _, r := range manifest.Requires {
if !manifest.OptionalRequires[r] {
n.Requires = append(n.Requires, r)
}
}
n.Awaits = catalogue.Awaited(manifest, providers)
if len(manifest.BusState) > 0 {
n.Requires = append(n.Requires, BusState)
if len(providers(BusState)) > 0 {
n.Awaits = append(n.Awaits, BusState)
}
}
n.Invokes, n.Serves = InvokesOf(manifest), ServesOf(manifest)
return n.normal()
}
// InvokesOf are the seat verbs and module tools manifest invokes, its own and its processes' and tools bundles' bus
// accounts' (catalogue.Manifest.BusAccounts), sorted, each once; `*`, every tool, names no edge and is left out.
func InvokesOf(manifest catalogue.Manifest) []string {
all := slices.Clone(manifest.Invokes)
for _, a := range manifest.BusAccounts() {
all = append(all, a.Bus.Invokes...)
}
var out []string
for _, v := range all {
if isVerb(v) {
out = append(out, v)
}
}
return sortedOnce(out)
}
// ServesOf are the seat verbs manifest's claims serve (`seat:<seat>.<verb>`, catalogue.Claim.ServesFor) and its own
// tools (`<module>.<tool>`), sorted, each once.
func ServesOf(manifest catalogue.Manifest) []string {
var out []string
for _, c := range manifest.Claims {
for _, v := range c.ServesFor(manifest) {
out = append(out, "seat:"+c.Name+"."+v)
}
}
for _, t := range manifest.Tools {
out = append(out, manifest.Module+"."+t)
}
var verbs []string
for _, v := range out {
if isVerb(v) {
verbs = append(verbs, v)
}
}
return sortedOnce(verbs)
}
// OfManifests is the graph of these manifests' own edges (EdgesOf), by module, each provision's providers being
// the manifests among them that offer it, with the verb edges on a cycle left out (LeaveOut): what the check works out
// for a change to find a cycle (ADR 0603 §2, ADR 0614 §3).
func OfManifests(manifests map[string]catalogue.Manifest) Graph {
providers := func(provision string) []catalogue.Manifest {
var out []catalogue.Manifest
for _, name := range slices.Sorted(maps.Keys(manifests)) {
if slices.Contains(manifests[name].Offers(), provision) {
out = append(out, manifests[name])
}
}
return out
}
g := Graph{}
for name, m := range manifests {
g[name] = EdgesOf(m, providers)
}
g.LeaveOut()
return g
}
// Served is whether a running build serves a seat verb or module tool (ADR 0614 §2, §7), counted from the holders' own
// haves as a provider is (ADR 0603 §5): every have running healthy, by node and module, whose build's manifest serves it
// (servesOf answers the verbs of a module's build at a fingerprint, ServesOf of its manifest, and whether it was read).
// A build whose manifest cannot be read counts what fallback answers of its module (the graph's Serves, so a build read
// late never holds its callers for good, or nothing), and is named in unread, sorted, so its reader says so.
func Served(haves map[string]map[string]nodeengine.HaveByNodeModuleValue, servesOf func(module, fp string) ([]string, bool),
fallback func(module string) []string) (served func(invoke string) bool, unread []string) {
set := map[string]bool{}
for _, node := range slices.Sorted(maps.Keys(haves)) {
for _, module := range slices.Sorted(maps.Keys(haves[node])) {
h := haves[node][module]
if h.Phase != nodeengine.HaveByNodeModuleValuePhaseRunning || h.Health != nodeengine.HaveByNodeModuleValueHealthOk {
continue
}
serves, ok := servesOf(module, h.Fp)
if !ok {
unread = append(unread, module)
if fallback != nil {
serves = fallback(module)
}
}
for _, v := range serves {
set[v] = true
}
}
}
return func(v string) bool { return set[v] }, slices.Compact(slices.Sorted(slices.Values(unread)))
}
-333
View File
@@ -1,333 +0,0 @@
package graph
import (
"errors"
"maps"
"reflect"
"slices"
"strings"
"testing"
nodeengine "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-delivery/contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
// TestGraphEdges: the module graph's cycle, dependents and providers, each from the edges alone (ADR 0603 §2, ADR 0604 §1).
func TestGraphEdges(t *testing.T) {
t.Run("a node's value", nodeValues)
t.Run("a reader of the seat list waits for its holder", readersOfTheSeatList)
t.Run("a verb is served by a running healthy have of the node-engine contract", servedByHaves)
// ADR 0636 §2, issue 1966: a need of a bootstrapped seat is read by every engine whatever its statement names; a seat
// not bootstrapped and a word stay missing, and an engine stating none is read as the baseline.
t.Run("a bootstrapped seat is read by every engine", func(t *testing.T) {
stated := []string{"word:claims", "word:invokes"}
for _, c := range []struct {
name string
needs, stated []string
want []string
}{
{"mesh-catalog and node-backup", []string{"seat:mesh-catalog", "seat:node-backup", "word:invokes"}, stated, nil},
{"a seat not bootstrapped", []string{"seat:mesh-catalog", "seat:mesh-vault"}, stated, []string{"seat:mesh-vault"}},
{"a word", []string{"seat:node-engine", "word:zone"}, stated, []string{"word:zone"}},
{"the baseline", []string{"seat:mesh-catalog", "form:seat-reach"}, nil, []string{"form:seat-reach"}},
} {
if got := MissingReads(c.needs, c.stated); !slices.Equal(got, c.want) {
t.Errorf("%s: missing %v, want %v", c.name, got, c.want)
}
}
})
fp := "src2:" + strings.Repeat("b", 64)
node := func(repository, path string, edit func(*Node)) Node {
n := Node{FP: fp, Repository: repository, Path: path}
if edit != nil {
edit(&n)
}
return n
}
gotool := map[string]Toolchain{"go": {Module: "build-go", Version: "go1", Recipe: "1"}}
// A base chain, a package and a build module: app stands on base, imports lib's package, is built by build-go.
g := Graph{
"build-go": node("novox/mesh-catalog", "modules/build-go", func(n *Node) { n.Toolchains = gotool }),
"lib": node("novox/lib", meshcatalogclient.RootPath, nil),
"base": node("novox/mesh-catalog", "modules/base", nil),
"app": node("novox/mesh-catalog", "modules/app", func(n *Node) {
n.Bases, n.Packages, n.Toolchains = []string{"base"}, []string{"git.novox.be/novox/lib"}, gotool
}),
"top": node("novox/mesh-catalog", "modules/top", func(n *Node) { n.Bases = []string{"app"} }),
// A package published from inside a module's directory belongs to that module (ADR 0604 §1): users imports build-go's.
"users": node("novox/other", "modules/users", func(n *Node) {
n.Packages = []string{"git.novox.be/novox/mesh-catalog/modules/build-go/buildrun"}
}),
"db": node("novox/mesh-catalog", "modules/db", func(n *Node) { n.Provides = []string{"database"} }),
"web": node("novox/mesh-catalog", "modules/web", func(n *Node) {
n.Requires, n.Awaits = []string{"database", "db"}, []string{"database"}
}),
}
for module, want := range map[string][]string{
"base": {"app", "top"},
"lib": {"app", "top"},
"build-go": {"app", "top", "users"}, // build-go's own toolchain edge reaches itself, which is left out
"top": nil,
"db": nil, // a provision edge is no build edge
} {
if got := g.Dependents(module); !reflect.DeepEqual(got, want) {
t.Errorf("dependents of %s = %v, want %v", module, got, want)
}
}
if got := g.Providers("database"); !reflect.DeepEqual(got, []string{"db"}) {
t.Errorf("providers of database = %v", got)
}
if got := g.Providers("db"); !reflect.DeepEqual(got, []string{"db"}) { // a module provides its own name
t.Errorf("providers of db = %v", got)
}
if got := g.Before("web"); !reflect.DeepEqual(got, []string{"db"}) { // web awaits database, which db provides
t.Errorf("web waits for %v", got)
}
if got := g.Before("top"); !reflect.DeepEqual(got, []string{"app"}) {
t.Errorf("top waits for %v", got)
}
if got := g.Requirers("db"); !reflect.DeepEqual(got, []string{"web"}) {
t.Errorf("requirers of db = %v", got)
}
for pkg, want := range map[string]string{
"git.novox.be/novox/mesh-catalog/modules/build-go/buildrun": "build-go", // inside its directory
"git.novox.be/novox/mesh-catalog/modules/build-go": "build-go", // its directory
"git.novox.be/novox/mesh-catalog/modules/build-gone": "", // beside it, not inside
"git.novox.be/novox/lib/sub": "lib", // a root module publishes what is below it
} {
if got := g.Publisher(pkg); got != want {
t.Errorf("publisher of %s = %q, want %q", pkg, got, want)
}
}
if g.Publisher("git.novox.be/novox/lib") != "lib" || g.Publisher("git.novox.be/novox/mesh-sdk/go") != "" {
t.Error("a package's publisher is not the module at its repository and directory")
}
// From manifests alone (the check's graph): a requirement answered by a helper at mesh scope is awaited, an optional
// one is not, and two modules awaiting each other's provision are a cycle.
offer := func(name string) []catalogue.Offer {
return []catalogue.Offer{{Name: name, Scope: catalogue.ScopeMesh, AnsweredBy: catalogue.AnsweredByHelper}}
}
ms := map[string]catalogue.Manifest{
"db": {Module: "db", Provides: offer("database"), Requires: []string{"site", "logs"}, OptionalRequires: map[string]bool{"logs": true}},
"web": {Module: "web", Provides: offer("site"), Requires: []string{"database"}, Build: &catalogue.Build{On: []catalogue.BuildsOn{{Module: "base"}}}},
}
mg := OfManifests(ms)
if db := mg["db"]; !reflect.DeepEqual(db.Requires, []string{"site"}) || !reflect.DeepEqual(db.Awaits, []string{"site"}) ||
!reflect.DeepEqual(mg["web"].Bases, []string{"base"}) || !reflect.DeepEqual(db.Provides, []string{"database"}) {
t.Errorf("the graph of manifests = %+v", mg)
}
if got := mg.Cycle(); !reflect.DeepEqual(got, []string{"db", "web", "db"}) {
t.Errorf("the cycle of manifests = %v", got)
}
// The verb and bus-state edges (ADR 0614 §2, §3, §5, §6), from manifests alone: a caller waits for the module serving
// what it invokes, a bus-state entry requires bus-state of the bus module offering it, the builder's remove and the
// holder's builder_versions close a cycle and both are left out, read from either side, a package edge gives no order,
// and a module invoking its own tool is no wait.
builder := catalogue.Manifest{Module: "builder", Tools: []string{"builder_versions"}, Invokes: []string{"seat:artifact-store.remove"}}
store := catalogue.Manifest{Module: "store", Claims: []catalogue.Claim{{Name: "artifact-store", Scope: catalogue.ScopeMesh,
Serves: []string{"remove"}}}, Invokes: []string{"builder.builder_versions", "*"}}
verbs := map[string]catalogue.Manifest{
"builder": builder, "store": store,
"bus": {Module: "bus", Provides: []catalogue.Offer{{Name: BusState, Scope: catalogue.ScopeMesh}}},
"keeper": {Module: "keeper", BusState: []catalogue.BusStateEntry{{Name: "cache", Storage: "key-value"}}},
"caller": {Module: "caller", Invokes: []string{"seat:artifact-store.remove", "caller.own", "nobody.serves"}, Tools: []string{"own"}},
}
vg := OfManifests(verbs)
for name, want := range map[string][]string{"caller": {"store"}, "keeper": {"bus"}, "builder": nil, "store": nil} {
if got := vg.Before(name); !reflect.DeepEqual(got, want) {
t.Errorf("%s waits for %v, want %v", name, got, want)
}
}
if b, s := vg["builder"], vg["store"]; !reflect.DeepEqual(b.LeftOut, []string{"seat:artifact-store.remove"}) ||
!reflect.DeepEqual(s.LeftOut, []string{"builder.builder_versions"}) ||
!reflect.DeepEqual(s.Serves, []string{"seat:artifact-store.remove"}) || !reflect.DeepEqual(s.Invokes, []string{"builder.builder_versions"}) {
t.Errorf("the builder's cycle is not left out from either side: %+v %+v", b, s)
}
if k := vg["keeper"]; !reflect.DeepEqual(k.Requires, []string{BusState}) || !reflect.DeepEqual(k.Awaits, []string{BusState}) {
t.Errorf("a bus-state entry is no requirement of bus-state: %+v", k)
}
if c := vg["caller"]; !reflect.DeepEqual(c.LeftOut, []string{"caller.own"}) || vg.Cycle() != nil {
t.Errorf("a module's own tool is a wait, or a left-out verb edge a cycle: %+v %v", c, vg.Cycle())
}
if got := OfManifests(map[string]catalogue.Manifest{"keeper": verbs["keeper"]})["keeper"]; got.Awaits != nil {
t.Errorf("bus-state with no module offering it is awaited: %+v", got)
}
// The words of a want held on a verb or a reader capability name their edge, and no other words do.
for words, want := range map[string]string{
VerbWaitWords("seat:mesh-catalog.modules", "artifact-store-tools", "g14"): "verb seat:mesh-catalog.modules",
ReaderWaitWords("g14", []string{"tool-runner", "bus-state"}, "node-tools", "src2:abcdef"): "reader capability tool-runner, bus-state",
BusStateWaitWords("keeper", "g14"): "bus state",
"the verb is served": "",
"the node-engine of g14 has not started": "",
} {
if got := EdgeOfWords(words); got != want {
t.Errorf("the edge of %q = %q, want %q", words, got, want)
}
}
for name, c := range map[string]struct {
edit func(Graph)
want []string
}{
"none: a toolchain on itself and a requirement not awaited order nothing": {func(Graph) {}, nil},
"bases": {func(g Graph) {
b := g["base"]
b.Bases = []string{"top"}
g["base"] = b
}, []string{"app", "base", "top", "app"}},
"provisions a -> b -> a": {func(g Graph) {
d := g["db"]
d.Requires, d.Awaits = []string{"site"}, []string{"site"}
g["db"] = d
w := g["web"]
w.Provides = []string{"site"}
g["web"] = w
}, []string{"db", "web", "db"}},
"a package cycle orders nothing": {func(g Graph) {
l := g["lib"]
l.Packages = []string{"git.novox.be/novox/mesh-catalog/modules/app"}
g["lib"] = l
}, nil},
"a verb edge with a provision, before LeaveOut leaves it out": {func(g Graph) {
d := g["db"]
d.Invokes = []string{"web.page"}
g["db"] = d
w := g["web"]
w.Serves = []string{"web.page"}
g["web"] = w
}, []string{"db", "web", "db"}},
"a requirement not awaited is no edge": {func(g Graph) {
d := g["db"]
d.Requires = []string{"site"}
g["db"] = d
w := g["web"]
w.Provides = []string{"site"}
g["web"] = w
}, nil},
} {
h := Graph{}
for k, v := range g {
h[k] = v
}
c.edit(h)
if got := h.Cycle(); !reflect.DeepEqual(got, c.want) {
t.Errorf("%s: cycle = %v, want %v", name, got, c.want)
}
if h.LeaveOut(); h.Cycle() != nil && slices.ContainsFunc(slices.Collect(maps.Values(h)), func(n Node) bool { return len(n.Invokes) > 0 }) {
t.Errorf("%s: a cycle through a verb edge is left once its verb edges are left out: %v", name, h.Cycle())
}
}
}
// sampleNode is a graph node with every kind of edge, its lists unsorted.
func sampleNode() Node {
return Node{FP: "src2:" + strings.Repeat("a", 64), Repository: "novox/mesh-catalog", Path: "modules/gitea",
Bases: []string{"z-base", "a-base"}, Packages: []string{"git.novox.be/novox/mesh-sdk/go"},
Toolchains: map[string]Toolchain{"go": {Module: "build-go", Version: "go1.27.1", Recipe: "3"}},
Provides: []string{"forge"}, Requires: []string{"postgres-database", "dns"}, Awaits: []string{"postgres-database"},
Invokes: []string{"seat:mesh-catalog.modules", "builder.builder_versions"}, Serves: []string{"seat:forge.pulls"},
LeftOut: []string{"builder.builder_versions"}}
}
// nodeValues: a node round-trips with its lists sorted, an unknown version is refused, a node that does not hold is
// refused naming why, and the state is the indexer's graph (ADR 0603 §2).
func nodeValues(t *testing.T) {
if History != 5 || State != "graph" {
t.Error("the graph's state differs from the decided layout")
}
g := sampleNode()
data, err := Encode(g)
if err != nil || !strings.Contains(string(data), `"v":1`) {
t.Fatalf("encode: %s %v", data, err)
}
if got, err := Decode(data); err != nil || !Same(got, g) || !slices.IsSorted(got.Bases) {
t.Errorf("round trip: %+v %v", got, err)
}
if Same(g, Node{None: "x", Repository: "a/b"}) {
t.Error("different graph nodes are the same")
}
for _, in := range []string{`{"none":"x","repository":"a/b"}`, `{"v":2,"none":"x","repository":"a/b"}`} {
if _, err := Decode([]byte(in)); !errors.Is(err, ErrUnknownVersion) {
t.Errorf("decode of %s = %v, want ErrUnknownVersion", in, err)
}
}
for name, c := range map[string]struct {
change func(*Node)
word string
}{
"both": {func(g *Node) { g.None = "why" }, "both"},
"neither": {func(g *Node) { g.FP = "" }, "neither"},
"an old form": {func(g *Node) { g.FP = "src1:x" }, "src2:"},
"a dotted base": {func(g *Node) { g.Bases = []string{"a.b"} }, "a.b"},
"a foreign package": {func(g *Node) { g.Packages = []string{"example.com/x"} }, "example.com/x"},
"a toolchain of no module": {func(g *Node) { g.Toolchains = map[string]Toolchain{"go": {Version: "go1", Recipe: "1"}} }, "build module"},
"a toolchain of no recipe": {func(g *Node) { g.Toolchains = map[string]Toolchain{"go": {Module: "b", Version: "go1"}} }, "recipe"},
"awaiting what it does not require": {func(g *Node) { g.Awaits = []string{"other"} }, "other"},
"no repository": {func(g *Node) { g.Repository = "" }, "repositor"},
"leaving out what it does not invoke": {func(g *Node) { g.LeftOut = []string{"x.y"} }, "x.y"},
"an invoke of no verb": {func(g *Node) { g.Invokes = []string{"seat:nothing"} }, "seat:nothing"},
} {
g := sampleNode()
c.change(&g)
if _, err := Encode(g); err == nil || !strings.Contains(err.Error(), c.word) {
t.Errorf("a node with %s: %v, want it refused naming %q", name, err, c.word)
}
}
}
// readersOfTheSeatList (D-31): a module whose manifest invokes the seat mesh-catalog's seat-definitions waits, by the verb
// edge, for the module that claims the seat and serves the verb, so the delivery plan puts the holder first (ADR 0614 §2); a
// foundation part the holder itself invokes lies on a cycle with it and the edge is left out, so the part is carried by the
// bootstrapped three until the holder's new build runs (ADR 0636 §1).
func readersOfTheSeatList(t *testing.T) {
const list = "seat:mesh-catalog.seat-definitions"
fp := "src2:" + strings.Repeat("c", 64)
node := func(edit func(*Node)) Node {
n := Node{FP: fp, Repository: "novox/mesh-delivery", Path: "modules/x"}
edit(&n)
return n
}
g := Graph{
"indexer": node(func(n *Node) {
n.Serves = []string{list, "seat:mesh-catalog.modules"}
n.Invokes = []string{"seat:node-engine.composed"}
}),
"checker": node(func(n *Node) { n.Invokes = []string{list} }),
"node-agent": node(func(n *Node) { n.Invokes = []string{list}; n.Serves = []string{"seat:node-engine.composed"} }),
}
if got := g.Servers(list); !reflect.DeepEqual(got, []string{"indexer"}) {
t.Errorf("servers of the seat list = %v", got)
}
if got := g.Before("checker"); !reflect.DeepEqual(got, []string{"indexer"}) {
t.Errorf("the checker waits for %v, want the indexer", got)
}
g.LeaveOut()
if got := g.Before("checker"); !reflect.DeepEqual(got, []string{"indexer"}) {
t.Errorf("after the cycles are left out the checker waits for %v, want the indexer", got)
}
if got := g["node-agent"].LeftOut; !reflect.DeepEqual(got, []string{list}) {
t.Errorf("the node-agent leaves out %v, want the seat list (a cycle with the holder)", got)
}
if got := g.Before("node-agent"); len(got) != 0 {
t.Errorf("the node-agent waits for %v, want nothing: the bootstrap carries it", got)
}
}
// servedByHaves: Served counts the node-engine contract's haves, running and healthy only; an unread build is named.
func servedByHaves(t *testing.T) {
running := nodeengine.HaveByNodeModuleValue{Fp: "a", Phase: nodeengine.HaveByNodeModuleValuePhaseRunning, Health: nodeengine.HaveByNodeModuleValueHealthOk}
failed := nodeengine.HaveByNodeModuleValue{Fp: "b", Phase: nodeengine.HaveByNodeModuleValuePhaseRunning, Health: nodeengine.HaveByNodeModuleValueHealthFailed}
haves := map[string]map[string]nodeengine.HaveByNodeModuleValue{"n1": {"m1": running, "m2": failed, "m3": running}}
served, unread := Served(haves, func(module, fp string) ([]string, bool) {
if module == "m3" {
return nil, false
}
return []string{module + ".verb"}, true
}, nil)
if !served("m1.verb") || served("m2.verb") {
t.Fatalf("a running healthy have serves, a failed one does not: m1 %v, m2 %v", served("m1.verb"), served("m2.verb"))
}
if !reflect.DeepEqual(unread, []string{"m3"}) {
t.Fatalf("unread = %v, want [m3]", unread)
}
}
-37
View File
@@ -1,37 +0,0 @@
package graph
import (
"slices"
"strings"
"sync"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatlist"
)
// bootstrappedReads are the reader capabilities `seat:<seat>` of the bootstrapped seats: the embedded files' own, so
// computed once.
var bootstrappedReads = sync.OnceValue(func() []string {
var out []string
for _, d := range seatlist.Bootstrapped() {
out = append(out, catalogue.ReadSeat+d.Seat)
}
return out
})
// MissingReads is catalogue.MissingManifestReads with every need of a bootstrapped seat counted as read (novox/hq ADR 0614
// §4, ADR 0636 §2): every reader of the seat list holds the bootstrapped seats from its start, before it has read the list,
// so a manifest naming one is read by every node-engine whatever its statement names. Without it an engine whose statement
// was made before its list was in use states no seat, and the node-engine's own build naming mesh-catalog is held on the
// very engine that would state it (issue 1966). The assigner's capability hold and the indexer's hold both judge with it,
// so the rule is one.
func MissingReads(needs, stated []string) []string {
boot := bootstrappedReads()
missing := slices.DeleteFunc(catalogue.MissingManifestReads(needs, stated), func(n string) bool {
return strings.HasPrefix(n, catalogue.ReadSeat) && slices.Contains(boot, n)
})
if len(missing) == 0 {
return nil
}
return missing
}
-61
View File
@@ -1,61 +0,0 @@
package graph
import (
"fmt"
"strings"
)
// The words of a want held on an edge of ADR 0614 (novox/hq ADR 0614 §2, §4, §5): no reader knows a rule number of its own for
// either yet, so the assigner holds them under the provisions' and the composition's rules, and these words are the one
// place they are written and read. The assigner writes them (VerbWaitWords, ReaderWaitWords, BusStateWaitWords); the delivery view names
// the edge a want waits on from them (EdgeOfWords).
const (
verbOpen = "the verb "
verbClose = " invokes is served by no running build"
readerOpen = "the node-engine of "
readerMid = " does not read "
readerTail = ", which the manifest of "
busOpen = "bus state: "
)
// BusStateWaitWords are the words of a want of module on node held until a build of a module offering bus-state runs
// healthy on a node present (ADR 0614 §5, through ADR 0603 §5's count of the provider's own have).
func BusStateWaitWords(module, node string) string {
return fmt.Sprintf("%s%s asks bus state, and no build of a module offering %s runs healthy on a node present: its want on %s waits for one (ADR 0614 §5)",
busOpen, module, BusState, node)
}
// VerbWaitWords are the words of a want of module on node held until a build serving verb runs healthy (ADR 0614 §2).
func VerbWaitWords(verb, module, node string) string {
return fmt.Sprintf("%s%s %s%s: its want on %s waits until a build serving it runs healthy (ADR 0614 §2)", verbOpen, verb,
module, verbClose, node)
}
// ReaderWaitWords are the words of a want of module at fp held on node until its node-engine states the reader
// capabilities missing (ADR 0614 §4).
func ReaderWaitWords(node string, missing []string, module, fp string) string {
return fmt.Sprintf("%s%s%s%s%s%s at %s needs: the want moves once that engine states it", readerOpen, node, readerMid,
strings.Join(missing, ", "), readerTail, module, fp)
}
// EdgeOfWords is the edge a held want's words name: `verb <verb>` for a verb wait, `reader capability <capabilities>` for
// a reader capability's hold, `bus state` for a bus-state wait, or "" for words of none of them.
func EdgeOfWords(words string) string {
if strings.HasPrefix(words, busOpen) {
return "bus state"
}
if rest, ok := strings.CutPrefix(words, verbOpen); ok {
if verb, _, ok := strings.Cut(rest, " "); ok && strings.Contains(rest, verbClose) {
return "verb " + verb
}
}
if rest, ok := strings.CutPrefix(words, readerOpen); ok {
if _, rest, ok := strings.Cut(rest, readerMid); ok {
if missing, _, ok := strings.Cut(rest, readerTail); ok {
return "reader capability " + missing
}
}
}
return ""
}