Revert the revert of G's mesh-sdk merge (#191): G's sdk stands again over reader release 3

Main reverted G's half merge (#189, reverted by 8afc3eb in #191) and then took the reader release's S1-S5, which
copied G's code. G's form holds where they differ (process_bus.go, seats.go, state.go and their tests); the
release's kept names stay so main's callers keep building: SeatViewPrefix beside SeatReadPrefix, and QueueInvoke's
empty strings on not-ok (with its test TestQueueInvoke). The tree differs from G's head f30dee54 only by those and
the release's two tests (objects cap option, seat states and stream kinds).

Builds: design 47 G (the milestone's sdk part, as at f30dee54)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h

go/buscompose/engine.go

@@ -1,12 +0,0 @@
-package buscompose
-
-// EngineModule is the node-engine's manifest's module name, and EngineActsState its state the acts asked through the
-// node seat and its own asks are kept in (ADR 0563 §2, §3: "the engine's own state"): the bucket mesh-host_acts, keys
-// `<node>.act.<id>`, `<node>.open.<act>.<digest>` and `<node>.ask.<id>`, each written by that node's engine alone.
-const (
-	EngineModule    = "mesh-host"
-	EngineActsState = "acts"
-)
-
-// EngineActsBucket is that state's bucket.
-var EngineActsBucket = BucketName(EngineModule, EngineActsState)

go/buscompose/events.go

@@ -0,0 +1,106 @@
+package buscompose
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// The one place the mesh's event subjects are named (design 34 every-event §1, §25, §26), so neither the grants part
+// nor the tool runner spells the event namespace itself.
+
+// The namespaces an event lands in, as `from` names them (design 34 every-event §13, §26).
+const (
+	fromSeat   = "seat"
+	fromModule = "module"
+	fromStream = "stream"
+)
+
+// eventNamespaces are the three, each with the prefix its subjects start with, in EveryEvent's order.
+var eventNamespaces = []struct{ from, prefix string }{
+	{fromSeat, "mesh.seat."},
+	{fromModule, "mesh.mod."},
+	{fromStream, moduleStreamPrefix},
+}
+
+// EveryEvent is the subjects the tool runner's account hears: every seat's events, every module's, and every module
+// stream's, a restricted one included, in that order (novox/hq ADR 0670 §1, ADR 0671 §1).
+func EveryEvent() []string {
+	out := make([]string, 0, len(eventNamespaces))
+	for _, ns := range eventNamespaces {
+		out = append(out, ns.prefix+"*.event.>")
+	}
+	return out
+}
+
+// eventToken is the form of each token of an event name.
+var eventToken = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
+
+// EventSubjects is the subjects one event name lands on. A name is `<emitter>.<event>`, optionally followed by further
+// tokens (`operator-channel.decided.claude-code`), each token of the form `[A-Za-z0-9_-]+`. With from empty it answers
+// six subjects, per namespace (seat, module, stream) `mesh.<ns>.<emitter>.event.<rest>` and the same followed by `.>`;
+// with from `seat`, `module` or `stream` only that namespace's two. It refuses, naming the rule, a name of fewer than two
+// tokens, an empty token or a token outside that form (so `*` and `>` are refused), and a from of any other word.
+func EventSubjects(name, from string) ([]string, error) {
+	tokens := strings.Split(name, ".")
+	if len(tokens) < 2 {
+		return nil, fmt.Errorf("event name %q has fewer than two tokens: a name is <seat or module>.<event>", name)
+	}
+	for _, t := range tokens {
+		if !eventToken.MatchString(t) {
+			return nil, fmt.Errorf("event name %q has the token %q: each token of a name matches [A-Za-z0-9_-]+, "+
+				"so no token is empty and none is * or >", name, t)
+		}
+	}
+	emitter, rest := tokens[0], strings.Join(tokens[1:], ".")
+	var out []string
+	for _, ns := range eventNamespaces {
+		if from != "" && from != ns.from {
+			continue
+		}
+		subject := ns.prefix + emitter + ".event." + rest
+		out = append(out, subject, subject+".>")
+	}
+	if out == nil {
+		return nil, fmt.Errorf("from %q is none of %s, %s or %s", from, fromSeat, fromModule, fromStream)
+	}
+	return out, nil
+}
+
+// EventName is the inverse of EventSubjects for a heard subject: for `mesh.seat.<emitter>.event.<rest>`,
+// `mesh.mod.<emitter>.event.<rest>` or `mesh.stream.<emitter>.event.<rest>` it answers the name `<emitter>.<rest>` and
+// its namespace (`seat`, `module` or `stream`); any other subject is answered as not an event (ok false).
+func EventName(subject string) (name, from string, ok bool) {
+	for _, ns := range eventNamespaces {
+		after, found := strings.CutPrefix(subject, ns.prefix)
+		if !found {
+			continue
+		}
+		emitter, rest, found := strings.Cut(after, ".event.")
+		if !found || emitter == "" || rest == "" || strings.Contains(emitter, ".") {
+			return "", "", false
+		}
+		return emitter + "." + rest, ns.from, true
+	}
+	return "", "", false
+}
+
+// Overlaps says whether some subject matches both a and b, a wildcard on either side: `*` stands for one token and
+// `>`, last, for one token or more (design 34 every-event §34).
+func Overlaps(a, b string) bool {
+	at, bt := strings.Split(a, "."), strings.Split(b, ".")
+	for i := 0; ; i++ {
+		switch {
+		case i == len(at) && i == len(bt):
+			return true
+		case i == len(at) || i == len(bt):
+			return false
+		case at[i] == ">" || bt[i] == ">":
+			return true
+		case at[i] == "*" || bt[i] == "*" || at[i] == bt[i]:
+			continue
+		default:
+			return false
+		}
+	}
+}

go/buscompose/events_test.go

@@ -0,0 +1,98 @@
+package buscompose
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// The mesh's event subjects are named in one place: EveryEvent, EventSubjects, EventName and Overlaps (design 34
+// every-event §1, §25, §26, §34, §37).
+func TestTheEventSubjectsAreNamedInOnePlace(t *testing.T) {
+	// EE-S1/AC1 (E §1, §25): the three subjects, in order.
+	if got, want := EveryEvent(), []string{"mesh.seat.*.event.>", "mesh.mod.*.event.>", "mesh.stream.*.event.>"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("EveryEvent is %v, want %v", got, want)
+	}
+
+	// EE-S1/AC2, AC3 (E §1, §26): a name's subjects, all six or one namespace's two, and the refusals naming the rule.
+	subjects := []struct {
+		name, from string
+		want       []string
+		refused    string
+	}{
+		{name: "operator-channel.decided.claude-code", want: []string{
+			"mesh.seat.operator-channel.event.decided.claude-code", "mesh.seat.operator-channel.event.decided.claude-code.>",
+			"mesh.mod.operator-channel.event.decided.claude-code", "mesh.mod.operator-channel.event.decided.claude-code.>",
+			"mesh.stream.operator-channel.event.decided.claude-code", "mesh.stream.operator-channel.event.decided.claude-code.>",
+		}},
+		{name: "mesh-delivery-view.delivered", from: "seat", want: []string{
+			"mesh.seat.mesh-delivery-view.event.delivered", "mesh.seat.mesh-delivery-view.event.delivered.>"}},
+		{name: "mesh-delivery-view.delivered", from: "module", want: []string{
+			"mesh.mod.mesh-delivery-view.event.delivered", "mesh.mod.mesh-delivery-view.event.delivered.>"}},
+		{name: "mesh-mail.mail", from: "stream", want: []string{
+			"mesh.stream.mesh-mail.event.mail", "mesh.stream.mesh-mail.event.mail.>"}},
+		{name: "mesh-delivery-view", refused: "fewer than two tokens"},
+		{name: "mesh-delivery-view..delivered", refused: "[A-Za-z0-9_-]+"},
+		{name: "mesh-delivery-view.*", refused: "[A-Za-z0-9_-]+"},
+		{name: "mesh-delivery-view.>", refused: "[A-Za-z0-9_-]+"},
+		{name: "mesh-delivery-view.delivered", from: "bench", refused: "none of seat, module or stream"},
+	}
+	for _, c := range subjects {
+		got, err := EventSubjects(c.name, c.from)
+		if c.refused != "" {
+			if err == nil || !strings.Contains(err.Error(), c.refused) {
+				t.Errorf("EventSubjects(%q, %q) answered %v, %v; want refused naming %q", c.name, c.from, got, err, c.refused)
+			}
+			continue
+		}
+		if err != nil || !reflect.DeepEqual(got, c.want) {
+			t.Errorf("EventSubjects(%q, %q) answered %v, %v; want %v", c.name, c.from, got, err, c.want)
+		}
+		// EE-S1/AC5 (E §1): every subject it answers is covered by one of EveryEvent's.
+		for _, s := range got {
+			covered := false
+			for _, e := range EveryEvent() {
+				covered = covered || Overlaps(e, s)
+			}
+			if !covered {
+				t.Errorf("%s is covered by none of EveryEvent", s)
+			}
+		}
+	}
+
+	// EE-S1/AC4 (E §1, §26): a heard subject's name and namespace, and any other subject not an event.
+	names := []struct{ subject, name, from string }{
+		{"mesh.seat.operator-channel.event.decided.claude-code", "operator-channel.decided.claude-code", "seat"},
+		{"mesh.mod.mesh-delivery-view.event.delivered", "mesh-delivery-view.delivered", "module"},
+		{"mesh.stream.mesh-delivery-checker.event.verdict", "mesh-delivery-checker.verdict", "stream"},
+		{"mesh.seat.intake.call.accept.ace", "", ""},
+		{"mesh.mod.netcheck.call.netcheck_dns", "", ""},
+		{"$KV.views.x", "", ""},
+		{"mesh.seat..event.x", "", ""},
+	}
+	for _, c := range names {
+		name, from, ok := EventName(c.subject)
+		if name != c.name || from != c.from || ok != (c.name != "") {
+			t.Errorf("EventName(%q) answered %q, %q, %v; want %q, %q", c.subject, name, from, ok, c.name, c.from)
+		}
+	}
+
+	// EE-S1/AC6 (E §34, §37): overlapping subjects, a wildcard on either side.
+	overlaps := []struct {
+		a, b string
+		want bool
+	}{
+		{"mesh.stream.mail.event.mail.>", "mesh.stream.mail.event.mail.*.message", true},
+		{"mesh.mod.mail.event.x", "mesh.stream.mail.event.x", false},
+		{"mesh.mod.mail.event.x.>", "mesh.mod.mail.event.x", false},
+		{"mesh.mod.mail.event.*", "mesh.mod.*.event.x", true},
+		{"mesh.mod.mail.event.x", "mesh.mod.mail.event.x", true},
+		{"mesh.mod.*.event.>", "mesh.mod.mail.event.x.ace", true},
+		{"mesh.mod.mail.event.x.ace", "mesh.mod.mail.event.x", false},
+	}
+	for _, c := range overlaps {
+		if Overlaps(c.a, c.b) != c.want || Overlaps(c.b, c.a) != c.want {
+			t.Errorf("Overlaps(%q, %q) is not %v both ways", c.a, c.b, c.want)
+		}
+	}
+}

go/buscompose/modstreams.go

@@ -3,6 +3,7 @@ package buscompose
 import (
 	"fmt"
 	"sort"
+	"strings"
 )
 
 // moduleStreamPrefix starts every subject a module's own stream takes.
@@ -14,6 +15,19 @@ func ModuleStreamSubject(module, event string) string {
 	return moduleStreamPrefix + module + ".event." + event
 }
 
+// WirePattern is a stream's local event pattern as the bus spells it: `**` is `>`, `*` stays `*`. A reader turns a
+// stream's events into the bus's subjects with it (design 46 7-approval-mark §5): the grants part composing a stream, and
+// the tool runner deriving a restricted stream's marked subjects.
+func WirePattern(local string) string {
+	parts := strings.Split(local, ".")
+	for i, p := range parts {
+		if p == "**" {
+			parts[i] = ">"
+		}
+	}
+	return strings.Join(parts, ".")
+}
+
 // A ModuleStream is one module's declared stream as the bus holds it.
 type ModuleStream struct {
 	Module string

go/buscompose/names_test.go

@@ -29,6 +29,20 @@ func TestTheBusNamesAgree(t *testing.T) {
 	if got := (Principal{Kind: KindLedger, Node: "a", Module: "m"}).Username(); got != "ledger.a.m" {
 		t.Fatalf("a ledger account is named %q", got)
 	}
+	// G §469: a state's bucket is capped at its max-mib; naming none is unbounded.
+	if (Bucket{}).MaxBytes() != -1 || (Bucket{MaxMiB: 2}).MaxBytes() != 2<<20 {
+		t.Fatal("a bucket's cap is not its max-mib in bytes")
+	}
+	// Design 46 7-approval-mark §5: a stream's local event pattern as the bus spells it.
+	for local, wire := range map[string]string{"mail.**": "mail.>", "mail.*.message": "mail.*.message", "sent": "sent"} {
+		if got := WirePattern(local); got != wire {
+			t.Errorf("WirePattern(%q) = %q, want %q", local, got, wire)
+		}
+	}
+	// Design 46 7-approval-mark §13: a per-machine state reaches its machine's key and the keys below it, no other machine's.
+	if got := PerMachineKeys("ace"); len(got) != 2 || got[0] != "ace" || got[1] != "ace.>" {
+		t.Errorf("a per-machine state reaches %v on ace", got)
+	}
 	// A seat's family is the shared events stream filtered to its subjects: a definition says the stream's age.
 	for _, st := range MeshStreams() {
 		if st.Name == EventsStream && int64(st.MaxAge) != seatdef.SharedEventsMaxAgeDays*24*60*60 {

go/buscompose/nats.go

@@ -163,8 +163,8 @@ type Principal struct {
 	// instances and read by whoever declares it.
 	State []string
 	Reads []string
-	// PerMachine is the local names of its state keyed by machine, reaching the key named for Node and
-	// no other; KeyedReads the keys of others' state it reads one key at a time (novox/hq ADR 0260).
+	// PerMachine is the local names of its state keyed by machine, reaching the keys of Node (PerMachineKeys) and
+	// no other machine's; KeyedReads the keys of others' state it reads one key at a time (novox/hq ADR 0260).
 	PerMachine []string
 	KeyedReads []KeyedRead
 	// Logs is the local names of the logs this principal's module keeps (novox/hq ADR 0297).

go/buscompose/state.go

@@ -18,14 +18,29 @@ type Bucket struct {
 	History int
 	// TTLSeconds is how long a value lives; zero is until replaced or deleted.
 	TTLSeconds int
-	// PerMachine says each machine's instance writes only the key named for its machine (novox/hq ADR
-	// 0260), and is granted that key and no other.
+	// PerMachine says each machine's instance writes only the keys of its machine (novox/hq ADR 0260; design 46
+	// 7-approval-mark §13): the key named for its machine and the keys below it, PerMachineKeys, and no other machine's.
 	PerMachine bool
 	// KeyTTL says the bucket allows a time to live per key (novox/hq ADR 0433 §1): its owner writes each key with its
 	// own, and the server writes a delete marker, kept KeyTTLMarkerTTL, when it ends.
 	KeyTTL bool
+	// MaxMiB is the bucket's cap in MiB (design 47 G §469); zero is no cap.
+	MaxMiB int
 }
 
+// MaxBytes is the bucket's cap in bytes as the bus's maximum size: -1, unbounded, where it names none.
+func (b Bucket) MaxBytes() int64 {
+	if b.MaxMiB <= 0 {
+		return -1
+	}
+	return int64(b.MaxMiB) * 1024 * 1024
+}
+
+// PerMachineKeys are the keys a machine's instance of a per-machine state reaches (design 46 7-approval-mark §13): the key
+// named for its machine, as every module's per-machine key keeps its form, and the keys below it, `<node>.>`; no other
+// machine's. A membership's per-machine state (membership.StateIssued's Key) reaches the same.
+func PerMachineKeys(node string) []string { return []string{node, node + ".>"} }
+
 // BucketName is the bucket a module's state lives in: the module and the local name joined by an
 // underscore, which neither may contain, so two modules can never derive one bucket.
 func BucketName(module, name string) string { return module + "_" + name }

go/buscompose/users.go

@@ -22,9 +22,6 @@ type Declared struct {
 	Watches []Seat
 	// Invokes are the tools it calls, `<module>.<tool>` or `*` (novox/hq ADR 0152).
 	Invokes []string
-	// Waits are the event families a session may wait on through the tool runner, the tool runner's module's
-	// alone (novox/hq ADR 0367 §2): its account subscribes them for a call, through no consumer.
-	Waits []Wait
 	// State is the state it keeps, each a bucket its instances write (novox/hq ADR 0201).
 	State []Bucket
 	// Logs are the logs it keeps, each a stream its instances append to (novox/hq ADR 0297).

go/buscompose/waits.go

@@ -1,18 +0,0 @@
-package buscompose
-
-// Wait is one event family the tool runner's module declares: its name as the manifest gives it, and the
-// emitter — a seat or a module — and the event, as the inventory resolved them.
-type Wait struct {
-	// Name is the family as the manifest names it, `<emitter>.<event>`: what a session asks for.
-	Name    string
-	Emitter string
-	// Seat says the emitter is a seat, whose events live under the seat's namespace (novox/hq ADR 0121).
-	Seat bool
-	// Event is the event, with any further token the subject carries: `decided.claude-code`, the asker of a
-	// seat that names it last (ADR 0259 §3).
-	Event string
-	// Last names what the seat's event subject ends in — "kind" for a kinded bench, "asker" for a seat naming
-	// its caller (ADR 0259 §3) — and is empty for an event that ends at its name. A family needing it is waited
-	// on with it given, and refused without.
-	Last string
-}