graph: the refused cycle is shared code, read by the indexer and the validate step

RefusedCycle, with its running-version break and its path search, moves from the indexer's
internal/index into mesh-delivery-sdk/graph, so the assigner's validate step reads the same rule
the indexer's take-in does; the indexer calls the shared function. The rule's table test moves
with it; the indexer keeps its test of the trunk catalogues against the shared rule.

Builds: design 47 H §745; lead answers H-A-34, H-A-104 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 04:00:13 +01:00
parent 89e0926feb
commit 5bf6fd9b01
7 changed files with 154 additions and 239 deletions
@@ -6,6 +6,8 @@ import (
"maps"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-sdk/go/process"
)
@@ -53,7 +55,7 @@ func (ix *Indexer) ApplyBranchSource(ctx context.Context, branch string, a meshd
return err
}
// A cycle with a build edge no running version breaks is refused here as at the trunk's take-in (design 47 G §49, A-326).
if cycle := RefusedCycle(WithEdges(ix.withActs(ctx, entries))); cycle != nil {
if cycle := graph.RefusedCycle(WithEdges(ix.withActs(ctx, entries))); cycle != nil {
ix.logf("catalog graph: the branch %s at source revision %d keeps no revision: its catalog graph holds a cycle with a build edge, which no running version breaks (design 47 G §49): %s; taken in again at its next source-moved", branch, a.Revision, strings.Join(cycle, ", "))
return nil
}
@@ -453,87 +453,3 @@ func (ix *Indexer) withActs(ctx context.Context, entries map[string]meshcatalog.
}
return WithActs(entries, defs)
}
// RefusedCycle is a cycle of the entries' edges that the take-in refuses (design 47 G §49, A-326, A-333), as the artifacts it
// passes through with the first named again at its end; nil when there is none. A cycle of delivery edges (kinds 2, 4, 5, 6)
// alone is delivered as one step, so only a cycle holding a build edge (kind 1 or 3) is refused, and not one of package edges
// (kind 1) alone: the language's own build refuses a real import cycle (A-333). A build edge of kind 3 that goes out of an
// artifact of a module holding a build seat into an artifact that seat builds is where such a cycle is broken: the running
// version builds the new one (§270), so a cycle through it is allowed, as the cycle through a build module's own inputs is.
func RefusedCycle(entries map[string]meshcatalog.CatalogEntry) []meshcatalog.ArtifactRef {
var edges []meshcatalog.Edge
for _, m := range slices.Sorted(maps.Keys(entries)) {
for _, x := range entries[m].Edges {
if x.From != "" && x.To != "" && !brokenAtTheRunningVersion(x, entries) {
edges = append(edges, x)
}
}
}
next := map[meshcatalog.ArtifactRef][]meshcatalog.Edge{}
for _, x := range edges {
next[x.From] = append(next[x.From], x)
}
for _, x := range edges {
if x.Kind != 1 && x.Kind != 3 {
continue
}
if path := pathBack(next, x.To, x.From, x.Kind != 1); path != nil {
return append([]meshcatalog.ArtifactRef{x.From}, path...)
}
}
return nil
}
// brokenAtTheRunningVersion says whether x is a build edge of kind 3 out of an artifact of a module that holds a build seat
// (an acting rule of step build) into an artifact that seat builds (A-326).
func brokenAtTheRunningVersion(x meshcatalog.Edge, entries map[string]meshcatalog.CatalogEntry) bool {
if x.Kind != 3 {
return false
}
builder, to := entries[strings.SplitN(x.From, ":", 2)[0]], entries[strings.SplitN(x.To, ":", 2)[0]]
i := slices.IndexFunc(to.Artifacts, func(a meshcatalog.Artifact) bool { return a.Ref == x.To })
if i < 0 {
return false
}
art := to.Artifacts[i]
return slices.ContainsFunc(builder.Acts, func(r meshcatalog.ActingRule) bool {
if r.Step != seatdef.StepBuild {
return false
}
if r.On == seatdef.OnKindImage {
return art.Kind == "image"
}
return seatdef.ActingRule{On: r.On}.ActsOn(art.Language)
})
}
// pathBack is the shortest path of next from start to end, start and end included, that holds an edge of a kind other than 1
// unless other is true already (a cycle of package edges alone is none of §49's, A-333); nil when there is none.
func pathBack(next map[meshcatalog.ArtifactRef][]meshcatalog.Edge, start, end meshcatalog.ArtifactRef, other bool) []meshcatalog.ArtifactRef {
type at struct {
ref meshcatalog.ArtifactRef
other bool
}
from := at{start, other}
before := map[at]at{from: {}}
queue := []at{from}
for len(queue) > 0 {
cur := queue[0]
queue = queue[1:]
if cur.ref == end && cur.other {
var path []meshcatalog.ArtifactRef
for ; cur != (at{}); cur = before[cur] {
path = append([]meshcatalog.ArtifactRef{cur.ref}, path...)
}
return path
}
for _, x := range next[cur.ref] {
n := at{x.To, cur.other || x.Kind != 1}
if _, seen := before[n]; !seen {
before[n] = cur
queue = append(queue, n)
}
}
}
return nil
}
@@ -8,6 +8,8 @@ import (
"testing"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
@@ -278,44 +280,9 @@ func TestAKeptRevisionHoldsTheActsAndTheKindFiveEdges(t *testing.T) {
}
}
// A-326, A-333 (design 47 G §49, §51): a cycle through a build module's own inputs is broken at its running version and
// allowed, as are a cycle of package edges alone and a cycle of delivery edges alone; any other cycle with a build edge is
// refused, naming every artifact on it. Today's trunk catalogue and G's own (the entries of G's dry run, 2026-11-13, kept
// in testdata with what the edges are computed from) are accepted.
func TestACycleWithABuildEdgeIsRefusedUnlessABuildSeatsRunningVersionBreaksIt(t *testing.T) {
builder := meshcatalog.CatalogEntry{Module: "mesh-build-go", Artifacts: []meshcatalog.Artifact{{Ref: "mesh-build-go:files", Language: "go"}},
Acts: []meshcatalog.ActingRule{{Seat: "node-build-go", Step: seatdef.StepBuild, On: "go"}}}
handActs := meshcatalog.CatalogEntry{Module: "mesh-hand-acts", Artifacts: []meshcatalog.Artifact{{Ref: "mesh-hand-acts:tools", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 3, From: "mesh-build-go:files", To: "mesh-hand-acts:tools", Word: "toolchains", Why: "go"}}}
trunkCycle := builder
trunkCycle.Edges = []meshcatalog.Edge{{Kind: 6, From: "mesh-hand-acts:tools", To: "mesh-build-go:files", Word: "seat:mesh-hand-acts.hand-act"}}
a := meshcatalog.CatalogEntry{Module: "a", Artifacts: []meshcatalog.Artifact{{Ref: "a:go", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 1, From: "b:go", To: "a:go", Word: "packages"}}}
b := meshcatalog.CatalogEntry{Module: "b", Artifacts: []meshcatalog.Artifact{{Ref: "b:go", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 1, From: "a:go", To: "b:go", Word: "packages"}}}
noSeat := trunkCycle
noSeat.Acts = nil
verbsOnly := meshcatalog.CatalogEntry{Module: "c", Artifacts: []meshcatalog.Artifact{{Ref: "c:go"}}, Edges: []meshcatalog.Edge{{Kind: 6, From: "d:go", To: "c:go"}}}
verbsBack := meshcatalog.CatalogEntry{Module: "d", Artifacts: []meshcatalog.Artifact{{Ref: "d:go"}}, Edges: []meshcatalog.Edge{{Kind: 4, From: "c:go", To: "d:go"}}}
for _, c := range []struct {
name string
entries []meshcatalog.CatalogEntry
want []meshcatalog.ArtifactRef
}{
{"the trunk catalogue's cycle through a build module's own inputs", []meshcatalog.CatalogEntry{trunkCycle, handActs}, nil},
{"two artifacts each needing the other's new package, package edges alone", []meshcatalog.CatalogEntry{a, b}, nil},
{"the same cycle from a module that holds no build seat", []meshcatalog.CatalogEntry{noSeat, handActs},
[]meshcatalog.ArtifactRef{"mesh-build-go:files", "mesh-hand-acts:tools", "mesh-build-go:files"}},
{"a cycle of delivery edges alone", []meshcatalog.CatalogEntry{verbsOnly, verbsBack}, nil},
} {
entries := map[string]meshcatalog.CatalogEntry{}
for _, e := range c.entries {
entries[e.Module] = e
}
if got := RefusedCycle(entries); !slices.Equal(got, c.want) {
t.Errorf("%s: refused %v, want %v", c.name, got, c.want)
}
}
// A-326, A-333 (design 47 G §49, §51): today's trunk catalogue and G's own (the entries of G's dry run, 2026-11-13, kept
// in testdata with what the edges are computed from) are accepted by the shared cycle rule (graph.RefusedCycle).
func TestTheTrunkCataloguesHoldNoRefusedCycle(t *testing.T) {
for _, name := range []string{"catalog-entries-trunk-2026-11-13", "catalog-entries-47-G-2026-11-13"} {
raw, err := os.ReadFile("testdata/" + name + ".json")
if err != nil {
@@ -325,7 +292,7 @@ func TestACycleWithABuildEdgeIsRefusedUnlessABuildSeatsRunningVersionBreaksIt(t
if err := json.Unmarshal(raw, &entries); err != nil {
t.Fatal(err)
}
if got := RefusedCycle(WithEdges(entries)); got != nil {
if got := graph.RefusedCycle(WithEdges(entries)); got != nil {
t.Errorf("%s: refused %v, want the catalogue accepted", name, got)
}
}
@@ -10,6 +10,8 @@ import (
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
@@ -787,7 +789,7 @@ func (ix *Indexer) refuseCycle(ctx context.Context, ready []PendingEntry, d *dry
if err != nil {
return "", false, err
}
cycle := RefusedCycle(WithEdges(ix.withActs(ctx, entries)))
cycle := graph.RefusedCycle(WithEdges(ix.withActs(ctx, entries)))
if cycle == nil {
return "", false, nil
}
+94
View File
@@ -0,0 +1,94 @@
package graph
import (
"maps"
"slices"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// RefusedCycle is a cycle of the entries' edges that the take-in and the validate step refuse (design 47 H-A-34, H-A-104) (design 47 G §49, A-326, A-333), as the artifacts it
// passes through with the first named again at its end; nil when there is none. A cycle of delivery edges (kinds 2, 4, 5, 6)
// alone is delivered as one step, so only a cycle holding a build edge (kind 1 or 3) is refused, and not one of package edges
// (kind 1) alone: the language's own build refuses a real import cycle (A-333). A build edge of kind 3 that goes out of an
// artifact of a module holding a build seat into an artifact that seat builds is where such a cycle is broken: the running
// version builds the new one (§270), so a cycle through it is allowed, as the cycle through a build module's own inputs is.
func RefusedCycle(entries map[string]meshcatalog.CatalogEntry) []meshcatalog.ArtifactRef {
var edges []meshcatalog.Edge
for _, m := range slices.Sorted(maps.Keys(entries)) {
for _, x := range entries[m].Edges {
if x.From != "" && x.To != "" && !brokenAtTheRunningVersion(x, entries) {
edges = append(edges, x)
}
}
}
next := map[meshcatalog.ArtifactRef][]meshcatalog.Edge{}
for _, x := range edges {
next[x.From] = append(next[x.From], x)
}
for _, x := range edges {
if x.Kind != 1 && x.Kind != 3 {
continue
}
if path := pathBack(next, x.To, x.From, x.Kind != 1); path != nil {
return append([]meshcatalog.ArtifactRef{x.From}, path...)
}
}
return nil
}
// brokenAtTheRunningVersion says whether x is a build edge of kind 3 out of an artifact of a module that holds a build seat
// (an acting rule of step build) into an artifact that seat builds (A-326).
func brokenAtTheRunningVersion(x meshcatalog.Edge, entries map[string]meshcatalog.CatalogEntry) bool {
if x.Kind != 3 {
return false
}
builder, to := entries[strings.SplitN(x.From, ":", 2)[0]], entries[strings.SplitN(x.To, ":", 2)[0]]
i := slices.IndexFunc(to.Artifacts, func(a meshcatalog.Artifact) bool { return a.Ref == x.To })
if i < 0 {
return false
}
art := to.Artifacts[i]
return slices.ContainsFunc(builder.Acts, func(r meshcatalog.ActingRule) bool {
if r.Step != seatdef.StepBuild {
return false
}
if r.On == seatdef.OnKindImage {
return art.Kind == "image"
}
return seatdef.ActingRule{On: r.On}.ActsOn(art.Language)
})
}
// pathBack is the shortest path of next from start to end, start and end included, that holds an edge of a kind other than 1
// unless other is true already (a cycle of package edges alone is none of §49's, A-333); nil when there is none.
func pathBack(next map[meshcatalog.ArtifactRef][]meshcatalog.Edge, start, end meshcatalog.ArtifactRef, other bool) []meshcatalog.ArtifactRef {
type at struct {
ref meshcatalog.ArtifactRef
other bool
}
from := at{start, other}
before := map[at]at{from: {}}
queue := []at{from}
for len(queue) > 0 {
cur := queue[0]
queue = queue[1:]
if cur.ref == end && cur.other {
var path []meshcatalog.ArtifactRef
for ; cur != (at{}); cur = before[cur] {
path = append([]meshcatalog.ArtifactRef{cur.ref}, path...)
}
return path
}
for _, x := range next[cur.ref] {
n := at{x.To, cur.other || x.Kind != 1}
if _, seen := before[n]; !seen {
before[n] = cur
queue = append(queue, n)
}
}
}
return nil
}
@@ -0,0 +1,48 @@
package graph
import (
"slices"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// A-326, A-333 (design 47 G §49, §51): a cycle through a build module's own inputs is broken at its running version and
// allowed, as are a cycle of package edges alone and a cycle of delivery edges alone; any other cycle with a build edge is
// refused, naming every artifact on it (design 47 H-A-104: the rule both the indexer and the validate step read).
func TestACycleWithABuildEdgeIsRefusedUnlessABuildSeatsRunningVersionBreaksIt(t *testing.T) {
builder := meshcatalog.CatalogEntry{Module: "mesh-build-go", Artifacts: []meshcatalog.Artifact{{Ref: "mesh-build-go:files", Language: "go"}},
Acts: []meshcatalog.ActingRule{{Seat: "node-build-go", Step: seatdef.StepBuild, On: "go"}}}
handActs := meshcatalog.CatalogEntry{Module: "mesh-hand-acts", Artifacts: []meshcatalog.Artifact{{Ref: "mesh-hand-acts:tools", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 3, From: "mesh-build-go:files", To: "mesh-hand-acts:tools", Word: "toolchains", Why: "go"}}}
trunkCycle := builder
trunkCycle.Edges = []meshcatalog.Edge{{Kind: 6, From: "mesh-hand-acts:tools", To: "mesh-build-go:files", Word: "seat:mesh-hand-acts.hand-act"}}
a := meshcatalog.CatalogEntry{Module: "a", Artifacts: []meshcatalog.Artifact{{Ref: "a:go", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 1, From: "b:go", To: "a:go", Word: "packages"}}}
b := meshcatalog.CatalogEntry{Module: "b", Artifacts: []meshcatalog.Artifact{{Ref: "b:go", Language: "go"}},
Edges: []meshcatalog.Edge{{Kind: 1, From: "a:go", To: "b:go", Word: "packages"}}}
noSeat := trunkCycle
noSeat.Acts = nil
verbsOnly := meshcatalog.CatalogEntry{Module: "c", Artifacts: []meshcatalog.Artifact{{Ref: "c:go"}}, Edges: []meshcatalog.Edge{{Kind: 6, From: "d:go", To: "c:go"}}}
verbsBack := meshcatalog.CatalogEntry{Module: "d", Artifacts: []meshcatalog.Artifact{{Ref: "d:go"}}, Edges: []meshcatalog.Edge{{Kind: 4, From: "c:go", To: "d:go"}}}
for _, c := range []struct {
name string
entries []meshcatalog.CatalogEntry
want []meshcatalog.ArtifactRef
}{
{"the trunk catalogue's cycle through a build module's own inputs", []meshcatalog.CatalogEntry{trunkCycle, handActs}, nil},
{"two artifacts each needing the other's new package, package edges alone", []meshcatalog.CatalogEntry{a, b}, nil},
{"the same cycle from a module that holds no build seat", []meshcatalog.CatalogEntry{noSeat, handActs},
[]meshcatalog.ArtifactRef{"mesh-build-go:files", "mesh-hand-acts:tools", "mesh-build-go:files"}},
{"a cycle of delivery edges alone", []meshcatalog.CatalogEntry{verbsOnly, verbsBack}, nil},
} {
entries := map[string]meshcatalog.CatalogEntry{}
for _, e := range c.entries {
entries[e.Module] = e
}
if got := RefusedCycle(entries); !slices.Equal(got, c.want) {
t.Errorf("%s: refused %v, want %v", c.name, got, c.want)
}
}
}
@@ -1,114 +0,0 @@
package watch
import (
"encoding/json"
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
// KindManifestRefused is a module whose manifest the indexer's judge refused (novox/hq ADR 0578 §1): every reader holds
// it, composing nothing of its own, until a mended manifest is merged.
const KindManifestRefused = "manifest-refused"
// KindManifestOutgrown is a module whose manifest the indexer accepted before and a stricter judge finds problems in
// (novox/hq ADR 0579 §1): it stays accepted and runs; the warning stands until the manifest is mended.
const KindManifestOutgrown = FindingManifestOutgrown
// The manifest findings are the indexer's verdicts heard as events (design 47 G §500): `manifest-refused` raises the refusal, and
// `manifest-accepted`, which carries `problems` (what a stricter validator finds in a manifest it still accepts), raises
// `manifest-outgrown` or, with none, clears it and any refusal. The watchman seeds both from the indexer's verdicts at its start
// (VerdictsTool). `manifest-waits` is no longer written: every revision is judged by a validator built from its own heads (§16).
// VerdictsTool is the indexer's tool that lists its verdicts, which seeds the findings at the start; it is asked of the holder of
// the seat mesh-catalog when it is asked (design 47 G A-210, §428), never of a module named here.
const VerdictsTool = "indexer_verdicts"
// VerdictRow is one verdict as the tool lists it (the fields the watchman reads).
type VerdictRow struct {
Module string `json:"module"`
State string `json:"state"`
Problems []string `json:"problems"`
Warnings []string `json:"warnings"`
At time.Time `json:"at"`
}
// ManifestRefused hears the seat mesh-catalog's manifest-refused: the module's manifest is refused until a mended one is accepted.
func (w *Watchman) ManifestRefused(e meshcatalog.ManifestRefusedEvent) {
if e.Module == "" {
w.say("a manifest-refused names no module, left")
return
}
w.mu.Lock()
defer w.mu.Unlock()
w.verdict(e.Module, e.Problems, nil, true)
}
// manifestAccepted hears the problems a manifest-accepted carries (Accepted calls it, w.mu held): none clears the module's findings, some are its warning.
func (w *Watchman) manifestAccepted(module string, problems []string) {
w.verdict(module, nil, problems, false)
}
// SeedVerdicts raises, at the start, the findings of the newest verdict of each module the indexer's tool listed: a refused one, or an
// accepted one with warnings. A module whose newest verdict is accepted clears both.
func (w *Watchman) SeedVerdicts(rows []VerdictRow) {
newest := map[string]VerdictRow{}
for _, r := range rows {
if old, ok := newest[r.Module]; !ok || r.At.After(old.At) {
newest[r.Module] = r
}
}
w.mu.Lock()
defer w.mu.Unlock()
for module, r := range newest {
switch r.State {
case meshcatalogclient.VerdictRefused:
w.verdict(module, r.Problems, nil, true)
case meshcatalogclient.VerdictAccepted:
w.verdict(module, nil, r.Warnings, false)
}
}
}
// DecodeVerdictRows reads the answer of the indexer's verdicts tool.
func DecodeVerdictRows(raw []byte) ([]VerdictRow, error) {
var a struct {
Verdicts []VerdictRow `json:"verdicts"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("not an answer of the indexer's verdicts: %w", err)
}
return a.Verdicts, nil
}
// verdict writes and clears a module's manifest findings, w.mu held: a refusal (problems, refused) or an outgrown manifest (warnings).
func (w *Watchman) verdict(module string, problems, warnings []string, refused bool) {
refusedKey := FindingKey(ScopeModule, module, KindManifestRefused)
outgrownKey := FindingKey(ScopeModule, module, KindManifestOutgrown)
if refused {
w.unfind(outgrownKey)
w.find(Finding{Scope: ScopeModule, ID: module, Kind: KindManifestRefused, Severity: Warning, Source: "indexer.verdicts",
Summary: "the indexer's judge refused the manifest of " + module + ": " + strings.Join(problems, "; "),
Said: strings.Join(problems, "; "),
Headline: "The manifest of " + module + " is refused",
Explanation: "The indexer's judge refused it, so every node, the grants part and the assigner hold " + module + ": " +
"nothing of it changes until a mended manifest is merged, and every other module goes on.",
Needs: "a pull request that mends the manifest of " + module})
return
}
w.unfind(refusedKey)
if len(warnings) == 0 {
w.unfind(outgrownKey)
return
}
w.find(Finding{Scope: ScopeModule, ID: module, Kind: KindManifestOutgrown, Severity: Warning, Source: "indexer.verdicts",
Summary: "the manifest of " + module + " breaks rules the indexer's judge holds it to now: " + strings.Join(warnings, "; "),
Said: strings.Join(warnings, "; "),
Headline: "The manifest of " + module + " needs mending",
Explanation: "A stricter judge found problems in a manifest it accepted before; " + module + " stays accepted and " +
"runs, and its next change is refused until they are mended (novox/hq ADR 0579).",
Needs: "a pull request that mends the manifest of " + module})
}