novox/mesh-contracts
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SD-M2a: mesh-broker's Held says the entry's state and why, so show says why an entry is in its state

Browse Source 
Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
This commit is contained in:
jschoubben
2026-11-04 13:15:18 +01:00
parent b5db9466c2
commit 323e6a6be2
5 changed files with 126 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
go/seats/meshbroker/contract.go
+4
View File
@@ -125,10 +125,14 @@ type Held struct {
Options map[string]any `json:"options,omitempty"`
// the settings the bus holds
Settings map[string]any `json:"settings,omitempty"`
// the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)
State string `json:"state,omitempty"`
// how the bus keeps it
StorageType string `json:"storage-type"`
// its template; empty for a configuration of its own
Template string `json:"template,omitempty"`
// why it is in its state, in plain words; empty when held as asked
Why string `json:"why,omitempty"`
}
// Named is a type of the contract.
go/seats/seats.go
+6 -6
View File
@@ -146,25 +146,25 @@ func List() []Seat {
Serves: []Verb{
{Name: "list", Description: "Every entry the bus module created, its template, its settings and its fill against its cap.", Optional: true,
Input: map[string]any{"properties": map[string]any{"module": map[string]any{"description": "one module (optional)", "type": "string"}}, "type": "object"},
Output: map[string]any{"properties": map[string]any{"entries": map[string]any{"description": "every entry", "items": map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}, "type": "array"}}, "required": []string{"entries"}, "type": "object"}},
Output: map[string]any{"properties": map[string]any{"entries": map[string]any{"description": "every entry", "items": map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}, "type": "array"}}, "required": []string{"entries"}, "type": "object"}},
{Name: "show", Description: "One entry, its template, settings and fill.", Optional: true,
Input: map[string]any{"properties": map[string]any{"local-name": map[string]any{"description": "the entry's local name", "type": "string"}, "module": map[string]any{"description": "the module", "type": "string"}}, "required": []string{"module", "local-name"}, "type": "object"},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
{Name: "check", Description: "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", Optional: true,
Input: map[string]any{"properties": map[string]any{"module": map[string]any{"description": "one module (optional)", "type": "string"}}, "type": "object"},
Output: map[string]any{"properties": map[string]any{"differences": map[string]any{"description": "every difference", "items": map[string]any{"properties": map[string]any{"asked": map[string]any{"description": "asked", "type": "object"}, "grows": map[string]any{"description": "the difference only grows: apply may act on it", "type": "boolean"}, "held": map[string]any{"description": "held", "type": "object"}, "local-name": map[string]any{"description": "the entry", "type": "string"}, "module": map[string]any{"description": "the module", "type": "string"}}, "required": []string{"module", "local-name"}, "type": "object"}, "type": "array"}}, "required": []string{"differences"}, "type": "object"}},
{Name: "orphans", Description: "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", Optional: true,
Input: map[string]any{"description": "no arguments", "properties": map[string]any{}, "type": "object"},
Output: map[string]any{"properties": map[string]any{"entries": map[string]any{"description": "every orphan", "items": map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}, "type": "array"}}, "required": []string{"entries"}, "type": "object"}},
Output: map[string]any{"properties": map[string]any{"entries": map[string]any{"description": "every orphan", "items": map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}, "type": "array"}}, "required": []string{"entries"}, "type": "object"}},
{Name: "create", Description: "Create one entry now.", Optional: true,
Input: map[string]any{"description": "one piece of bus state as a manifest asks it", "properties": map[string]any{"configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type"}, "type": "object"},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
{Name: "apply", Description: "Apply a difference that only grows: a larger cap, a longer age.", Optional: true,
Input: map[string]any{"properties": map[string]any{"local-name": map[string]any{"description": "the entry's local name", "type": "string"}, "module": map[string]any{"description": "the module", "type": "string"}}, "required": []string{"module", "local-name"}, "type": "object"},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
{Name: "recreate", Description: "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", Optional: true,
Input: map[string]any{"properties": map[string]any{"local-name": map[string]any{"description": "the entry's local name", "type": "string"}, "module": map[string]any{"description": "the module", "type": "string"}, "warrant": map[string]any{"description": "the operator's warrant, as the operator channel decided it (ADR 0259 §6)", "type": "string"}, "why": map[string]any{"description": "why, kept in the record", "type": "string"}}, "required": []string{"module", "local-name", "warrant", "why"}, "type": "object"},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
Output: map[string]any{"description": "one entry as the bus holds it", "properties": map[string]any{"bus-name": map[string]any{"description": "its name on the bus, <module>_<local name>", "type": "string"}, "configuration": map[string]any{"description": "its own configuration, where no template fits", "type": "object"}, "fill": map[string]any{"properties": map[string]any{"bytes": map[string]any{"description": "bytes held", "type": "integer"}, "cap": map[string]any{"description": "its cap in bytes", "type": "integer"}, "count": map[string]any{"description": "messages, keys or objects held", "type": "integer"}}, "required": []string{"count", "bytes", "cap"}, "type": "object"}, "local-name": map[string]any{"description": "its local name in the module's manifest", "type": "string"}, "module": map[string]any{"description": "the module asking it", "type": "string"}, "options": map[string]any{"description": "the template's options the module set, within their bounds", "type": "object"}, "settings": map[string]any{"description": "the settings the bus holds", "type": "object"}, "state": map[string]any{"description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)", "enum": []string{"held", "refused", "waiting", "drifted", "full", "orphaned"}, "type": "string"}, "storage-type": map[string]any{"description": "how the bus keeps it", "enum": []string{"stream", "key-value", "object-store", "ledger"}, "type": "string"}, "template": map[string]any{"description": "its template; empty for a configuration of its own", "enum": []string{"state", "events", "work-queue", "log", "objects", "ledger", ""}, "type": "string"}, "why": map[string]any{"description": "why it is in its state, in plain words; empty when held as asked", "type": "string"}}, "required": []string{"module", "local-name", "storage-type", "bus-name"}, "type": "object"}},
{Name: "drop", Description: "Remove one orphan, after a stream snapshot.", Optional: true,
Input: map[string]any{"properties": map[string]any{"local-name": map[string]any{"description": "the entry's local name", "type": "string"}, "module": map[string]any{"description": "the module", "type": "string"}, "warrant": map[string]any{"description": "the operator's warrant, as the operator channel decided it (ADR 0259 §6)", "type": "string"}, "why": map[string]any{"description": "why, kept in the record", "type": "string"}}, "required": []string{"module", "local-name", "warrant", "why"}, "type": "object"},
Output: map[string]any{"properties": map[string]any{"dropped": map[string]any{"description": "it is gone", "type": "boolean"}, "snapshot": map[string]any{"description": "the snapshot taken first", "type": "string"}}, "required": []string{"dropped"}, "type": "object"}},