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

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

Browse Source 
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:
jschoubben
2026-11-11 14:40:11 +01:00
parent 9068aac406 5fd0bf86f1
commit a7ab33028f
7 changed files with 222 additions and 577 deletions
Download Patch File Download Diff File Expand all files Collapse all files
go/seats/meshbroker/contract.go
+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
go/seats/meshbroker/contract_test.go
+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))
seats/mesh-broker/fixtures/events.json
+56
View File
@@ -22,6 +22,62 @@
}
}
},
{
"name": "created with a ledger's binding as the bus module writes it",
"of": "event:created",
"subject": "mesh.seat.mesh-broker.event.created",
"given": {
"module": "mesh-knowledge",
"local-name": "ledger",
"storage-type": "ledger",
"template": "ledger",
"bus-name": "mesh-knowledge_ledger",
"binding": {
"local": "ledger",
"storage": "ledger",
"template": "ledger",
"subject": "mesh.ledger.mesh-knowledge.ledger.history",
"history": "mesh-knowledge_ledger",
"state": "mesh-knowledge_ledger_state",
"indexes": {
"by-kind": "mesh-knowledge_ledger_index-by-kind"
},
"snapshot": "mesh.ledger.mesh-knowledge.ledger.snapshot",
"types": [
{
"name": "decision",
"schema": {
"title": {
"type": "string"
},
"kind": {
"type": "string"
}
},
"operations": [
{
"name": "set",
"effect": "set-fields",
"fields": [
"title",
"kind"
]
}
],
"indexes": [
{
"name": "by-kind",
"on": [
"kind"
]
}
]
}
]
},
"revision": 7
}
},
{
"name": "refused on the seat's subject",
"of": "event:refused",
seats/mesh-broker/fixtures/verbs.json
+62 -40
View File
@@ -49,48 +49,70 @@
}
},
{
"name": "snapshot-kept answers the restore point",
"of": "verb:snapshot-kept.answer",
"name": "list answers the binding of an entry the bus holds",
"of": "verb:list.answer",
"given": {
"point": {
"module": "mesh-delivery-indexer",
"kept": "catalog-revisions",
"form": 1,
"fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"snapshot": "kept-mesh-delivery-indexer-catalog-revisions-1-aaaa",
"consumers": [
{
"stream": "forge",
"consumer": "novox_mesh-delivery-indexer",
"sequence": 4711
"entries": [
{
"module": "mesh-knowledge",
"local-name": "ledger",
"storage-type": "ledger",
"template": "ledger",
"bus-name": "mesh-knowledge_ledger",
"settings": {
"max-mib": 64
},
"fill": {
"count": 10,
"bytes": 2048,
"cap": 67108864
},
"binding": {
"local": "ledger",
"storage": "ledger",
"template": "ledger",
"subject": "mesh.ledger.mesh-knowledge.ledger.history",
"history": "mesh-knowledge_ledger",
"state": "mesh-knowledge_ledger_state",
"objects": "mesh-knowledge_ledger_state-objects",
"indexes": {
"by-kind": "mesh-knowledge_ledger_index-by-kind"
},
"snapshot": "mesh.ledger.mesh-knowledge.ledger.snapshot",
"types": [
{
"name": "decision",
"schema": {
"title": {
"type": "string"
},
"kind": {
"type": "string"
}
},
"operations": [
{
"name": "set",
"effect": "set-fields",
"fields": [
"title",
"kind"
]
}
],
"indexes": [
{
"name": "by-kind",
"on": [
"kind"
]
}
]
}
]
}
],
"size": 1048576,
"at": "2026-11-09T20:00:00Z"
}
}
},
{
"name": "snapshot-kept answers an error",
"of": "verb:snapshot-kept.answer",
"given": {
"error": "the object store catalog-revisions is not on the bus"
}
},
{
"name": "restore-kept answers what it set aside",
"of": "verb:restore-kept.answer",
"given": {
"restored": true,
"aside": {
"id": "aside-1",
"module": "mesh-delivery-indexer",
"kept": "catalog-revisions",
"form": 2,
"name": "catalog-revisions-aside-20261109",
"size": 2097152,
"at": "2026-11-09T21:00:00Z"
}
}
]
}
}
]
seats/mesh-broker/seat.json
+41 -273
View File
@@ -212,150 +212,6 @@
},
"optional": true,
"class": "warrant"
},
{
"name": "snapshot-kept",
"description": "Take the restore point of one module's kept data on the bus: the data whole and the position of each durable consumer the module reads with, keyed by the module, the kept data, its form and the fingerprint it is taken before (design 47 *A module's kept data on the bus*).",
"callers": [
"holder:node-backup@same-node"
],
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module",
"minLength": 1
},
"kept": {
"type": "string",
"description": "the kept data, its local name in the module's manifest",
"minLength": 1
},
"form": {
"type": "integer",
"description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)"
},
"fingerprint": {
"type": "string",
"description": "the fingerprint the restore point is taken before",
"minLength": 1
},
"why": {
"type": "string",
"description": "why it is taken"
},
"catch-up": {
"type": "object",
"description": "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)",
"properties": {
"tool": {
"type": "string"
},
"arguments": {
"type": "object"
}
},
"required": [
"tool"
]
}
},
"required": [
"module",
"kept",
"form",
"fingerprint"
],
"additionalProperties": false
},
"answer": {
"type": "object",
"properties": {
"point": {
"$ref": "#/defs/KeptPoint"
},
"error": {
"type": "string",
"description": "why it failed; set alone"
}
},
"description": "the restore point taken, or the error"
},
"class": "act"
},
{
"name": "restore-kept",
"description": "Restore one module's kept data from its restore point beside the live data, never over it: the live data is set aside under a name of its own and the consumers' positions are set back with it. With aside-only it sets the live data aside and restores nothing; with discard-aside, naming data set aside, it removes that data and restores nothing (design 47 G 405).",
"callers": [
"holder:node-backup@same-node"
],
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module",
"minLength": 1
},
"kept": {
"type": "string",
"description": "the kept data, its local name in the module's manifest",
"minLength": 1
},
"form": {
"type": "integer",
"description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)"
},
"fingerprint": {
"type": "string",
"description": "the fingerprint the restore point is taken before",
"minLength": 1
},
"snapshot": {
"type": "string",
"description": "the restore point's name; not with aside-only or discard-aside",
"minLength": 1
},
"why": {
"type": "string",
"description": "why"
},
"aside-only": {
"type": "boolean",
"description": "set the live data aside and restore nothing"
},
"discard-aside": {
"type": "string",
"description": "the name of data set aside: remove it and restore nothing"
}
},
"required": [
"module",
"kept",
"form",
"fingerprint"
],
"additionalProperties": false
},
"answer": {
"type": "object",
"properties": {
"restored": {
"type": "boolean",
"description": "the restore point is the live data now"
},
"aside": {
"$ref": "#/defs/Aside"
},
"error": {
"type": "string",
"description": "why it failed; set alone"
}
},
"description": "what was restored and what was set aside, or the error"
},
"class": "act"
}
],
"events": [
@@ -567,6 +423,10 @@
"why": {
"type": "string",
"description": "why it is in its state, in plain words; empty when held as asked"
},
"binding": {
"$ref": "#/defs/Binding",
"description": "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)"
}
},
"required": [
@@ -704,162 +564,70 @@
"Binding": {
"type": "object",
"properties": {
"bus-name": {
"local": {
"type": "string",
"description": "the entry's name on the bus"
"description": "the entry's local name in the module's manifest"
},
"storage-type": {
"storage": {
"type": "string",
"description": "how the bus keeps it"
"description": "how the bus keeps it: the entry's storage type"
},
"template": {
"type": "string",
"description": "its template"
},
"subjects": {
"type": "array",
"items": {
"type": "string"
},
"description": "its subjects, for a stream"
"stream": {
"type": "string",
"description": "a stream's name on the bus"
},
"subject": {
"type": "string",
"description": "the subject a stream's messages are on; also a ledger's history's"
},
"bucket": {
"type": "string",
"description": "a key-value bucket's name"
},
"object-store": {
"type": "string",
"description": "an object store's name"
},
"objects": {
"type": "string",
"description": "the bus name of the state's <state>-objects, where its large values go (design 47 G 58, 399)"
}
},
"required": [
"bus-name",
"storage-type"
],
"description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)"
},
"KeptPoint": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module",
"minLength": 1
},
"kept": {
"history": {
"type": "string",
"description": "the kept data, its local name in the module's manifest",
"minLength": 1
"description": "a ledger's history stream"
},
"form": {
"type": "integer",
"description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)"
},
"fingerprint": {
"state": {
"type": "string",
"description": "the fingerprint the restore point is taken before",
"minLength": 1
"description": "a ledger's state bucket"
},
"indexes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "a ledger's index buckets, by index name"
},
"snapshot": {
"type": "string",
"description": "the restore point's name"
"description": "the subject of a ledger's instances' snapshots"
},
"consumers": {
"types": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stream": {
"type": "string",
"description": "the stream"
},
"consumer": {
"type": "string",
"description": "the durable consumer"
},
"sequence": {
"type": "integer",
"description": "its acknowledged position"
}
},
"required": [
"stream",
"consumer",
"sequence"
]
"type": "object"
},
"description": "each durable consumer the module reads with, and its position"
},
"size": {
"type": "integer",
"description": "its size in bytes"
},
"at": {
"type": "string",
"description": "when it was taken",
"format": "date-time"
},
"catch-up": {
"type": "object",
"description": "the catch-up tool and its arguments the restore point records (design 47 G 406)",
"properties": {
"tool": {
"type": "string"
},
"arguments": {
"type": "object"
}
},
"required": [
"tool"
]
"description": "a ledger's types, as its manifest declares them"
}
},
"required": [
"module",
"kept",
"form",
"fingerprint",
"snapshot"
"local",
"storage"
],
"description": "a restore point of one module's kept data on the bus, whole, with its consumers' positions"
},
"Aside": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "its id, for discard-aside"
},
"module": {
"type": "string",
"description": "the module"
},
"kept": {
"type": "string",
"description": "the kept data"
},
"form": {
"type": "integer",
"description": "the form it held"
},
"name": {
"type": "string",
"description": "the name it is kept under on the bus"
},
"size": {
"type": "integer",
"description": "its size in bytes"
},
"at": {
"type": "string",
"description": "when it was set aside",
"format": "date-time"
}
},
"required": [
"id",
"module",
"kept",
"name"
],
"description": "live kept data a restore set aside, never removed but by discard-aside"
"description": "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"
}
}
}
ts/seats/meshbroker/index.d.ts
Vendored
+25 -122
View File
@@ -13,8 +13,6 @@ export declare const verbs: {
readonly apply: "apply";
readonly recreate: "recreate";
readonly drop: "drop";
readonly snapshotKept: "snapshot-kept";
readonly restoreKept: "restore-kept";
};
export declare const events: {
@@ -49,36 +47,34 @@ export declare const recreatedSubject: "mesh.seat.mesh-broker.event.recreated";
export declare const droppedSubject: "mesh.seat.mesh-broker.event.dropped";
/** live kept data a restore set aside, never removed but by discard-aside */
export interface Aside {
/** when it was set aside */
"at"?: string;
/** the form it held */
"form"?: number;
/** its id, for discard-aside */
"id": string;
/** the kept data */
"kept": string;
/** the module */
"module": string;
/** the name it is kept under on the bus */
"name": string;
/** its size in bytes */
"size"?: number;
}
/** the binding a module receives in its membership for one entry (ADR 0595 §1, §7) */
/** 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 */
export interface Binding {
/** the entry's name on the bus */
"bus-name": string;
/** a key-value bucket's name */
"bucket"?: string;
/** a ledger's history stream */
"history"?: string;
/** a ledger's index buckets, by index name */
"indexes"?: Record<string, string>;
/** the entry's local name in the module's manifest */
"local": string;
/** an object store's name */
"object-store"?: string;
/** the bus name of the state's <state>-objects, where its large values go (design 47 G 58, 399) */
"objects"?: string;
/** how the bus keeps it */
"storage-type": string;
/** its subjects, for a stream */
"subjects"?: string[];
/** the subject of a ledger's instances' snapshots */
"snapshot"?: string;
/** a ledger's state bucket */
"state"?: string;
/** how the bus keeps it: the entry's storage type */
"storage": string;
/** a stream's name on the bus */
"stream"?: string;
/** the subject a stream's messages are on; also a ledger's history's */
"subject"?: string;
/** its template */
"template"?: string;
/** a ledger's types, as its manifest declares them */
"types"?: Record<string, unknown>[];
}
/** one piece of bus state as a manifest asks it */
@@ -108,6 +104,8 @@ export interface Fill {
/** one entry as the bus holds it */
export interface Held {
/** 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;
/** its name on the bus, <module>_<local name> */
"bus-name": string;
/** its own configuration, where no template fits */
@@ -131,43 +129,6 @@ export interface Held {
"why"?: string;
}
/** the catch-up tool and its arguments the restore point records (design 47 G 406) */
export interface KeptPointCatchUp {
"arguments"?: Record<string, unknown>;
"tool": string;
}
export interface KeptPointConsumersItem {
/** the durable consumer */
"consumer": string;
/** its acknowledged position */
"sequence": number;
/** the stream */
"stream": string;
}
/** a restore point of one module's kept data on the bus, whole, with its consumers' positions */
export interface KeptPoint {
/** when it was taken */
"at"?: string;
/** the catch-up tool and its arguments the restore point records (design 47 G 406) */
"catch-up"?: KeptPointCatchUp;
/** each durable consumer the module reads with, and its position */
"consumers"?: KeptPointConsumersItem[];
/** the fingerprint the restore point is taken before */
"fingerprint": string;
/** its form, the number the holder raises when it changes how it writes it (0 when undeclared) */
"form": number;
/** the kept data, its local name in the module's manifest */
"kept": string;
/** the module */
"module": string;
/** its size in bytes */
"size"?: number;
/** the restore point's name */
"snapshot": string;
}
export interface Named {
/** the entry's local name */
"local-name": string;
@@ -298,64 +259,6 @@ export interface DropAnswer {
"snapshot"?: string;
}
/** 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) */
export interface SnapshotKeptInputCatchUp {
"arguments"?: Record<string, unknown>;
"tool": string;
}
/** is what snapshot-kept takes. */
export interface SnapshotKeptInput {
/** 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) */
"catch-up"?: SnapshotKeptInputCatchUp;
/** the fingerprint the restore point is taken before */
"fingerprint": string;
/** its form, the number the holder raises when it changes how it writes it (0 when undeclared) */
"form": number;
/** the kept data, its local name in the module's manifest */
"kept": string;
/** the module */
"module": string;
/** why it is taken */
"why"?: string;
}
/** is what snapshot-kept answers. */
export interface SnapshotKeptAnswer {
/** why it failed; set alone */
"error"?: string;
"point"?: KeptPoint;
}
/** is what restore-kept takes. */
export interface RestoreKeptInput {
/** set the live data aside and restore nothing */
"aside-only"?: boolean;
/** the name of data set aside: remove it and restore nothing */
"discard-aside"?: string;
/** the fingerprint the restore point is taken before */
"fingerprint": string;
/** its form, the number the holder raises when it changes how it writes it (0 when undeclared) */
"form": number;
/** the kept data, its local name in the module's manifest */
"kept": string;
/** the module */
"module": string;
/** the restore point's name; not with aside-only or discard-aside */
"snapshot"?: string;
/** why */
"why"?: string;
}
/** is what restore-kept answers. */
export interface RestoreKeptAnswer {
"aside"?: Aside;
/** why it failed; set alone */
"error"?: string;
/** the restore point is the live data now */
"restored"?: boolean;
}
/** is the body of the event created. */
export type CreatedEvent = Said;
ts/seats/meshbroker/index.js
-2
View File
@@ -13,8 +13,6 @@ export const verbs = {
apply: "apply",
recreate: "recreate",
drop: "drop",
snapshotKept: "snapshot-kept",
restoreKept: "restore-kept",
};
export const events = {