Files
mesh-delivery/modules/mesh-delivery-indexer/internal/index/catalog_edges.go
T
jschoubben daa7737392 Item 5 (join 11): an asker's build-seat queue is served by the seat's holders, so the indexer draws its kind-6 edge
An asker names the queue it asks as seat:<seat>.accept.<queue> (A-231); no module's serves lists that form, so
graph.Servers matched nothing and the indexer drew no served-verb edge from a build seat's holders to the asker.
Servers now reads the form through mesh-sdk's catalogue.QueueInvoke and answers every module serving a verb of the
seat; the kind-6 edge asks the module graph's Servers, the one rule, instead of a match of its own.

Builds: design 47 G §544, §605, A-231

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 13:08:40 +01:00

381 lines
14 KiB
Go

package index
import (
"cmp"
"context"
"encoding/json"
"maps"
"slices"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// The edges of a catalog graph entry (design 47 G §47 to §50, §121; A-208): the indexer writes, in each entry of a revision,
// the edges between artifact references of kinds 1, 2, 3, 4 and 6 that the entry's own words and the other entries of the same
// revision say (the builder and the assigner read them from the entry, never derive their own). Kind 5 is the acting rules' (§711, below). An edge runs from B, the artifact that comes first, to A, the artifact that waits for it.
// WithEdges gives each entry of a revision its edges. The entries given are not changed. The edges of kinds 1 to 4 and 6 are
// each entry's own; those of kind 5 (§711) need the others' edges of kinds 1 to 4, so they come after.
func WithEdges(entries map[string]meshcatalog.CatalogEntry) map[string]meshcatalog.CatalogEntry {
out := make(map[string]meshcatalog.CatalogEntry, len(entries))
for module, e := range entries {
e.Edges = edgesOf(e, entries)
out[module] = e
}
built := pathsTo(out)
for module, e := range out {
if acting := actingEdges(e, out, built); len(acting) > 0 {
e.Edges = slices.Clone(e.Edges)
for _, x := range acting {
if !slices.Contains(e.Edges, x) {
e.Edges = append(e.Edges, x)
}
}
sortEdges(e.Edges)
out[module] = e
}
}
return out
}
// kind5Steps are the steps of an acting rule that give an edge of kind 5 (§711): a grant or a credential, a composition, a
// placement and a verdict, each made for the dependent's new version. `build` gives kind 3, `take-in` and `validate` none.
var kind5Steps = []string{seatdef.StepGrant, seatdef.StepCompose, seatdef.StepPlace, seatdef.StepCheck, seatdef.StepPipeline}
// WithActs gives each entry its `acts` (§711): for each seat its manifest claims, each acting rule the seat's definition in
// defs carries, as one item {seat, step, on, bound} sorted by seat then step; an entry claiming no seat with a rule has none.
// The entries given are not changed.
func WithActs(entries map[string]meshcatalog.CatalogEntry, defs map[string]seatdef.Definition) map[string]meshcatalog.CatalogEntry {
out := make(map[string]meshcatalog.CatalogEntry, len(entries))
for module, e := range entries {
var acts []meshcatalog.ActingRule
for _, c := range manifestOf(e).Claims {
for _, r := range defs[c.Name].Acts {
acts = append(acts, meshcatalog.ActingRule{Seat: c.Name, Step: r.Step, On: r.On, Bound: r.Bound})
}
}
slices.SortStableFunc(acts, func(x, y meshcatalog.ActingRule) int {
return cmp.Or(strings.Compare(x.Seat, y.Seat), strings.Compare(x.Step, y.Step))
})
e.Acts = slices.Compact(acts)
out[module] = e
}
return out
}
// pathsTo says, for each module, the modules it is built from or needs: those with a path of edges of kinds 1 to 4 to it
// (a package, a fetched artifact, a build module or base, a provider), read from the entries' edges.
func pathsTo(entries map[string]meshcatalog.CatalogEntry) map[string]map[string]bool {
direct := map[string][]string{} // module -> the modules with an edge of kinds 1 to 4 into it
for module, e := range entries {
for _, x := range e.Edges {
if x.Kind >= 1 && x.Kind <= 4 {
direct[module] = append(direct[module], strings.SplitN(x.From, ":", 2)[0])
}
}
}
out := map[string]map[string]bool{}
for module := range entries {
seen := map[string]bool{}
stack := []string{module}
for len(stack) > 0 {
m := stack[len(stack)-1]
stack = stack[:len(stack)-1]
for _, from := range direct[m] {
if !seen[from] {
seen[from] = true
stack = append(stack, from)
}
}
}
out[module] = seen
}
return out
}
// actingEdges are the edges of kind 5 into entry a (§711): from the delivered artifact of each other entry B whose acting rule
// in a step of kind5Steps matches a, unless a has no artifact or a has a path of edges
// of kinds 1 to 4 to B (built[b][a]): a is then what B's new version is built from or needs, which B's running version acts on (§270).
func actingEdges(a meshcatalog.CatalogEntry, all map[string]meshcatalog.CatalogEntry, built map[string]map[string]bool) []meshcatalog.Edge {
to := primaryOf(a)
if to == "" {
return nil
}
var out []meshcatalog.Edge
for _, m := range slices.Sorted(maps.Keys(all)) {
b := all[m]
from := primaryOf(b)
if m == a.Module || from == "" || built[m][a.Module] {
continue
}
for _, r := range b.Acts {
if slices.Contains(kind5Steps, r.Step) && ruleActsOn(r.On, a) {
out = append(out, meshcatalog.Edge{Kind: 5, From: from, To: to, Word: "acts", Why: r.Seat + " " + r.Step})
}
}
}
return out
}
// ruleActsOn says whether an acting rule's `on` matches entry a: every (or none), a language a has an artifact of, or
// kind:image with an artifact of kind image (§324).
func ruleActsOn(on string, a meshcatalog.CatalogEntry) bool {
switch on {
case "", seatdef.OnEvery:
return true
case seatdef.OnKindImage:
return slices.ContainsFunc(a.Artifacts, func(x meshcatalog.Artifact) bool { return x.Kind == "image" })
}
return slices.ContainsFunc(a.Artifacts, func(x meshcatalog.Artifact) bool { return seatdef.ActingRule{On: on}.ActsOn(x.Language) })
}
func sortEdges(out []meshcatalog.Edge) {
slices.SortFunc(out, func(x, y meshcatalog.Edge) int {
return cmp.Or(cmp.Compare(x.Kind, y.Kind), strings.Compare(x.From, y.From), strings.Compare(x.To, y.To), strings.Compare(x.Word, y.Word), strings.Compare(x.Why, y.Why))
})
}
// primaryOf is the artifact an entry delivers: the one its first process resource runs, else its first artifact; empty for a
// module with no artifact.
func primaryOf(e meshcatalog.CatalogEntry) meshcatalog.ArtifactRef {
if resources, ok := e.Manifest["resources"].([]any); ok {
for _, r := range resources {
res, _ := r.(map[string]any)
if res["type"] != "process" {
continue
}
if name, _ := res["artifact"].(string); name != "" && slices.ContainsFunc(e.Artifacts, func(a meshcatalog.Artifact) bool { return a.Ref == ArtifactRefOf(e.Module, name) }) {
return ArtifactRefOf(e.Module, name)
}
}
}
if len(e.Artifacts) > 0 {
return e.Artifacts[0].Ref
}
return ""
}
// ofLanguage are the artifacts of e a build of language (go or another) produces: its packages' and programs' of that language.
func ofLanguage(e meshcatalog.CatalogEntry, language string) []meshcatalog.ArtifactRef {
var out []meshcatalog.ArtifactRef
for _, a := range e.Artifacts {
if a.Language == language {
out = append(out, a.Ref)
}
}
return out
}
func edgesOf(a meshcatalog.CatalogEntry, all map[string]meshcatalog.CatalogEntry) []meshcatalog.Edge {
var out []meshcatalog.Edge
add := func(e meshcatalog.Edge) {
if e.From != "" && e.To != "" && e.From != e.To && !slices.Contains(out, e) {
out = append(out, e)
}
}
modules := slices.Sorted(maps.Keys(all))
delivers := primaryOf(a)
// Kind 1: a package its build imports, from the artifact that publishes it, to each artifact built from that ecosystem (§47).
for _, name := range slices.Sorted(maps.Keys(a.Packages)) {
for _, m := range modules {
b := all[m]
if m == a.Module {
continue
}
for _, art := range b.Artifacts {
if art.Package == nil || art.Package.Name != name {
continue
}
for _, to := range importersOf(a, art.Package.Ecosystem) {
add(meshcatalog.Edge{Kind: 1, From: art.Ref, To: to, Stale: true, Word: "packages", Why: name})
}
}
}
}
// Kind 2: an artifact its manifest's `needs` references in another module, published before the artifact that names it
// delivers (A-212, §432).
for _, n := range needsOf(a) {
if owner := all[strings.SplitN(n.ref, ":", 2)[0]]; owner.Module != "" && owner.Module != a.Module &&
slices.ContainsFunc(owner.Artifacts, func(x meshcatalog.Artifact) bool { return x.Ref == n.ref }) {
add(meshcatalog.Edge{Kind: 2, From: n.ref, To: n.by, Declared: true, Word: "needs", Why: n.ref})
}
}
// Kind 3: the build module its language names and the modules it is built on (§47, §378).
for _, language := range slices.Sorted(maps.Keys(a.Toolchains)) {
builder, ok := all[a.Toolchains[language].Module]
if !ok || builder.Module == a.Module {
continue
}
for _, to := range ofLanguage(a, language) {
add(meshcatalog.Edge{Kind: 3, From: primaryOf(builder), To: to, Stale: true, Word: "toolchains", Why: language})
}
}
for _, base := range a.Bases {
b, ok := all[base]
if !ok || b.Module == a.Module {
continue
}
for _, art := range a.Artifacts {
add(meshcatalog.Edge{Kind: 3, From: primaryOf(b), To: art.Ref, Stale: true, Word: "build.on", Why: base})
}
}
// Kind 4: a provision it requires and a provider offers (§47): the provisions a want of it waits for.
for _, provision := range a.Awaits {
for _, m := range modules {
if b := all[m]; m != a.Module && (slices.Contains(b.Provides, provision) || m == provision) {
add(meshcatalog.Edge{Kind: 4, From: primaryOf(b), To: delivers, Word: "requires", Why: provision})
}
}
}
// Kind 6: a verb or a tool it invokes and another entry serves (§47), unless its edge lies on a cycle and is left out (ADR 0614 §3).
// A verb whose answer's fields it relies on (the long form of `invokes`, §558) names them in the edge's `why`.
// Who serves an invoke is the module graph's one rule (graph.Servers): a build seat's queue, `seat:<seat>.accept.<queue>`,
// is its holders' (A-231).
serving := graph.Graph{}
for _, m := range modules {
serving[m] = graph.Node{Serves: all[m].Serves}
}
fields := manifestOf(a).InvokeFields
for _, verb := range a.Invokes {
if slices.Contains(a.LeftOut, verb) {
continue
}
why := verb
if named := fields[verb]; len(named) > 0 {
why += " fields " + strings.Join(named, ", ")
}
for _, m := range serving.Servers(verb) {
if m != a.Module {
add(meshcatalog.Edge{Kind: 6, From: primaryOf(all[m]), To: delivers, Word: verb, Why: why})
}
}
}
// Kind 6 again: a package it builds against whose artifact takes `calls` (the capability words its code calls of the tool
// runner) orders it after the artifact that `states` each word, so no manifest names the tool runner's module (§605, §545).
for _, name := range slices.Sorted(maps.Keys(a.Packages)) {
for _, m := range modules {
for _, art := range all[m].Artifacts {
if art.Package == nil || art.Package.Name != name {
continue
}
for _, word := range wordsOf(all[m], art.Ref, "calls") {
for _, other := range modules {
for _, stating := range all[other].Artifacts {
if other != a.Module && slices.Contains(wordsOf(all[other], stating.Ref, "states"), word) {
add(meshcatalog.Edge{Kind: 6, From: stating.Ref, To: delivers, Word: word, Why: "calls of " + name})
}
}
}
}
}
}
}
sortEdges(out)
return out
}
// manifestOf is the manifest the entry carries whole, read by the manifest reader; none where it cannot be read.
func manifestOf(e meshcatalog.CatalogEntry) catalogue.Manifest {
raw, err := json.Marshal(e.Manifest)
if err != nil {
return catalogue.Manifest{}
}
m, err := catalogue.Decode(raw)
if err != nil {
return catalogue.Manifest{}
}
return m
}
// wordsOf are the words an artifact's entry in the entry's manifest lists under key (`calls` or `states`).
func wordsOf(e meshcatalog.CatalogEntry, ref meshcatalog.ArtifactRef, key string) []string {
build, _ := e.Manifest["build"].(map[string]any)
arts, _ := build["artifacts"].([]any)
var out []string
for _, x := range arts {
art, _ := x.(map[string]any)
if name, _ := art["name"].(string); ArtifactRefOf(e.Module, name) != ref {
continue
}
list, _ := art[key].([]any)
for _, w := range list {
if word, _ := w.(string); word != "" {
out = append(out, word)
}
}
}
return out
}
type need struct{ by, ref string }
// needsOf are the artifact references each artifact of the entry's manifest names in its `needs`, with the artifact that names them.
func needsOf(e meshcatalog.CatalogEntry) []need {
build, _ := e.Manifest["build"].(map[string]any)
arts, _ := build["artifacts"].([]any)
var out []need
for _, x := range arts {
art, _ := x.(map[string]any)
name, _ := art["name"].(string)
list, _ := art["needs"].([]any)
for _, r := range list {
if ref, _ := r.(string); ref != "" && name != "" {
out = append(out, need{by: ArtifactRefOf(e.Module, name), ref: ref})
}
}
}
return out
}
// importersOf are the artifacts of a built from a package of ecosystem: a Go package by the Go artifacts, an npm package by
// the others that are no image.
func importersOf(a meshcatalog.CatalogEntry, ecosystem string) []meshcatalog.ArtifactRef {
var out []meshcatalog.ArtifactRef
for _, art := range a.Artifacts {
if art.Kind == "image" {
continue
}
if (ecosystem == EcosystemGo) == (art.Language == "go") && ecosystem != EcosystemImage {
out = append(out, art.Ref)
}
}
return out
}
// withActs gives each entry its `acts` from the trunk definitions of the seats the indexer keeps (§711; the state the verb
// seat-definitions answers from); where it keeps none, the entries are left as they are.
func (ix *Indexer) withActs(ctx context.Context, entries map[string]meshcatalog.CatalogEntry) map[string]meshcatalog.CatalogEntry {
if ix.SeatDefinitions == nil {
return entries
}
keys, err := ix.SeatDefinitions.Keys(ctx)
if err != nil {
ix.logf("catalog graph: the acting rules are not read: the %s state cannot be listed: %v", SeatDefinitionsState, err)
return entries
}
defs := map[string]seatdef.Definition{}
for _, key := range keys {
seat, ok := strings.CutSuffix(key, "."+SourceTrunk)
if !ok || strings.HasPrefix(key, outOfStepPrefix) {
continue
}
value, _, found, err := ix.SeatDefinitions.Get(ctx, key)
if err != nil || !found {
continue
}
var e SeatDefinitionEntry
if json.Unmarshal(value, &e) != nil || len(e.Definition) == 0 {
continue
}
var d seatdef.Definition // kept after the format's reader parsed it, so read as it was kept
if json.Unmarshal(e.Definition, &d) == nil {
defs[seat] = d
}
}
return WithActs(entries, defs)
}