Merge origin/main (#5): mesh-broker's Binding is the wire form; restore-kept and snapshot-kept taken out, the binding names its objects

The conflicts in mesh-broker's seat.json and fixtures took origin/main's Binding (list, show and orphans answer each
binding) and the objects field of C8; C8's snapshot-kept, restore-kept, KeptPoint and Aside are not carried over as G
section 555 moves them to the seat mesh-recovery, which mesh-broker does not gain. The generated Go and TypeScript of
mesh-broker are written again by seatgen.

Builds: design 47 G §399, §513, §555

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-11 14:40:11 +01:00
7 changed files with 222 additions and 577 deletions
+34 -134
View File
@@ -3,22 +3,18 @@
// Package meshbroker is the contract of the seat "mesh-broker", defined whole (seats/mesh-broker/seat.json): The mesh's bus, and the bus state modules ask of it in requires (design 25 § 12). create, apply, recreate and drop are granted to the bus module's own credential alone.
package meshbroker
import "time"
// Seat is the seat's name.
const Seat = "mesh-broker"
const (
VerbList = "list"
VerbShow = "show"
VerbCheck = "check"
VerbOrphans = "orphans"
VerbCreate = "create"
VerbApply = "apply"
VerbRecreate = "recreate"
VerbDrop = "drop"
VerbSnapshotKept = "snapshot-kept"
VerbRestoreKept = "restore-kept"
VerbList = "list"
VerbShow = "show"
VerbCheck = "check"
VerbOrphans = "orphans"
VerbCreate = "create"
VerbApply = "apply"
VerbRecreate = "recreate"
VerbDrop = "drop"
)
const (
@@ -35,7 +31,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop, VerbSnapshotKept, VerbRestoreKept}
return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -76,36 +72,34 @@ const SubjectRecreated = "mesh.seat.mesh-broker.event.recreated"
// SubjectDropped is where dropped is published.
const SubjectDropped = "mesh.seat.mesh-broker.event.dropped"
// Aside is live kept data a restore set aside, never removed but by discard-aside.
type Aside struct {
// when it was set aside
At *time.Time `json:"at,omitempty"`
// the form it held
Form int64 `json:"form,omitempty"`
// its id, for discard-aside
ID string `json:"id"`
// the kept data
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// the name it is kept under on the bus
Name string `json:"name"`
// its size in bytes
Size int64 `json:"size,omitempty"`
}
// Binding is the binding a module receives in its membership for one entry (ADR 0595 §1, §7).
// Binding is the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership.
type Binding struct {
// the entry's name on the bus
BusName string `json:"bus-name"`
// a key-value bucket's name
Bucket string `json:"bucket,omitempty"`
// a ledger's history stream
History string `json:"history,omitempty"`
// a ledger's index buckets, by index name
Indexes map[string]string `json:"indexes,omitempty"`
// the entry's local name in the module's manifest
Local string `json:"local"`
// an object store's name
ObjectStore string `json:"object-store,omitempty"`
// the bus name of the state's <state>-objects, where its large values go (design 47 G 58, 399)
Objects string `json:"objects,omitempty"`
// how the bus keeps it
StorageType string `json:"storage-type"`
// its subjects, for a stream
Subjects []string `json:"subjects,omitempty"`
// the subject of a ledger's instances' snapshots
Snapshot string `json:"snapshot,omitempty"`
// a ledger's state bucket
State string `json:"state,omitempty"`
// how the bus keeps it: the entry's storage type
Storage string `json:"storage"`
// a stream's name on the bus
Stream string `json:"stream,omitempty"`
// the subject a stream's messages are on; also a ledger's history's
Subject string `json:"subject,omitempty"`
// its template
Template string `json:"template,omitempty"`
// a ledger's types, as its manifest declares them
Types []map[string]any `json:"types,omitempty"`
}
// Entry is one piece of bus state as a manifest asks it.
@@ -155,6 +149,8 @@ type Fill struct {
// Held is one entry as the bus holds it.
type Held struct {
// the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)
Binding *Binding `json:"binding,omitempty"`
// its name on the bus, <module>_<local name>
BusName string `json:"bus-name"`
// its own configuration, where no template fits
@@ -207,44 +203,6 @@ const (
HeldTemplate = ""
)
// KeptPointCatchUp is the catch-up tool and its arguments the restore point records (design 47 G 406).
type KeptPointCatchUp struct {
Arguments map[string]any `json:"arguments,omitempty"`
Tool string `json:"tool"`
}
// KeptPointConsumersItem is a type of the contract.
type KeptPointConsumersItem struct {
// the durable consumer
Consumer string `json:"consumer"`
// its acknowledged position
Sequence int64 `json:"sequence"`
// the stream
Stream string `json:"stream"`
}
// KeptPoint is a restore point of one module's kept data on the bus, whole, with its consumers' positions.
type KeptPoint struct {
// when it was taken
At *time.Time `json:"at,omitempty"`
// the catch-up tool and its arguments the restore point records (design 47 G 406)
CatchUp *KeptPointCatchUp `json:"catch-up,omitempty"`
// each durable consumer the module reads with, and its position
Consumers []KeptPointConsumersItem `json:"consumers,omitempty"`
// the fingerprint the restore point is taken before
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// its size in bytes
Size int64 `json:"size,omitempty"`
// the restore point's name
Snapshot string `json:"snapshot"`
}
// Named is a type of the contract.
type Named struct {
// the entry's local name
@@ -397,64 +355,6 @@ type DropAnswer struct {
Snapshot string `json:"snapshot,omitempty"`
}
// SnapshotKeptInputCatchUp is the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406).
type SnapshotKeptInputCatchUp struct {
Arguments map[string]any `json:"arguments,omitempty"`
Tool string `json:"tool"`
}
// SnapshotKeptInput is what snapshot-kept takes.
type SnapshotKeptInput struct {
// the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406)
CatchUp *SnapshotKeptInputCatchUp `json:"catch-up,omitempty"`
// the fingerprint the restore point is taken before
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// why it is taken
Why string `json:"why,omitempty"`
}
// SnapshotKeptAnswer is what snapshot-kept answers.
type SnapshotKeptAnswer struct {
// why it failed; set alone
Error string `json:"error,omitempty"`
Point *KeptPoint `json:"point,omitempty"`
}
// RestoreKeptInput is what restore-kept takes.
type RestoreKeptInput struct {
// set the live data aside and restore nothing
AsideOnly bool `json:"aside-only,omitempty"`
// the name of data set aside: remove it and restore nothing
DiscardAside string `json:"discard-aside,omitempty"`
// the fingerprint the restore point is taken before
Fingerprint string `json:"fingerprint"`
// its form, the number the holder raises when it changes how it writes it (0 when undeclared)
Form int64 `json:"form"`
// the kept data, its local name in the module's manifest
Kept string `json:"kept"`
// the module
Module string `json:"module"`
// the restore point's name; not with aside-only or discard-aside
Snapshot string `json:"snapshot,omitempty"`
// why
Why string `json:"why,omitempty"`
}
// RestoreKeptAnswer is what restore-kept answers.
type RestoreKeptAnswer struct {
Aside *Aside `json:"aside,omitempty"`
// why it failed; set alone
Error string `json:"error,omitempty"`
// the restore point is the live data now
Restored bool `json:"restored,omitempty"`
}
// CreatedEvent is the body of the event created.
type CreatedEvent = Said
+4 -6
View File
@@ -19,6 +19,8 @@ func TestFixtures(t *testing.T) {
}{
{name: "created on the seat's subject", subject: "mesh.seat.mesh-broker.event.created", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\"}",
decode: func(b []byte) (any, error) { var v CreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.created$")},
{name: "created with a ledger's binding as the bus module writes it", subject: "mesh.seat.mesh-broker.event.created", given: "{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"revision\":7,\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"revision\":7,\"storage-type\":\"ledger\",\"template\":\"ledger\"}",
decode: func(b []byte) (any, error) { var v CreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.created$")},
{name: "refused on the seat's subject", subject: "mesh.seat.mesh-broker.event.refused", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.refused$")},
{name: "drifted on the seat's subject", subject: "mesh.seat.mesh-broker.event.drifted", given: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}", wire: "{\"asked\":{\"max-mib\":64},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"held\":{\"max-mib\":64},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"storage-type\":\"ledger\",\"template\":\"ledger\",\"why\":\"the bus refused it\"}",
@@ -41,12 +43,8 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers every entry", subject: "", given: "{\"entries\":[{\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}", wire: "{\"entries\":[{\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-kept answers the restore point", subject: "", given: "{\"point\":{\"at\":\"2026-11-09T20:00:00Z\",\"consumers\":[{\"consumer\":\"novox_mesh-delivery-indexer\",\"sequence\":4711,\"stream\":\"forge\"}],\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"form\":1,\"kept\":\"catalog-revisions\",\"module\":\"mesh-delivery-indexer\",\"size\":1048576,\"snapshot\":\"kept-mesh-delivery-indexer-catalog-revisions-1-aaaa\"}}", wire: "{\"point\":{\"at\":\"2026-11-09T20:00:00Z\",\"consumers\":[{\"consumer\":\"novox_mesh-delivery-indexer\",\"sequence\":4711,\"stream\":\"forge\"}],\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"form\":1,\"kept\":\"catalog-revisions\",\"module\":\"mesh-delivery-indexer\",\"size\":1048576,\"snapshot\":\"kept-mesh-delivery-indexer-catalog-revisions-1-aaaa\"}}",
decode: func(b []byte) (any, error) { var v SnapshotKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "snapshot-kept answers an error", subject: "", given: "{\"error\":\"the object store catalog-revisions is not on the bus\"}", wire: "{\"error\":\"the object store catalog-revisions is not on the bus\"}",
decode: func(b []byte) (any, error) { var v SnapshotKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "restore-kept answers what it set aside", subject: "", given: "{\"aside\":{\"at\":\"2026-11-09T21:00:00Z\",\"form\":2,\"id\":\"aside-1\",\"kept\":\"catalog-revisions\",\"module\":\"mesh-delivery-indexer\",\"name\":\"catalog-revisions-aside-20261109\",\"size\":2097152},\"restored\":true}", wire: "{\"aside\":{\"at\":\"2026-11-09T21:00:00Z\",\"form\":2,\"id\":\"aside-1\",\"kept\":\"catalog-revisions\",\"module\":\"mesh-delivery-indexer\",\"name\":\"catalog-revisions-aside-20261109\",\"size\":2097152},\"restored\":true}",
decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers the binding of an entry the bus holds", subject: "", given: "{\"entries\":[{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"objects\":\"mesh-knowledge_ledger_state-objects\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}", wire: "{\"entries\":[{\"binding\":{\"history\":\"mesh-knowledge_ledger\",\"indexes\":{\"by-kind\":\"mesh-knowledge_ledger_index-by-kind\"},\"local\":\"ledger\",\"objects\":\"mesh-knowledge_ledger_state-objects\",\"snapshot\":\"mesh.ledger.mesh-knowledge.ledger.snapshot\",\"state\":\"mesh-knowledge_ledger_state\",\"storage\":\"ledger\",\"subject\":\"mesh.ledger.mesh-knowledge.ledger.history\",\"template\":\"ledger\",\"types\":[{\"indexes\":[{\"name\":\"by-kind\",\"on\":[\"kind\"]}],\"name\":\"decision\",\"operations\":[{\"effect\":\"set-fields\",\"fields\":[\"title\",\"kind\"],\"name\":\"set\"}],\"schema\":{\"kind\":{\"type\":\"string\"},\"title\":{\"type\":\"string\"}}}]},\"bus-name\":\"mesh-knowledge_ledger\",\"fill\":{\"bytes\":2048,\"cap\":67108864,\"count\":10},\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"settings\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))