Register only from a protected trunk of the same repository, and mark the serving controller never the terminal

A source repository's name is not its identity, and a trunk anyone may push
to makes the trunk rule mean nothing (the review of 2026-10-09). Through any
verb a module now registers only from a repository on the mesh's forge whose
trunk refuses direct pushes, requires a status and lets no administrator
merge past one, asked of the forge's own tools; and only from the repository
by the forge's id, recorded at registration (migration 0084), so one deleted
and made again under the name is refused. The serving controller marks its
environment, so nothing it runs or starts reads as the terminal, and a
terminal request covers only the repository and path it asked.

cmd/mesh-controller/build_source.go

@@ -2,10 +2,13 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
+	"regexp"
 	"strings"
+	"time"
 
 	"github.com/novox/mesh-controller/internal/catalogue"
 	"github.com/novox/mesh-controller/internal/inventory"
@@ -35,11 +38,24 @@ import (
 // errNotItsSource is an outcome refused for where it was built from.
 var errNotItsSource = errors.New("not built from the repository the catalogue builds it from")
 
-// startedAtTheTerminal says this process was started at the controller's terminal: neither a verb nor a seat call
-// started it. runVerb sets both for every command a verb runs (seatverbs.go), and a verb is the only way an
-// agent reaches the controller.
+// servedVar marks every process the serving controller starts — each verb's command, each child — and the serving
+// process itself, so none of them can read as the operator at the terminal (novox/hq ADR 0266). Set by serve
+// before it answers anything, inherited by every child through os.Environ.
+const servedVar = "MESH_SERVED_BY_THE_CONTROLLER"
+
+// startedAtTheTerminal says this process was started at the controller's terminal: not the serving controller,
+// not anything it started, not a verb's command, not a seat call's. The serving controller marks its own
+// environment (servedVar), so a build asked in it, or by any process it starts, never reads as the terminal's;
+// runVerb also names the verb and the caller.
 func startedAtTheTerminal() bool {
-	return os.Getenv(verbVar) == "" && os.Getenv(link.CallerVar) == ""
+	return os.Getenv(servedVar) == "" && os.Getenv(verbVar) == "" && os.Getenv(link.CallerVar) == ""
+}
+
+// markServed marks this process, and so everything it starts, as the serving controller's.
+func markServed() {
+	if err := os.Setenv(servedVar, "1"); err != nil {
+		panic("the serving controller could not mark its environment: " + err.Error())
+	}
 }
 
 // sourceForms compares sources however each is spelled: a path on a seat's holder (ADR 0111) or a URL — a
@@ -116,21 +132,166 @@ func (f *sourceForms) buildsFrom(entries []inventory.Entry, repository, seat str
 	return false
 }
 
-// mayRegisterFrom says whether a build's outcome may register module from the source it was built from
-// (novox/hq ADR 0266): from the module's registered repository; for a module new to the catalogue, from a
-// repository the catalogue builds another module from; else only when the build was asked at the terminal.
+// forgeFacts is what the mesh's forge says of a repository a module is registered from (novox/hq ADR 0266).
+type forgeFacts struct {
+	// ID is the forge's own id of the repository: what tells it from one deleted and made again by its name.
+	ID int64
+	// Guarded is whether the branch is protected as a module's trunk must be: no direct push, at least one
+	// required status, and no administrator merging past one. Why says what is missing when it is not.
+	Guarded bool
+	Why     string
+}
+
+// askTheForge asks the forge, through its module's tools on the bus, for a repository's id and its branch's
+// protection. A variable so a test needs no forge.
+var askTheForge = func(ctx context.Context, owner, repo, branch string) (forgeFacts, error) {
+	js, err := aBus()
+	if err != nil {
+		return forgeFacts{}, err
+	}
+	defer js.Close()
+	bus := link.OverNATS{Conn: js.Conn()}
+	ask := func(tool string, args map[string]any, into any) error {
+		raw, _ := json.Marshal(args)
+		answer, err := link.Ask(ctx, bus, "gitea", tool, raw, 30*time.Second)
+		if err != nil {
+			return err
+		}
+		if answer.Error != "" {
+			return fmt.Errorf("gitea.%s: %s", tool, answer.Error)
+		}
+		return json.Unmarshal(answer.Result, into)
+	}
+	var found struct {
+		Result struct {
+			ID       int64  `json:"id"`
+			FullName string `json:"full_name"`
+		} `json:"result"`
+	}
+	if err := ask("gitea_api", map[string]any{"path": "/repos/" + owner + "/" + repo}, &found); err != nil {
+		return forgeFacts{}, err
+	}
+	if found.Result.ID == 0 {
+		return forgeFacts{}, fmt.Errorf("the forge named no id for %s/%s", owner, repo)
+	}
+	var rules struct {
+		Rules []struct {
+			Rule             string   `json:"rule"`
+			Push             bool     `json:"push"`
+			RequiredStatuses []string `json:"required_statuses"`
+			AdminMayOverride bool     `json:"admin_may_override"`
+		} `json:"rules"`
+	}
+	if err := ask("gitea_branch_protection_get", map[string]any{"owner": owner, "repo": repo}, &rules); err != nil {
+		return forgeFacts{}, err
+	}
+	facts := forgeFacts{ID: found.Result.ID, Why: fmt.Sprintf("no protection rule covers %s", branch)}
+	for _, r := range rules.Rules {
+		if !ruleCovers(r.Rule, branch) {
+			continue
+		}
+		switch {
+		case r.Push:
+			facts.Why = fmt.Sprintf("the rule %s lets a person push to %s directly", r.Rule, branch)
+		case len(r.RequiredStatuses) == 0:
+			facts.Why = fmt.Sprintf("the rule %s requires no status before a merge into %s", r.Rule, branch)
+		case r.AdminMayOverride:
+			facts.Why = fmt.Sprintf("the rule %s lets an administrator merge into %s past a status", r.Rule, branch)
+		default:
+			return forgeFacts{ID: facts.ID, Guarded: true}, nil
+		}
+	}
+	return facts, nil
+}
+
+// ruleCovers says a protection rule's name — a branch, or a glob of them — covers a branch, as the forge reads it.
+func ruleCovers(rule, branch string) bool {
+	if rule == branch {
+		return true
+	}
+	if !strings.ContainsAny(rule, "*?[") {
+		return false
+	}
+	var re strings.Builder
+	re.WriteString("^")
+	for i := 0; i < len(rule); i++ {
+		switch c := rule[i]; {
+		case c == '*' && i+1 < len(rule) && rule[i+1] == '*':
+			re.WriteString(".*")
+			i++
+		case c == '*':
+			re.WriteString("[^/]*")
+		case c == '?':
+			re.WriteString("[^/]")
+		default:
+			re.WriteString(regexp.QuoteMeta(string(c)))
+		}
+	}
+	re.WriteString("$")
+	ok, _ := regexp.MatchString(re.String(), branch)
+	return ok
+}
+
+// onTheForge is a source's owner and name on the mesh's own forge (the git seat's holder), and whether it is
+// there at all.
+func (f *sourceForms) onTheForge(repository, seat string) (owner, name string, ok bool) {
+	var rest string
+	switch {
+	case seat == gitSeat:
+		rest = strings.Trim(repository, "/")
+	case seat == "":
+		base := f.base(gitSeat)
+		if base == "" {
+			return "", "", false
+		}
+		url, prefix := f.canonical(repository, ""), f.canonical(base, "")+"/"
+		if !strings.HasPrefix(url, prefix) {
+			return "", "", false
+		}
+		// The case the forge spells it with: the URL as given, past the base.
+		rest = strings.TrimSuffix(strings.Trim(repository[len(prefix):], "/"), ".git")
+	default:
+		return "", "", false
+	}
+	parts := strings.Split(rest, "/")
+	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", false
+	}
+	return parts[0], parts[1], true
+}
+
+// mayRegisterFrom says whether a build's outcome may register module from the source it was built from, and the
+// forge's id of that repository to record (novox/hq ADR 0266). Through any verb, only:
+//
+//   - from the module's registered repository — the same repository by the forge's own id, not only its name; or,
+//     for a module new to the catalogue, from a repository the catalogue builds another module from;
+//   - and from a repository on the mesh's forge whose trunk is protected as a trunk must be: no direct push, at
+//     least one required status, no administrator merging past one.
+//
+// Anything else only when the build request was kept as asked at the controller's terminal, for this very
+// repository and path. path is the module's directory as built; branch the trunk it is registered from.
 func mayRegisterFrom(ctx context.Context, inv *inventory.Inventory, module string, built inventory.Source,
-	buildID string) error {
+	buildID, path, branch string) (int64, error) {
 	forms := newSourceForms(ctx, inv)
 	was, err := inv.SourceOf(ctx, module)
 	isNew := errors.Is(err, inventory.ErrNoSuchModule)
 	if err != nil && !isNew {
-		return err
+		return 0, err
 	}
+	terminal, err := askedHereFor(ctx, inv, forms, buildID, built, path)
+	if err != nil {
+		return 0, err
+	}
+	refuse := func(why string) (int64, error) {
+		return 0, fmt.Errorf("%w: %s. A module is registered from such a source only by a build asked at the "+
+			"controller's terminal, never through a verb: a registered module is what the next push sends, and whoever "+
+			"may call a verb includes agents (novox/hq ADR 0266)", errNotItsSource, why)
+	}
+
 	var why string
+	var alongside []inventory.Entry // the modules a new one's repository already builds
 	switch {
 	case !isNew && forms.same(was.Repository, was.Seat, built.Repository, built.Seat):
-		return nil
 	case !isNew:
 		registered := was.Repository
 		if registered == "" {
@@ -141,25 +302,94 @@ func mayRegisterFrom(ctx context.Context, inv *inventory.Inventory, module strin
 	default:
 		entries, err := inv.Catalogued(ctx)
 		if err != nil {
-			return err
+			return 0, err
 		}
-		if forms.buildsFrom(entries, built.Repository, built.Seat) {
-			return nil
+		for _, e := range entries {
+			if !e.Provided && e.Source.Repository != "" &&
+				forms.same(e.Source.Repository, e.Source.Seat, built.Repository, built.Seat) {
+				alongside = append(alongside, e)
+			}
+		}
+		if len(alongside) == 0 {
+			why = fmt.Sprintf("%s is new to the catalogue, and %s is no repository the catalogue builds a module from",
+				module, sourceWords(built.Repository, built.Seat))
 		}
-		why = fmt.Sprintf("%s is new to the catalogue, and %s is no repository the catalogue builds a module from",
-			module, sourceWords(built.Repository, built.Seat))
 	}
-	terminal, err := inv.AskedAtTheTerminal(ctx, buildID)
+	if why != "" && !terminal {
+		return refuse(why)
+	}
+
+	owner, name, onForge := forms.onTheForge(built.Repository, built.Seat)
+	if !onForge {
+		if terminal {
+			fmt.Printf("%s: %s is not on the mesh's forge — registered, as asked at the controller's terminal\n",
+				buildID, sourceWords(built.Repository, built.Seat))
+			return 0, nil
+		}
+		return refuse(fmt.Sprintf("%s is not on the mesh's forge, so whether its trunk is protected cannot be read",
+			sourceWords(built.Repository, built.Seat)))
+	}
+	facts, err := askTheForge(ctx, owner, name, branch)
 	if err != nil {
-		return err
+		if terminal {
+			fmt.Printf("%s: the forge could not be asked about %s/%s (%v) — registered, as asked at the controller's "+
+				"terminal\n", buildID, owner, name, err)
+			return 0, nil
+		}
+		return refuse(fmt.Sprintf("the forge could not say whether %s/%s's %s is protected: %v", owner, name, branch, err))
 	}
 	if terminal {
-		fmt.Printf("%s: %s — registered, as asked at the controller's terminal\n", buildID, why)
-		return nil
+		if why != "" || !facts.Guarded {
+			fmt.Printf("%s: %s — registered, as asked at the controller's terminal\n", buildID,
+				strings.Trim(why+"; "+facts.Why, "; "))
+		}
+		return facts.ID, nil
 	}
-	return fmt.Errorf("%w: %s. A module is registered from another repository only by a build asked at the "+
-		"controller's terminal, never through a verb: a registered module is what the next push sends, and whoever "+
-		"may call a verb includes agents (novox/hq ADR 0266)", errNotItsSource, why)
+	if !facts.Guarded {
+		return refuse(fmt.Sprintf("%s/%s's %s is not protected as a module's trunk must be: %s", owner, name, branch,
+			facts.Why))
+	}
+	// The same repository by the forge's id, not only its name: one deleted and made again is another.
+	recorded := map[string]int64{}
+	if !isNew {
+		id, err := inv.SourceIdentity(ctx, module)
+		if err != nil {
+			return 0, err
+		}
+		recorded[module] = id
+	}
+	for _, e := range alongside {
+		id, err := inv.SourceIdentity(ctx, e.Manifest.Module)
+		if err != nil {
+			return 0, err
+		}
+		recorded[e.Manifest.Module] = id
+	}
+	for m, id := range recorded {
+		if id != 0 && id != facts.ID {
+			return refuse(fmt.Sprintf("%s/%s is not the repository %s was registered from: the forge knows it as "+
+				"repository %d, and %s was registered from repository %d — one of that name deleted and made again",
+				owner, name, m, facts.ID, m, id))
+		}
+	}
+	return facts.ID, nil
+}
+
+// askedHereFor says the build was asked at the controller's terminal, for this repository and this path: a kept
+// request marked so, whose source is the outcome's (novox/hq ADR 0266).
+func askedHereFor(ctx context.Context, inv *inventory.Inventory, forms *sourceForms, buildID string,
+	built inventory.Source, path string) (bool, error) {
+	r, found, err := inv.BuildRequestByID(ctx, buildID)
+	if err != nil || !found || !r.AtTerminal {
+		return false, err
+	}
+	if !forms.same(r.Repository, r.Seat, built.Repository, built.Seat) ||
+		strings.Trim(r.Path, "/") != strings.Trim(path, "/") {
+		fmt.Printf("%s was asked at the terminal of %s at %q, and its outcome is of %s at %q: not the terminal's\n",
+			buildID, sourceWords(r.Repository, r.Seat), r.Path, sourceWords(built.Repository, built.Seat), path)
+		return false, nil
+	}
+	return true, nil
 }
 
 // sourceWords is a source as a person reads it.