Let a module declare a log the controller creates and never removes (ADR 0297)

The issue tracker's history lasts seven days on the events stream and its
bucket fills toward a cap with no warning (issues 501, 502). A module may
now declare `logs`; the controller creates each as a stream on the bus
(create-or-update, never deleted or recreated, reported when undeclared),
issues it to the owner's assignments in their membership, grants the
runtime exactly the append and direct-read subjects, and raises a
condition when any module's bucket or log reaches 75% of its cap, cleared
below 70%.

internal/catalogue/logs.go

@@ -0,0 +1,105 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+)
+
+// What a module may call its logs (novox/hq ADR 0297).
+//
+// A log is a module's record of operations: entries appended under a key, each kept as long as the
+// log is, in the order they came. A module names each log it owns **locally** — `changes`, never a
+// stream or a subject (ADR 0201 §4) — and the mesh derives the stream from the module and the local
+// name, as it derives a bucket. So the rule for a log's name is a state name's: one plain token, and
+// a module that keeps a log has a name that is one plain token too.
+
+// The mesh's caps on a log, in MiB: what a module may ask, and what it gets when it asks nothing.
+const (
+	LogLeastMiB   = 1
+	LogMostMiB    = 8192
+	LogDefaultMiB = 1024
+)
+
+// LogDeclaration is one log a module owns: its local name, and how large it may grow.
+type LogDeclaration struct {
+	Name string `json:"name"`
+	// MaxMiB is the log's cap in MiB; zero is LogDefaultMiB. When full, the log refuses new entries
+	// and never drops old ones.
+	MaxMiB int `json:"max-mib,omitempty"`
+}
+
+// Cap is the log's cap in MiB, the default where none is said.
+func (l LogDeclaration) Cap() int {
+	if l.MaxMiB == 0 {
+		return LogDefaultMiB
+	}
+	return l.MaxMiB
+}
+
+// UnmarshalJSON reads a log as its bare name, or as {name, max-mib}.
+func (l *LogDeclaration) UnmarshalJSON(raw []byte) error {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) > 0 && trimmed[0] == '"' {
+		return json.Unmarshal(trimmed, &l.Name)
+	}
+	var full struct {
+		Name   string `json:"name"`
+		MaxMiB *int   `json:"max-mib"`
+	}
+	dec := json.NewDecoder(bytes.NewReader(trimmed))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&full); err != nil {
+		return fmt.Errorf("a log is either a name or {name, max-mib}: %w", typedUnknown(err))
+	}
+	l.Name = full.Name
+	l.MaxMiB = 0
+	if full.MaxMiB != nil {
+		// Said, and said as nothing: refused rather than read as the default, which it did not say.
+		if *full.MaxMiB == 0 {
+			return fmt.Errorf("log %q: max-mib is between %d and %d, not 0", full.Name, LogLeastMiB, LogMostMiB)
+		}
+		l.MaxMiB = *full.MaxMiB
+	}
+	return nil
+}
+
+// MarshalJSON writes back the short form when there is nothing else to say.
+func (l LogDeclaration) MarshalJSON() ([]byte, error) {
+	if l.MaxMiB == 0 {
+		return json.Marshal(l.Name)
+	}
+	type plain LogDeclaration
+	return json.Marshal(plain(l))
+}
+
+// LogProblems is what is wrong with a manifest's logs.
+//
+// Refused at registration, for a bucket's reason: a stream name the bus cannot hold, or a cap the
+// mesh would not grant, is a module that installs, starts, and is refused on its first append.
+func LogProblems(m Manifest) []string {
+	var problems []string
+	if len(m.Logs) > 0 && !stateName.MatchString(m.Module) {
+		problems = append(problems, fmt.Sprintf(
+			"%s keeps a log, and a module's name is part of its logs' names, which take one plain "+
+				"name — no dot (novox/hq ADR 0297)", m.Module))
+	}
+	seen := map[string]bool{}
+	for _, l := range m.Logs {
+		switch {
+		case !stateName.MatchString(l.Name):
+			problems = append(problems, fmt.Sprintf(
+				"%s keeps log %q: a log is named locally — lower-case letters, digits and hyphens, "+
+					"no dot and no underscore; the mesh derives the stream (novox/hq ADR 0297)", m.Module, l.Name))
+		case seen[l.Name]:
+			problems = append(problems, fmt.Sprintf("%s keeps log %q twice", m.Module, l.Name))
+		}
+		seen[l.Name] = true
+		if l.MaxMiB != 0 && (l.MaxMiB < LogLeastMiB || l.MaxMiB > LogMostMiB) {
+			problems = append(problems, fmt.Sprintf(
+				"%s caps log %q at %d MiB; a log holds between %d and %d MiB (novox/hq ADR 0297)",
+				m.Module, l.Name, l.MaxMiB, LogLeastMiB, LogMostMiB))
+		}
+	}
+	return problems
+}

internal/catalogue/logs_test.go

