Design 47 H1: the indexer registers a module that enters the trunk's module graph

Four modules added to a repository after the registrations' seed were never
registered, so a pipeline's steps for them waited on a registration nobody
asked. A kept trunk revision of any kind now registers each of its modules
with no registration, before the revision is said, with no ask: origin its
repository, path its manifest's, the first watched branch, the steps its
repository's other modules hold alike (else the seed's) and a per-artifact
status only where every sibling naming that artifact holds it identically,
said registration-changed. The start does the same once for the current
trunk graph. With no registration held the seed stays the only writer; a
module that leaves the graph keeps its registration.

Builds: design 47 H H-A-262, H-A-263, H-A-264, G A-327, ADR 0666 §2
This commit is contained in:
2026-11-21 13:09:23 +01:00
parent d1ec9d9072
commit 251745f859
5 changed files with 302 additions and 4 deletions
@@ -17,6 +17,7 @@ import (
"log"
"os"
"os/signal"
"strings"
"sync/atomic"
"syscall"
"time"
@@ -380,7 +381,16 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
logger.Printf("start: %s", name)
return func() { logger.Printf("start: %s done in %s", name, time.Since(began).Round(time.Millisecond)) }
}
done := step("reading the build log")
// A module of the current trunk graph with no registration is registered once at the start, as a kept trunk revision
// registers one entering the graph (design 47 H H-A-262, H-A-264 (1)); said loudly, whatever it answers.
done := step("registering the trunk graph's modules that have no registration")
if written, err := ix.RegisterTrunkGraph(ctx); err != nil {
logger.Printf("start: the trunk graph's modules with no registration are not all registered (%d were): %v", len(written), err)
} else {
logger.Printf("start: %d modules of the trunk graph had no registration and are registered now: %s", len(written), strings.Join(written, ", "))
}
done()
done = step("reading the build log")
// The log's entries at the start are read before any fingerprint is computed (below).
var started atomic.Bool
var startEnds []stdio.LogEntry // the log's entries read at the start, whose imports are kept once the packages are published
@@ -446,6 +446,11 @@ func (ix *Indexer) keepBranchEntries(ctx context.Context, branch string, src int
ix.sayFill(ctx, meshcatalog.EventFilling, fmt.Sprintf("%d", rev.Revision), meshcatalog.Fill{Bytes: after, Cap: capacity})
}
ix.logf("catalog graph: revision %d of source revision %d kept (%s), %d entries, %d changed", rev.Revision, src, call.Call, len(rev.Entries), len(changed))
// A module entering the trunk's graph is registered before the revision is said, at every kind of kept trunk revision
// (design 47 H H-A-262, H-A-264).
if isTrunkBranch(branch) {
ix.registerEntering(ctx, slices.Collect(maps.Values(entries)))
}
if ix.SayCatalogRevision != nil {
if err := ix.SayCatalogRevision(ctx, meshcatalog.CatalogRevisionEvent{V: CatalogEntryLayout, Revision: rev.Revision, Kind: rev.Kind,
Branch: keys.EscapeName(branch), Source: src, Call: call.Call, CallKind: call.Kind, Module: call.Module, Version: call.Version,
@@ -0,0 +1,154 @@
package index
import (
"context"
"fmt"
"path"
"slices"
"strings"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
// seedSteps are the seed's module-wide statuses (§8, design 47 H §745): the statuses the check judged until then, lint, unit
// tests, integration tests, composition and validate required, code review optional, approval bypass.
func seedSteps() meshcatalog.StepStatuses {
return meshcatalog.StepStatuses{Lint: "required", Unit: "required", Integration: "required",
Composition: "required", Review: "optional", Approval: "bypass", Validate: "required"}
}
// GraphModule is a module of a trunk revision's module graph as its registration is composed when it enters the graph
// (design 47 H H-A-262): its repository, the path of its manifest and the names of its artifacts.
type GraphModule struct {
Module string
Origin string
Path string
Artifacts []string
}
// GraphModulesOf are the modules of a trunk revision's entries, sorted by module.
func GraphModulesOf(entries []meshcatalog.CatalogEntry) []GraphModule {
out := make([]GraphModule, 0, len(entries))
for _, e := range entries {
m := GraphModule{Module: e.Module, Origin: e.Repository, Path: path.Join(e.Path, ModuleManifest)}
for _, a := range e.Artifacts {
m.Artifacts = append(m.Artifacts, artifactName(a.Ref))
}
out = append(out, m)
}
slices.SortFunc(out, func(a, b GraphModule) int { return strings.Compare(a.Module, b.Module) })
return out
}
// enteringPolicy is the policy of a module entering the graph (H-A-262, H-A-263): the module-wide steps every other
// registered module of its repository holds alike, else the seed's; a per-artifact status only for an artifact name the module
// has that every sibling naming it holds identically; nothing else.
func enteringPolicy(m GraphModule, siblings []meshcatalog.Registration) meshcatalog.Policy {
p := meshcatalog.Policy{Steps: seedSteps()}
if len(siblings) > 0 {
alike := true
for _, s := range siblings[1:] {
alike = alike && s.Policy.Steps == siblings[0].Policy.Steps
}
if alike {
p.Steps = siblings[0].Policy.Steps
}
}
for _, a := range m.Artifacts {
var held []meshcatalog.StepStatuses
for _, s := range siblings {
if st, ok := s.Policy.Artifacts[a]; ok {
held = append(held, st)
}
}
if len(held) == 0 || slices.ContainsFunc(held[1:], func(st meshcatalog.StepStatuses) bool { return st != held[0] }) {
continue
}
if p.Artifacts == nil {
p.Artifacts = map[string]meshcatalog.StepStatuses{}
}
p.Artifacts[a] = held[0]
}
return p
}
// RegisterEntering registers every module of mods that has no registration (design 47 H H-A-262, H-A-263; the operator,
// 2026-11-14: a module in the module graph is a registration): origin its repository, path its manifest's, the first watched
// branch, the policy of its repository's other registered modules (enteringPolicy), version 1 with no ask, said
// registration-changed. A module already registered is left as it is; none is ever removed here. While no registration is
// held it registers none: the seed writes the first (H-A-264 (2)). It answers the modules it registered, sorted.
func (r *Registry) RegisterEntering(ctx context.Context, mods []GraphModule, by string) ([]string, error) {
r.mu.Lock()
defer r.mu.Unlock()
held, err := r.RegistrationsAnswer(ctx, meshcatalog.RegistrationsInput{})
if err != nil {
return nil, fmt.Errorf("the registrations are not read: %w", err)
}
if len(held.Registrations) == 0 {
// With none held, the seed is the first and only writer: its policy reads the build seats' steps (H-A-264 (2)).
r.logf("registrations: none is held, so no module entering the module graph is registered here: the seed writes the first (H-A-264)")
return nil, nil
}
have := map[string]bool{}
byOrigin := map[string][]meshcatalog.Registration{}
for _, reg := range held.Registrations {
have[reg.Module] = true
byOrigin[reg.Origin] = append(byOrigin[reg.Origin], reg)
}
var written []string
var errs []string
for _, m := range mods {
if m.Module == "" || have[m.Module] {
continue
}
reg := meshcatalog.Registration{Module: m.Module, Origin: m.Origin, Path: m.Path, Branches: []string{TrunkBranch},
Policy: enteringPolicy(m, byOrigin[m.Origin])}
p := Proposal{V: 1, Verb: verbRegister, Module: m.Module, Caller: by, At: r.now(), State: ProposalOpen,
Lines: []string{fmt.Sprintf("%s: registered as it entered the module graph (%s, %s)", m.Module, m.Origin, m.Path)}}
if err := r.write(ctx, "", p, reg, oc.Warrant{Ask: "module-graph"}); err != nil {
errs = append(errs, fmt.Sprintf("%s: %v", m.Module, err))
continue
}
have[m.Module] = true
written = append(written, m.Module)
r.logf("registrations: %s entered the module graph of %s with no registration: registered as version 1 from %s (%s), watching %s (H-A-262)",
m.Module, TrunkBranch, m.Origin, m.Path, TrunkBranch)
}
if len(errs) > 0 {
return written, fmt.Errorf("the registrations of modules entering the module graph are not written: %s", strings.Join(errs, "; "))
}
return written, nil
}
// registerEntering registers each module of a kept trunk revision's entries that has no registration (H-A-262, H-A-264 (1),
// (3)): a module entering the trunk's graph, at any kind of kept trunk revision. A dry run, or an indexer with no
// registrations, registers none. A failure is said in the journal: the revision is kept whatever it answers.
func (ix *Indexer) registerEntering(ctx context.Context, entries []meshcatalog.CatalogEntry) {
if ix.isDry || ix.Registry == nil || ix.Registry.Registrations == nil {
return
}
written, err := ix.Registry.RegisterEntering(ctx, GraphModulesOf(entries), ix.Registry.Module)
if len(written) > 0 {
ix.logf("registrations: %d modules entering the module graph of %s registered: %s (H-A-262)", len(written), TrunkBranch, strings.Join(written, ", "))
}
if err != nil {
ix.logf("registrations: %v (H-A-262)", err)
}
}
// RegisterTrunkGraph registers, once at the indexer's start, each module of the current trunk graph that has no registration
// (H-A-264 (1)), as a kept trunk revision does; it answers the modules it registered.
func (ix *Indexer) RegisterTrunkGraph(ctx context.Context) ([]string, error) {
if ix.isDry || ix.Registry == nil || ix.Registry.Registrations == nil || ix.Revisions == nil {
return nil, nil
}
_, entries, found, err := readNewestOf(ctx, ix.Revisions, TrunkBranch)
if err != nil {
return nil, fmt.Errorf("the newest trunk revision is not read: %w", err)
}
if !found {
return nil, nil
}
return ix.Registry.RegisterEntering(ctx, GraphModulesOf(entries), ix.Registry.Module)
}
@@ -0,0 +1,131 @@
package index
import (
"context"
"slices"
"testing"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
// Design 47 H H-A-262, H-A-263, H-A-264 (ADR 0666 §2 read with the operator's rule of 2026-11-14): a module that enters a
// watched trunk's module graph is registered as the revision is kept, before it is said, with no ask: origin its repository,
// path its manifest's, the first watched branch, the module-wide steps its repository's other modules hold alike (else the
// seed's) and a per-artifact status only where every sibling naming that artifact holds it identically, said
// registration-changed. A module registered already is untouched, a branch that is not the trunk registers none, an indexer
// holding no registration leaves the first to the seed, and the start registers the current trunk graph's unregistered ones.
func TestAModuleEnteringTheTrunkGraphIsRegistered(t *testing.T) {
ctx := context.Background()
g := newRegRig()
var order []string
say := g.r.Say
g.r.Say = func(ctx context.Context, e meshcatalog.RegistrationChangedEvent) error {
order = append(order, "registration-changed "+e.Module)
return say(ctx, e)
}
ix := &Indexer{Module: testSelf, Revisions: newMemObjects(1 << 20), Now: g.r.Now}
ix.SayCatalogRevision = func(_ context.Context, e meshcatalog.CatalogRevisionEvent) error {
order = append(order, "catalog-revision "+e.Branch)
return nil
}
entry := func(module, repo, dir string, artifacts ...string) meshcatalog.CatalogEntry {
e := meshcatalog.CatalogEntry{Module: module, Repository: repo, Path: dir, Commit: "c1", Manifest: map[string]any{}}
for _, a := range artifacts {
e.Artifacts = append(e.Artifacts, meshcatalog.Artifact{Ref: module + ":" + a})
}
return e
}
keep := func(branch string, src int64, entries ...meshcatalog.CatalogEntry) {
t.Helper()
m := map[string]meshcatalog.CatalogEntry{}
for _, e := range entries {
m[e.Module] = e
}
if err := ix.KeepBranchEntries(ctx, branch, src, m, nil); err != nil {
t.Fatal(err)
}
}
// No registration held: the seed is the first writer, so a kept trunk revision registers nothing (H-A-264 (2)).
ix.Registry = g.r
keep("main", 1, entry("core", "novox/c", "go/core", "lib"))
if regs, _ := g.r.RegistrationsAnswer(ctx, meshcatalog.RegistrationsInput{}); len(regs.Registrations) != 0 {
t.Fatalf("with no registration held a trunk revision registered %v, want none: the seed writes the first", regs.Registrations)
}
steps := meshcatalog.StepStatuses{Lint: "required", Unit: "required", Integration: "required", Composition: "required", Review: "optional", Approval: "bypass"}
other := steps
other.Lint = "optional"
held := []meshcatalog.Registration{
{Module: "core", Origin: "novox/c", Path: "go/core/module.json", Branches: []string{"main"}, Policy: meshcatalog.Policy{Steps: steps,
Artifacts: map[string]meshcatalog.StepStatuses{"lib": {Integration: "bypass"}, "files": {Lint: "bypass", Unit: "bypass"}}}},
{Module: "tools", Origin: "novox/c", Path: "go/tools/module.json", Branches: []string{"main"}, Policy: meshcatalog.Policy{Steps: steps,
Artifacts: map[string]meshcatalog.StepStatuses{"lib": {Integration: "bypass"}, "files": {Unit: "bypass"}}}},
{Module: "x1", Origin: "novox/mixed", Path: "x1/module.json", Branches: []string{"main"}, Policy: meshcatalog.Policy{Steps: steps}},
{Module: "x2", Origin: "novox/mixed", Path: "x2/module.json", Branches: []string{"main"}, Policy: meshcatalog.Policy{Steps: other}},
}
for _, reg := range held {
if err := g.r.write(ctx, "", Proposal{V: 1, Verb: verbRegister, Module: reg.Module, Caller: "test", State: ProposalOpen}, reg, oc.Warrant{Ask: "test"}); err != nil {
t.Fatal(err)
}
}
g.events, order = nil, nil
// A take-in that lists three new modules beside a registered one.
keep("main", 2, entry("core", "novox/c", "go/core", "lib"), entry("lib2", "novox/c", "go/lib2", "lib", "files", "bin"),
entry("solo", "novox/new", "solo", "app"), entry("x3", "novox/mixed", "x3"))
got := func(module string) meshcatalog.Registration {
t.Helper()
r, found, err := g.r.Registration(ctx, module)
if err != nil || !found {
t.Fatalf("%s is not registered (%v)", module, err)
}
return r
}
lib2 := got("lib2")
if lib2.Version != 1 || lib2.Origin != "novox/c" || lib2.Path != "go/lib2/module.json" || !slices.Equal(lib2.Branches, []string{TrunkBranch}) {
t.Errorf("lib2 registered as %+v, want version 1 from novox/c, go/lib2/module.json, watching main", lib2)
}
if lib2.Policy.Steps != steps {
t.Errorf("lib2's steps %+v, want its repository's modules' alike steps %+v (H-A-263)", lib2.Policy.Steps, steps)
}
if a := lib2.Policy.Artifacts; len(a) != 1 || a["lib"] != (meshcatalog.StepStatuses{Integration: "bypass"}) {
t.Errorf("lib2's artifacts %+v, want lib alone, the one status its siblings hold identically (files differs, bin none)", a)
}
if solo := got("solo"); solo.Policy.Steps != seedSteps() || len(solo.Policy.Artifacts) != 0 {
t.Errorf("solo, alone in its repository, has %+v, want the seed's default", solo.Policy)
}
if x3 := got("x3"); x3.Policy.Steps != seedSteps() {
t.Errorf("x3, whose siblings' steps differ, has %+v, want the seed's default", x3.Policy.Steps)
}
if core := got("core"); core.Version != 1 || core.By != "test" {
t.Errorf("core, registered already, became %+v, want it untouched", core)
}
if len(g.asks) != 0 {
t.Errorf("registering modules entering the graph asked %v, want no ask", g.asks)
}
wantOrder := []string{"registration-changed lib2", "registration-changed solo", "registration-changed x3", "catalog-revision main"}
if !slices.Equal(order, wantOrder) {
t.Errorf("said %v, want %v: each registration said before the revision", order, wantOrder)
}
// A branch that is not the trunk registers none (H-A-264 (3)); a module that leaves the graph keeps its registration.
keep("feature", 3, entry("feat", "novox/c", "go/feat", "lib"))
keep("main", 4, entry("core", "novox/c", "go/core", "lib"))
if _, found, _ := g.r.Registration(ctx, "feat"); found {
t.Error("a revision of the branch feature registered feat, want only the trunk's")
}
got("lib2")
// At the start, a module of the current trunk graph with no registration is registered (H-A-264 (1)); again, none.
ix.Registry = nil
keep("main", 5, entry("core", "novox/c", "go/core", "lib"), entry("late", "novox/c", "go/late"))
ix.Registry = g.r
if written, err := ix.RegisterTrunkGraph(ctx); err != nil || !slices.Equal(written, []string{"late"}) {
t.Fatalf("the start registered %v (%v), want late", written, err)
}
if written, err := ix.RegisterTrunkGraph(ctx); err != nil || len(written) != 0 {
t.Errorf("a second start registered %v (%v), want none", written, err)
}
}
@@ -74,9 +74,7 @@ func (r *Registry) ComposeSeed(modules []SeedModule) (SeedProposal, error) {
return out, fmt.Errorf("the default branch of %s is not read: %s", m.Origin, b.Error)
}
reg := meshcatalog.Registration{Module: m.Module, Origin: m.Origin, Path: m.Path, Branches: []string{b.Branch},
Policy: meshcatalog.Policy{Steps: meshcatalog.StepStatuses{Lint: "required", Unit: "required", Integration: "required",
Composition: "required", Review: "optional", Approval: "bypass",
Validate: "required"}}} // design 47 H §745: the step validate is required in every policy by default
Policy: meshcatalog.Policy{Steps: seedSteps()}} // design 47 H §745: the step validate is required in every policy by default
for _, a := range m.Artifacts {
var s meshcatalog.StepStatuses
if !slices.Contains(a.Steps, "lint") {