Add mesh-knowledge, the knowledge base's first slice (hq issue 425, ADR 0290)

An agent learns what a decision says only by reading whole records. This module
holds every decision record and research effort whole in a database in the store,
with clauses that carry their own status and source, typed links read from both
ends, and every version. It answers ask, get and holds within a stated bound, and
takes a record through reserve, propose (refused on any of the 29 per-record
rules), review by someone other than the author, and acceptance, on the
operator's proven warrant when the record needs it. The 4 whole-set rules make
the module unhealthy when they fail. The import reads hq at a commit through the
records module, never overwrites, and changes nothing when run again. Prose
decisions get drafted clauses that a second judgement must confirm before they
are served.

modules/mesh-knowledge/cmd/mesh-knowledge/bound_test.go

@@ -0,0 +1,132 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// to-be 55 §10: "An answer stays within its bound — the module's test over the full import of main at a recorded
+// commit (testdata/hq-main.commit): every ask, get and holds of a fixed question list."
+
+var questions = []string{
+	"what holds about the merge window, and why",
+	"how is a module's health judged",
+	"who hands out decision numbers",
+	"what is a seat",
+	"can the mesh create a symlink",
+	"how does a node reach the bus",
+	"how are secrets kept",
+	"what does the operator approve and on which channel",
+	"what is the knowledge base",
+	"how is a delivery walked across the nodes",
+	"what does the firewall allow",
+	"the",
+	"zebra quantum",
+}
+
+func TestEveryAnswerStaysWithinItsBoundOverTheWholeOfMain(t *testing.T) {
+	eachStore(t, func(t *testing.T, s Store) {
+		w := newWorld(t, s, hqMain(t))
+		if _, err := w.k.Import("import@test", ImportAsk{}, hqMain(t)); err != nil {
+			t.Fatal(err)
+		}
+		// Draft and confirm a few prose records, so drafted and confirmed clauses are in the answers too.
+		for i := 0; i < 12; i++ {
+			if _, err := w.k.DraftStep(); err != nil {
+				t.Fatal(err)
+			}
+		}
+		within := func(what string, v any, bound int) {
+			t.Helper()
+			raw, _ := json.Marshal(v)
+			if len(raw) > bound {
+				t.Errorf("%s: %d bytes, over its bound of %d", what, len(raw), bound)
+			}
+		}
+		cuts := 0
+		for _, q := range questions {
+			for _, bound := range []int{0, 2048, 16 << 10} {
+				a, err := w.k.Ask(q, bound)
+				if err != nil {
+					t.Fatalf("%q: %v", q, err)
+				}
+				within("ask "+q, a, boundOf(bound))
+				if a.Cut != "" {
+					cuts++
+				}
+			}
+		}
+		if cuts == 0 {
+			t.Error("no answer was cut: the bound was never tested")
+		}
+		all, _ := s.All(t.Context())
+		topics := map[string]bool{}
+		for _, e := range all {
+			k := e.Current.Key()
+			for _, get := range []GetAsk{{Kind: k.Kind, Number: k.Number}, {Kind: k.Kind, Number: k.Number, Reasoning: true}} {
+				g, err := w.k.Get(get)
+				if err != nil {
+					t.Fatalf("get %s: %v", k, err)
+				}
+				within("get "+k.String(), g, DefaultBound)
+				if get.Reasoning && len(g.Sections) > 0 && g.Cut == "" && len(g.Reasoning) < len(g.Sections) {
+					t.Errorf("get %s left out reasoning without saying so", k)
+				}
+			}
+			h, err := w.k.Holds("", &k, 0)
+			if err != nil {
+				t.Fatal(err)
+			}
+			within("holds "+k.String(), h, DefaultBound)
+			topics[e.Current.Topic] = true
+		}
+		for topic := range topics {
+			h, err := w.k.Holds(topic, nil, 0)
+			if err != nil {
+				t.Fatal(err)
+			}
+			within("holds "+topic, h, DefaultBound)
+		}
+	})
+}
+
+// The acceptance sentence, over the whole of main: "what holds about the merge window, and why" answers, in one
+// call under 4 KiB, the clauses in force of the record that decided it, what changed them since, and how to read
+// its reasoning.
+func TestTheMergeWindowQuestionIsAnsweredInOneCallUnderFourKiB(t *testing.T) {
+	eachStore(t, func(t *testing.T, s Store) {
+		w := newWorld(t, s, hqMain(t))
+		if _, err := w.k.Import("import@test", ImportAsk{}, hqMain(t)); err != nil {
+			t.Fatal(err)
+		}
+		a, err := w.k.Ask("what holds about the merge window, and why", 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, _ := json.Marshal(a)
+		if len(raw) > 4096 || len(a.Records) == 0 {
+			t.Fatalf("%d bytes, %d records", len(raw), len(a.Records))
+		}
+		var r276 *AnswerRecord
+		for i, r := range a.Records[:min(3, len(a.Records))] {
+			if r.Record == "ADR 0276" {
+				r276 = &a.Records[i]
+			}
+		}
+		if r276 == nil {
+			t.Fatalf("ADR 0276 is not among the first three: %s", raw)
+		}
+		if len(r276.Clauses) == 0 || !strings.Contains(r276.Clauses[0].Holds, "in force") || !strings.Contains(r276.Read, "reasoning") {
+			t.Fatalf("0276 as answered: %+v", r276)
+		}
+		changed := false
+		for _, s := range r276.Since {
+			changed = changed || strings.Contains(s, "ADR 0282")
+		}
+		if !changed {
+			t.Fatalf("what changed 0276 since is not said: %+v", r276.Since)
+		}
+		t.Logf("%d bytes: %s", len(raw), raw)
+	})
+}