@@ -0,0 +1,68 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A module declares the logs it keeps (novox/hq ADR 0297 §1): a log by its bare name, or with its cap
+// in MiB; the default cap where none is said.
+func TestAManifestMaySayWhatLogsItKeeps(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"mesh-issues","version":"1",` +
+		`"logs":["changes",{"name":"moves","max-mib":2048}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(m.Logs) != 2 || m.Logs[0].Name != "changes" || m.Logs[1].Name != "moves" {
+		t.Fatalf("logs not read: %+v", m.Logs)
+	}
+	if m.Logs[0].Cap() != LogDefaultMiB || m.Logs[0].Cap() != 1024 || m.Logs[1].Cap() != 2048 {
+		t.Fatalf("caps read as %d and %d", m.Logs[0].Cap(), m.Logs[1].Cap())
+	}
+	out, _ := json.Marshal(m.Logs)
+	if string(out) != `["changes",{"name":"moves","max-mib":2048}]` {
+		t.Fatalf("written back as %s", out)
+	}
+	for _, edge := range []string{`{"name":"a","max-mib":1}`, `{"name":"a","max-mib":8192}`} {
+		if _, err := ParseManifest([]byte(`{"module":"a","version":"1","logs":[` + edge + `]}`)); err != nil {
+			t.Errorf("%s is inside the caps and was refused: %v", edge, err)
+		}
+	}
+}
+
+// The catalogue check refuses a log outside the caps, with a name that is not one plain token, with a
+// field the mesh does not know, or kept by a module whose own name is not one plain token.
+func TestALogIsNamedLocallyAndCapped(t *testing.T) {
+	for _, c := range []struct{ manifest, says string }{
+		{`{"module":"a","version":"1","logs":["mesh.changes"]}`, `keeps log "mesh.changes": a log is named locally`},
+		{`{"module":"a","version":"1","logs":["my_changes"]}`, `keeps log "my_changes"`},
+		{`{"module":"a","version":"1","logs":["Changes"]}`, `keeps log "Changes"`},
+		{`{"module":"a","version":"1","logs":["c","c"]}`, `keeps log "c" twice`},
+		{`{"module":"a","version":"1","logs":[{"name":"c","max-mib":8193}]}`, `between 1 and 8192 MiB`},
+		{`{"module":"a","version":"1","logs":[{"name":"c","max-mib":-1}]}`, `between 1 and 8192 MiB`},
+		{`{"module":"a","version":"1","logs":[{"name":"c","max-mib":0}]}`, `max-mib is between 1 and 8192, not 0`},
+		{`{"module":"a","version":"1","logs":[{"name":"c","stream":"LOG_x"}]}`, `{name, max-mib}`},
+		{`{"module":"a.b","version":"1","logs":["c"]}`, `no dot`},
+	} {
+		_, err := ParseManifest([]byte(c.manifest))
+		if err == nil {
+			t.Errorf("%s was accepted", c.manifest)
+			continue
+		}
+		if !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s refused for the wrong reason: %v", c.manifest, err)
+		}
+	}
+}
+
+// **Across the whole catalogue**: every log is named locally and capped within the mesh's caps.
+func TestEveryManifestsLogsAreLocalAndCapped(t *testing.T) {
+	var problems []string
+	for _, m := range theCatalogue(t) {
+		problems = append(problems, LogProblems(m)...)
+	}
+	if len(problems) > 0 {
+		t.Fatalf("the catalogue's logs are not what ADR 0297 says:\n  %s", strings.Join(problems, "\n  "))
+	}
+}

internal/catalogue/manifest.go

@@ -465,6 +465,11 @@ type Manifest struct {
 	// (novox/hq ADR 0201). Not history — that is an event — and never a secret, sealed or not.
 	State []StateDeclaration `json:"state,omitempty"`
 
+	// Logs are the logs of operations this module keeps on the bus, by local name: each a stream the
+	// controller creates and never removes, which every instance of the module appends to and reads
+	// (novox/hq ADR 0297). A log is its owner's alone: no other module reads it.
+	Logs []LogDeclaration `json:"logs,omitempty"`
+
 	// Settings are the defaults this module gives its settings (novox/hq ADR 0262): each key a file,
 	// a contribution or a served fact asks for as `${setting:<key>}`, its default, and why that
 	// default. Only a preference has one — a font size, a width, a number of workers — and a value
@@ -1507,7 +1512,7 @@ func ParseManifest(raw []byte) (Manifest, error) {
 			name string
 			n    int
 		}{{"consumes", len(m.Consumes)}, {"uses", len(m.Uses)}, {"invokes", len(m.Invokes)},
-			{"state", len(m.State)}, {"reads", len(m.Reads)}} {
+			{"state", len(m.State)}, {"logs", len(m.Logs)}, {"reads", len(m.Reads)}} {
 			if f.n > 0 {
 				said = append(said, f.name)
 			}
@@ -1618,6 +1623,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	problems = append(problems, EventProblems(m)...)
 	// And what it may call its state, and whose it may read (state.go, novox/hq ADR 0201).
 	problems = append(problems, StateProblems(m)...)
+	// And what it may call its logs, and how large it may ask them to grow (logs.go, novox/hq ADR 0297).
+	problems = append(problems, LogProblems(m)...)
 	// And the defaults it gives its settings (setting_defaults.go, novox/hq ADR 0262).
 	problems = append(problems, SettingProblems(m)...)
 	wellFormed := true