From ada45be38b95cbe66903873080b1fd8e312e7a9b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:35:35 +0100 Subject: [PATCH 01/62] AM-C1: the operator-channel client puts a key prefix before every key of its own state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Client.KeyPrefix is put before the keys the client writes and reads in its own State; empty for every asker today, so today's keys stay; Where still reads the router's record under .. Builds: design 46 milestone 7 §10, §22 (design 47 G, approval mark) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../clients/operatorchannelclient/client.go | 13 ++++++----- .../operatorchannelclient/client_test.go | 22 +++++++++++++++++++ 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client.go b/operator-and-conversation/go/clients/operatorchannelclient/client.go index b809fe1..645e48e 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client.go @@ -27,6 +27,9 @@ type Client struct { Module string // State is the module's own state the asks are kept in. State Store + // KeyPrefix is put before every key of State the client writes and reads; empty for every asker today, so + // today's keys stay (design 46 milestone 7 §10). The router's record Where reads is never prefixed. + KeyPrefix string // Now is the clock; nil is time.Now. Now func() time.Time // Publish, Record and Subscribe reach the bus; nil is the stdio SDK's, through the module's runtime. @@ -63,7 +66,7 @@ type Kept struct { Answer *seat.Warrant `json:"answer,omitempty"` } -func key(id string) string { return "ask." + id } +func (c *Client) key(id string) string { return c.KeyPrefix + "ask." + id } // Ask checks an ask, keeps it, and publishes it under the module's own name. An ask with an id already kept // is refused: a new question is a new id. @@ -71,7 +74,7 @@ func (c *Client) Ask(a seat.Ask) error { if err := Check(a, c.now()); err != nil { return err } - if _, err := c.State.Create(key(a.ID), Kept{Ask: a, Asked: c.now()}); err != nil { + if _, err := c.State.Create(c.key(a.ID), Kept{Ask: a, Asked: c.now()}); err != nil { if errors.Is(err, stdio.ErrChanged) { return fmt.Errorf("an ask %s was already made: a new question is a new id", a.ID) } @@ -130,7 +133,7 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error) if w.Asker != c.Module { return Refused, fmt.Errorf("a warrant for %s reached %s", w.Asker, c.Module) } - e, err := c.State.Get(key(w.Ask)) + e, err := c.State.Get(c.key(w.Ask)) if err != nil { return "", err } @@ -147,7 +150,7 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error) if w.Outcome != OutcomeChosen { k.Ended = w.Outcome k.Answer = &w - if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) { + if _, err := c.State.Update(c.key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) { return "", err } return Recorded, nil @@ -158,7 +161,7 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error) } // Marked before acting: of two deliveries, or two instances, only the one whose write stands acts. k.Acted, k.Ended, k.Answer = true, OutcomeChosen, &w - if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil { + if _, err := c.State.Update(c.key(w.Ask), k, e.Revision); err != nil { if errors.Is(err, stdio.ErrChanged) { return Done, nil } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 45c2b0a..8798ea5 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -139,3 +139,25 @@ func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) { t.Errorf("%s", h) } } + +func TestAKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere(t *testing.T) { + for _, tc := range []struct{ prefix, key string }{{"n1.", "n1.ask.d-1"}, {"", "ask.d-1"}} { + c, _ := client() + store := c.State.(*mem) + c.KeyPrefix = tc.prefix + var asked string + c.Record = func(k string) (*stdio.StateEntry, error) { asked = k; return nil, nil } + if err := c.Ask(askedHeld()); err != nil { + t.Fatal(err) + } + if _, ok := store.vals[tc.key]; len(store.vals) != 1 || !ok { + t.Fatalf("prefix %q: keys written %v, want %s", tc.prefix, store.vals, tc.key) + } + if h, err := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { return nil }); h != Acted || err != nil { + t.Fatalf("prefix %q: the warrant was not read from %s: %s %v", tc.prefix, tc.key, h, err) + } + if _, _, err := c.Where("an-asker.d-1"); err != nil || asked != "an-asker.d-1" { + t.Errorf("prefix %q: Where read %q", tc.prefix, asked) + } + } +} From a7113023237893868f03242c5549a44bf5a252b9 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:37:48 +0100 Subject: [PATCH 02/62] C1, C2 (format): the schema names a verb's class and callers list, an accepted kind's callers, a kept event, acts and bodies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A verb gains class (read, act, warrant), callers as a list of the forms of §336/§392 and needs-approval; an accepted kind gains callers; an event gains subject and keep as an object (max-age-days, max-mib, last-per-subject), a dot only without keep; the seat gains acts (steps incl. pipeline, on every|language| kind:image, bound) and bodies. Builds: design 47 G §68, §203, §336, §338, §391, §392, §396, §397, §439; design 46 milestone 7 §2 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- format/seat-definition.schema.json | 152 +++++++++++++++++++++++++++-- 1 file changed, 143 insertions(+), 9 deletions(-) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index 46a1557..1b0888b 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://git.novox.be/novox/mesh-contracts/format/seat-definition.schema.json", - "title": "A seat's definition (novox/hq ADR 0608 \u00a71, design 26), format 1", - "description": "One file per seat, seats//seat.json. A whole definition (grain whole) gives every verb's input and answer, every message's body and where its events are kept; one at the seat list's grain (seat-list) holds what mesh-sdk's compiled seat list held (ADR 0613 \u00a72). At most 256 KiB. Read strictly: a field not named here is refused.", + "title": "A seat's definition (novox/hq ADR 0608 §1, design 26), format 1", + "description": "One file per seat, seats//seat.json. A whole definition (grain whole) gives every verb's input and answer, every message's body and where its events are kept; one at the seat list's grain (seat-list) holds what mesh-sdk's compiled seat list held (ADR 0613 §2). At most 256 KiB. Read strictly: a field not named here is refused.", "type": "object", "additionalProperties": false, "required": [ @@ -34,7 +34,7 @@ ] }, "domain": { - "description": "the glossary domain the seat belongs to, by its heading (ADR 0636 \u00a75)", + "description": "the glossary domain the seat belongs to, by its heading (ADR 0636 §5)", "enum": [ "Module", "Config", @@ -97,9 +97,9 @@ "events": { "type": "array", "items": { - "$ref": "#/$defs/message" + "$ref": "#/$defs/event" }, - "description": "published on mesh.seat..event." + "description": "published on mesh.seat..event., or on its subject when it carries parts" }, "family": { "type": "object", @@ -144,11 +144,11 @@ } } }, - "description": "the holder's own events listed beside the seat, keeping the holder's subjects (ADR 0620 \u00a72)" + "description": "the holder's own events listed beside the seat, keeping the holder's subjects (ADR 0620 §2)" }, "states": { "type": "array", - "description": "the layouts of the state the holder keeps on the bus for the seat (ADR 0608 \u00a71, ADR 0634 \u00a76); a whole definition's. No holder module is named: each reader takes the holder from its own manifest's reads", + "description": "the layouts of the state the holder keeps on the bus for the seat (ADR 0608 §1, ADR 0634 §6); a whole definition's. No holder module is named: each reader takes the holder from its own manifest's reads", "items": { "$ref": "#/$defs/state" } @@ -261,6 +261,50 @@ "type": "object", "description": "a JSON Schema" } + }, + "acts": { + "type": "array", + "description": "the seat's acting rules (design 47 G 203): each step of a delivery the seat's holder acts in, on which modules, and how long an entry waits there for the holder's new version", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "step" + ], + "properties": { + "step": { + "type": "string", + "enum": [ + "take-in", + "validate", + "check", + "pipeline", + "build", + "compose", + "grant", + "place" + ] + }, + "on": { + "type": "string", + "pattern": "^(every|kind:image|[a-z][a-z0-9-]*)$", + "description": "every (the default), a language, or kind:image (design 47 G 397)" + }, + "bound": { + "type": "string", + "pattern": "^([0-9]+(\\.[0-9]+)?(h|m|s|ms))+$", + "description": "how long an entry waits in the step for the holder's new version, such as 30m (design 47 G 397); none is the step's default" + } + } + } + }, + "bodies": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "a JSON Schema" + }, + "description": "the bodies other modules say on their own streams, from which the grants part makes no seat event or stream (design 47 G 439)" } }, "$defs": { @@ -296,7 +340,25 @@ "description": "a JSON Schema" }, "callers": { - "type": "string" + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^(operator|healers|persons|sessions|invokers|seat:[a-z][a-z0-9-]*|module:[a-z][a-z0-9-]*|holder:[a-z][a-z0-9-]*@same-node)$" + }, + "description": "who may call: a list of operator, healers, persons (any person the tool runner proves), sessions (an agent session it proves), invokers (every module whose manifest declares the verb in invokes), seat: (a holder role), module:, or holder:@same-node (the holder of that seat on the node of the verb's holder); the grants part reads it as its one source of caller limits (design 47 G, 336 and 392). A verb naming none takes the default of its class (391)" + }, + "class": { + "enum": [ + "read", + "act", + "warrant" + ], + "description": "read: invokers, persons and sessions; act: operator and sessions; warrant: operator alone, with needs-approval (design 47 G 391). A verb without it on main is a read; a verb added in design 47 G names it" + }, + "needs-approval": { + "type": "boolean", + "description": "the verb runs only on the operator's Approve of the call, for every holder (design 46 milestone 7, 2)" } } }, @@ -317,6 +379,15 @@ }, "by-caller": { "type": "boolean" + }, + "callers": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^(operator|healers|persons|sessions|invokers|seat:[a-z][a-z0-9-]*|module:[a-z][a-z0-9-]*|holder:[a-z][a-z0-9-]*@same-node)$" + }, + "description": "who may call: a list of operator, healers, persons (any person the tool runner proves), sessions (an agent session it proves), invokers (every module whose manifest declares the verb in invokes), seat: (a holder role), module:, or holder:@same-node (the holder of that seat on the node of the verb's holder); the grants part reads it as its one source of caller limits (design 47 G, 336 and 392). A verb naming none takes the default of its class (391)" } } }, @@ -433,7 +504,7 @@ "objects", "ledger" ], - "description": "ADR 0595 \u00a72" + "description": "ADR 0595 §2" }, "writer": { "enum": [ @@ -485,6 +556,69 @@ "type": "string" } } + }, + "event": { + "type": "object", + "additionalProperties": false, + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$", + "description": "lower-case words; a dot only in an event that names no keep, which stays on its seat's family (design 47 G 396)" + }, + "body": { + "type": "object", + "description": "a JSON Schema" + }, + "by-caller": { + "type": "boolean" + }, + "subject": { + "type": "string", + "pattern": "^([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>)(\\.([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>))*$", + "description": "the words after mesh.seat..event. with tokens, written out (design 47 G 397); a part is the publishing node's. Not with by-caller" + }, + "keep": { + "type": "object", + "additionalProperties": false, + "description": "the event is kept on the stream SEAT__ (design 47 G 396); without it the event stays on the seat's family", + "properties": { + "max-age-days": { + "type": "integer", + "minimum": 0, + "description": "days a message is kept; 0 is no age limit; 90 when not named" + }, + "max-mib": { + "type": "integer", + "minimum": 1, + "description": "the stream's cap in MiB; 16 when not named" + }, + "last-per-subject": { + "type": "boolean", + "description": "keep the last message of each subject; no when not named" + } + } + } + }, + "allOf": [ + { + "if": { + "required": [ + "keep" + ] + }, + "then": { + "properties": { + "name": { + "pattern": "^[a-z][a-z0-9-]*$" + } + } + } + } + ] } } } From 8d8a28934ce0f3fdbce040feb328c9cd4b7463e3 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:37:48 +0100 Subject: [PATCH 03/62] AM-C2: the login shell's verb execute is marked needs-approval MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 46 milestone 7 §21, §2 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-login-shell/seat.json | 1 + 1 file changed, 1 insertion(+) diff --git a/seats/node-login-shell/seat.json b/seats/node-login-shell/seat.json index 9d6295a..44a4d28 100644 --- a/seats/node-login-shell/seat.json +++ b/seats/node-login-shell/seat.json @@ -10,6 +10,7 @@ "name": "execute", "description": "Run one command on this machine as the operator account, in a non-interactive login shell in its home; answers with what it printed and how it exited.", "optional": true, + "needs-approval": true, "input": { "properties": { "command": { From f33c1d4b78e211a65d14724eee6d0de4b2d82e0f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:38:50 +0100 Subject: [PATCH 04/62] C3: the callers of mesh-broker's four reads, mesh-config's renames, mesh-vault's retire and node-engine's seat-list verbs are lists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mesh-broker list, show, check, orphans and mesh-config renames name invokers; mesh-vault retire names seat:mesh-config; node-engine seat-list names persons and healers, seat-list-again the operator and the healers. mesh-broker create, apply, recreate and drop keep their text: the design names no form for them. Builds: design 47 G §336, §392, §204 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- identity-and-access/seats/mesh-vault/seat.json | 4 +++- seats/mesh-broker/seat.json | 16 ++++++++++++---- seats/mesh-config/seat.json | 4 +++- seats/node-engine/seat.json | 10 ++++++++-- 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/identity-and-access/seats/mesh-vault/seat.json b/identity-and-access/seats/mesh-vault/seat.json index 7c93f1b..749f148 100644 --- a/identity-and-access/seats/mesh-vault/seat.json +++ b/identity-and-access/seats/mesh-vault/seat.json @@ -597,7 +597,9 @@ "name": "retire", "optional": true, "description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.", - "callers": "the holder of the seat mesh-config alone", + "callers": [ + "seat:mesh-config" + ], "input": { "type": "object", "properties": { diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index 6fc5d4e..d0efe0f 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -11,7 +11,9 @@ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", - "callers": "any caller whose role grants it", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": { @@ -41,7 +43,9 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": "any caller whose role grants it", + "callers": [ + "invokers" + ], "input": { "$ref": "#/defs/Named" }, @@ -53,7 +57,9 @@ { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", - "callers": "any caller whose role grants it", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": { @@ -109,7 +115,9 @@ { "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.", - "callers": "any caller whose role grants it", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": {}, diff --git a/seats/mesh-config/seat.json b/seats/mesh-config/seat.json index 9a555b1..a92bc0a 100644 --- a/seats/mesh-config/seat.json +++ b/seats/mesh-config/seat.json @@ -64,7 +64,9 @@ } } }, - "callers": "any caller whose role grants it; the checker asks it", + "callers": [ + "invokers" + ], "answer": { "type": "object", "properties": { diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 49462e9..f04b6ff 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -678,7 +678,10 @@ { "name": "seat-list", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", - "callers": "the operator and the healers", + "callers": [ + "persons", + "healers" + ], "input": { "type": "object", "properties": {} @@ -690,7 +693,10 @@ { "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", - "callers": "the operator and the healers", + "callers": [ + "operator", + "healers" + ], "input": { "type": "object", "properties": {} From 91818305e7f33d696be1f421116d77d5f139507d Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:39:23 +0100 Subject: [PATCH 05/62] C5: the node-engine seat says composed, running (kept last per subject, no age limit, or stopped) and capabilities-changed, acts in compose, and serves process-builds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewritten from the earlier branch to the final lines: keep as an object, stopped on running, process-builds a read for persons, sessions and healers and not optional, the compose rule with the step's default bound. The eleven verbs' callers (§393) wait on a question; the generated Go and TypeScript wait on the generator. Builds: design 47 G §177, §199, §203, §260, §261, §266, §396, §404, §440 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/fixtures/events.json | 52 ++++++ seats/node-engine/fixtures/verbs.json | 39 +++++ seats/node-engine/seat.json | 233 ++++++++++++++++++++++++- 3 files changed, 323 insertions(+), 1 deletion(-) diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index eb2c8d7..657566e 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -65,5 +65,57 @@ "at": "2026-11-04T10:05:00Z", "why": "returned" } + }, + { + "name": "composed is said", + "of": "event:composed", + "subject": "mesh.seat.node-engine.event.composed.ace", + "given": { + "v": 1, + "node": "ace", + "module": "nats", + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "at": "2026-11-09T20:00:00Z" + } + }, + { + "name": "running is said, its node and module in its subject", + "of": "event:running", + "subject": "mesh.seat.node-engine.event.running.ace.nats", + "given": { + "v": 1, + "node": "ace", + "module": "nats", + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", + "at": "2026-11-09T20:01:00Z" + } + }, + { + "name": "running says a module stopped on the node, with no fingerprint", + "of": "event:running", + "subject": "mesh.seat.node-engine.event.running.ace.nats", + "given": { + "v": 1, + "node": "ace", + "module": "nats", + "stopped": true, + "at": "2026-11-11T09:00:00Z" + } + }, + { + "name": "capabilities-changed is said", + "of": "event:capabilities-changed", + "subject": "mesh.seat.node-engine.event.capabilities-changed.ace", + "given": { + "v": 1, + "node": "ace", + "capabilities": [ + "build-go", + "docker" + ], + "at": "2026-11-09T20:02:00Z" + } } ] diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index 3375279..8c72985 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -117,5 +117,44 @@ "health": "the seat list is held from the bootstrap", "error": "seatlist: no answer" } + }, + { + "name": "process-builds asks one module", + "of": "verb:process-builds.input", + "given": { + "module": "nats" + } + }, + { + "name": "process-builds answers each process's build", + "of": "verb:process-builds.answer", + "given": { + "node": "ace", + "processes": [ + { + "module": "nats", + "process": "nats.service", + "kind": "service", + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "started": "2026-11-09T19:00:00Z" + }, + { + "module": "route-proxy", + "process": "route-proxy", + "kind": "container", + "unknown": "started before the node-engine handed MESH_FINGERPRINT", + "started": "2026-11-01T08:00:00Z" + } + ] + } + }, + { + "name": "process-builds answers an error", + "of": "verb:process-builds.answer", + "given": { + "node": "ace", + "processes": [], + "error": "the service manager did not answer" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index f04b6ff..1a08c68 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -5,8 +5,14 @@ "grain": "whole", "domain": "Core", "decision": "novox/hq ADR 0563", - "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token.", + "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", "held-by-the-engine": true, + "acts": [ + { + "step": "compose", + "on": "every" + } + ], "verbs": [ { "name": "hand-over", @@ -704,6 +710,29 @@ "answer": { "$ref": "#/defs/SeatList" } + }, + { + "name": "process-builds", + "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", + "callers": [ + "persons", + "sessions", + "healers" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "only this module's processes" + } + }, + "additionalProperties": false + }, + "answer": { + "$ref": "#/defs/ProcessBuilds" + }, + "class": "read" } ], "events": [ @@ -734,6 +763,31 @@ "body": { "$ref": "#/defs/ManifestReadsChanged" } + }, + { + "name": "composed", + "subject": "composed.", + "body": { + "$ref": "#/defs/Composed" + } + }, + { + "name": "running", + "subject": "running..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Running" + } + }, + { + "name": "capabilities-changed", + "subject": "capabilities-changed.", + "body": { + "$ref": "#/defs/CapabilitiesChanged" + } } ], "family": { @@ -2664,6 +2718,183 @@ "state", "since" ] + }, + "Composed": { + "type": "object", + "description": "an entry composed on a node (design 47 *What each step says*)", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint of the want composed" + }, + "digest": { + "type": "string", + "description": "the digest of the composition (design 47 G 404)" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "v", + "node", + "module", + "fingerprint", + "digest", + "at" + ] + }, + "Running": { + "type": "object", + "description": "a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint of the build it runs; none with stopped" + }, + "manifest": { + "type": "string", + "description": "the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half" + }, + "at": { + "type": "string", + "description": "when it was seen running healthy, RFC 3339", + "format": "date-time" + }, + "stopped": { + "type": "boolean", + "description": "true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there" + } + }, + "required": [ + "v", + "node", + "module", + "at" + ] + }, + "CapabilitiesChanged": { + "type": "object", + "description": "a node's capabilities changed, which the assigner places by", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "capabilities": { + "type": "array", + "items": { + "type": "string" + }, + "description": "its capabilities now" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "v", + "node", + "capabilities", + "at" + ] + }, + "ProcessBuild": { + "type": "object", + "description": "the build one process of a module was started with", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "process": { + "type": "string", + "description": "the service's unit or the container's name" + }, + "kind": { + "type": "string", + "description": "service or container", + "enum": [ + "service", + "container" + ] + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint handed to it in MESH_FINGERPRINT; empty when it was started without one" + }, + "unknown": { + "type": "string", + "description": "why its build is unknown: started before the node-engine handed MESH_FINGERPRINT, or the value could not be read" + }, + "started": { + "type": "string", + "description": "when it was started, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "module", + "process", + "kind" + ] + }, + "ProcessBuilds": { + "type": "object", + "description": "what process-builds answers", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "processes": { + "type": "array", + "items": { + "$ref": "#/defs/ProcessBuild" + }, + "description": "every process the node-engine started, by module" + }, + "error": { + "type": "string", + "description": "why they could not be read" + } + }, + "required": [ + "node", + "processes" + ] } } } From a904102a0774614687e5153f0cb0d22cf7a966a3 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:39:46 +0100 Subject: [PATCH 06/62] C6: a placed module and a place change name the watched branch and the build's fingerprint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §14, §78, §114, §402 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../mesh-module-assigner/fixtures/states.json | 36 +++++++++++++++++++ seats/mesh-module-assigner/seat.json | 16 +++++++++ 2 files changed, 52 insertions(+) diff --git a/seats/mesh-module-assigner/fixtures/states.json b/seats/mesh-module-assigner/fixtures/states.json index 04e940b..d08098b 100644 --- a/seats/mesh-module-assigner/fixtures/states.json +++ b/seats/mesh-module-assigner/fixtures/states.json @@ -58,6 +58,19 @@ } } }, + { + "name": "a module's key on a watched branch and a build", + "of": "state:assignments/.", + "given": { + "v": 1, + "node": "ace", + "placed": { + "module": "plex", + "branch": "beta", + "build": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + } + } + }, { "name": "an open proposal", "of": "state:proposals/", @@ -82,6 +95,29 @@ "state": "answering" } }, + { + "name": "a proposal placing a module on a watched branch at an earlier build", + "of": "state:proposals/", + "given": { + "id": "p-20261110t120000-aabbccdd", + "by": "operator", + "why": "run nats from beta, back one build", + "at": "2026-11-10T12:00:00Z", + "changes": [ + { + "op": "place", + "node": "ace", + "module": "nats", + "branch": "beta", + "build": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + } + ], + "base": { + "ace": 3 + }, + "state": "answering" + } + }, { "name": "a candidate", "of": "state:candidates/.", diff --git a/seats/mesh-module-assigner/seat.json b/seats/mesh-module-assigner/seat.json index 1eb0669..cd483f5 100644 --- a/seats/mesh-module-assigner/seat.json +++ b/seats/mesh-module-assigner/seat.json @@ -407,6 +407,14 @@ "module": { "type": "string" }, + "branch": { + "type": "string", + "description": "the watched branch this node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14)" + }, + "build": { + "type": "string", + "description": "the fingerprint of the build the node runs; absent, the newest delivered of the branch (design 47 G 78, 402)" + }, "ports": { "type": "object", "additionalProperties": { @@ -636,6 +644,14 @@ "module": { "type": "string" }, + "branch": { + "type": "string", + "description": "for place, the watched branch the node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14)" + }, + "build": { + "type": "string", + "description": "for place, the build of that branch the node runs, a return to an earlier build being this one value; absent, the newest delivered of the branch (ADR 0666 section 24)" + }, "ports": { "type": "object", "additionalProperties": { From d86a46e5d8cc264ff78dc7115e9f28ebde7c18ec Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:40:23 +0100 Subject: [PATCH 07/62] C7: node-backup backs up and restores a module's kept data on the bus: aside, discard-aside, ended and restored MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit now, restore and aside are of class act; discard-aside is the operator's alone; ended and restored carry the node, module and kept data in their subject and the module, kept data, form, fingerprint and outcome. Builds: design 47 G §296, §297, §302, §405 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-backup/fixtures/events.json | 29 ++++ seats/node-backup/seat.json | 217 ++++++++++++++++++++++++- 2 files changed, 242 insertions(+), 4 deletions(-) create mode 100644 seats/node-backup/fixtures/events.json diff --git a/seats/node-backup/fixtures/events.json b/seats/node-backup/fixtures/events.json new file mode 100644 index 0000000..9a5e58f --- /dev/null +++ b/seats/node-backup/fixtures/events.json @@ -0,0 +1,29 @@ +[ + { + "name": "ended is said, its node, module and kept data in its subject", + "of": "event:ended", + "subject": "mesh.seat.node-backup.event.ended.ace.plex.library", + "given": { + "v": 1, + "module": "plex", + "kept": "library", + "form": 2, + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "outcome": "done" + } + }, + { + "name": "restored failed says why", + "of": "event:restored", + "subject": "mesh.seat.node-backup.event.restored.ace.plex.library", + "given": { + "v": 1, + "module": "plex", + "kept": "library", + "form": 2, + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "outcome": "failed", + "error": "restore point missing" + } + } +] diff --git a/seats/node-backup/seat.json b/seats/node-backup/seat.json index f5c59d2..66653b7 100644 --- a/seats/node-backup/seat.json +++ b/seats/node-backup/seat.json @@ -8,7 +8,7 @@ "verbs": [ { "name": "backed-up", - "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size. Also each module's restore points of its kept data on the bus (the kept data, the form, the fingerprint each was taken before) and the data set aside at each restore, with its size.", "replaces": [ "restic snapshots" ], @@ -24,7 +24,7 @@ }, { "name": "now", - "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. With kept, a restore point of one kept data on the bus instead, said by the event ended.", "replaces": [ "restic backup" ], @@ -33,14 +33,42 @@ "module": { "description": "one module (optional)", "type": "string" + }, + "kept": { + "type": "string", + "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" + }, + "form": { + "type": "integer", + "description": "with kept: its form now" + }, + "fingerprint": { + "type": "string", + "description": "with kept: the fingerprint the restore point is taken before" + }, + "catch-up": { + "type": "object", + "description": "with kept: the catch-up tool the newer manifest declares beside it and its arguments whole, recorded in the restore point (design 47 G 299, 406)", + "properties": { + "tool": { + "type": "string" + }, + "arguments": { + "type": "object" + } + }, + "required": [ + "tool" + ] } }, "type": "object" - } + }, + "class": "act" }, { "name": "restore", - "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as \u003cpath\u003e.restored-\u003cdate\u003e. Swapping it in is a person's act. Lists the restore points when none is named.", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named. With kept, the restore point of one kept data on the bus by its module, kept data and form, the live data set aside and never removed, said by the event restored.", "replaces": [ "restic restore" ], @@ -57,13 +85,96 @@ "snapshot": { "description": "the restore point (from `backed-up`; the newest when omitted)", "type": "string" + }, + "kept": { + "type": "string", + "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" + }, + "form": { + "type": "integer", + "description": "with kept: its form now" + }, + "fingerprint": { + "type": "string", + "description": "with kept: the fingerprint the restore point is taken before" } }, "required": [ "module" ], "type": "object" + }, + "class": "act" + }, + { + "name": "aside", + "description": "Set one module's live kept data on the bus aside under a name of its own and restore nothing, after the node agent stopped the newer build (design 47 G 297, 405); the data set aside is listed by backed-up and removed only by discard-aside.", + "class": "act", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "kept": { + "type": "string", + "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" + }, + "form": { + "type": "integer", + "description": "with kept: its form now" + }, + "fingerprint": { + "type": "string", + "description": "with kept: the fingerprint the restore point is taken before" + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint" + ] + }, + "answer": { + "type": "object", + "properties": { + "aside": { + "type": "string", + "description": "the name the live data is set aside under" + }, + "error": { + "type": "string", + "description": "why it failed; set alone" + } + } } + }, + { + "name": "discard-aside", + "description": "Remove data a restore set aside, on a person's call alone; writes the act, who and why in the hand-act log of the seat mesh-hand-acts.", + "callers": [ + "operator" + ], + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the aside's id, as backed-up lists it" + }, + "why": { + "type": "string", + "description": "why" + } + }, + "required": [ + "id", + "why" + ] + }, + "class": "act" } ], "receives": [ @@ -77,5 +188,103 @@ "comment": "#", "dirs": true } + ], + "events": [ + { + "name": "ended", + "subject": "ended...", + "body": { + "type": "object", + "description": "a restore point of a kept data on the bus taken, done or failed", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "module": { + "type": "string", + "description": "the module" + }, + "kept": { + "type": "string", + "description": "the kept data" + }, + "form": { + "type": "integer", + "description": "its form" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint" + }, + "outcome": { + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string", + "description": "why it failed" + } + }, + "required": [ + "v", + "module", + "kept", + "form", + "fingerprint", + "outcome" + ] + } + }, + { + "name": "restored", + "subject": "restored...", + "body": { + "type": "object", + "description": "a kept data on the bus restored from its restore point beside the live data, done or failed", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "module": { + "type": "string", + "description": "the module" + }, + "kept": { + "type": "string", + "description": "the kept data" + }, + "form": { + "type": "integer", + "description": "its form" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint" + }, + "outcome": { + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string", + "description": "why it failed" + } + }, + "required": [ + "v", + "module", + "kept", + "form", + "fingerprint", + "outcome" + ] + } + } ] } From bcb37afb484774e34fb36bd88a7f8d0036c9405b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:40:49 +0100 Subject: [PATCH 08/62] C8: mesh-broker takes and restores a module's kept data (snapshot-kept, restore-kept) and a binding names its objects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both verbs are of class act, not optional, and called by holder:node-backup@same-node alone; restore-kept takes aside-only and discard-aside; the Binding gains objects. The verbs' sibling mesh-broker callers text (create, apply, recreate, drop) is left as it is: a question is open. Builds: design 47 G §58, §59, §337, §399, §400, §405, §406 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/mesh-broker/fixtures/verbs.json | 45 +++++ seats/mesh-broker/seat.json | 275 ++++++++++++++++++++++++++ 2 files changed, 320 insertions(+) diff --git a/seats/mesh-broker/fixtures/verbs.json b/seats/mesh-broker/fixtures/verbs.json index a1d5c41..81439ab 100644 --- a/seats/mesh-broker/fixtures/verbs.json +++ b/seats/mesh-broker/fixtures/verbs.json @@ -47,5 +47,50 @@ } ] } + }, + { + "name": "snapshot-kept answers the restore point", + "of": "verb:snapshot-kept.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 + } + ], + "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" + } + } } ] diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index d0efe0f..baff7db 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -200,6 +200,150 @@ ] }, "optional": true + }, + { + "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": [ @@ -566,6 +710,10 @@ "type": "string" }, "description": "its subjects, for a stream" + }, + "objects": { + "type": "string", + "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" } }, "required": [ @@ -573,6 +721,133 @@ "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": { + "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" + }, + "consumers": { + "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" + ] + }, + "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" + ] + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "snapshot" + ], + "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" } } } From 5cd44f0ebe1dd5cd18ddc1349d5f51b455afe7d4 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:41:42 +0100 Subject: [PATCH 09/62] C9: the seat mesh-grants is defined whole: rule grant, the events wait-held, wait-ended, filling and room, and the read grants-for MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewritten from the earlier branch to the final lines: the earlier verbs waits and release go (the part's tools stay its own), grants-for is added, wait events carry clock-from, filling and room carry a store's fill as mesh-wants' do. The generated Go and TypeScript wait on the generator. Builds: design 47 Where it goes (grants part), G §264, §266, §331, §401, §441 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- identity-and-access/module.json | 20 ++ identity-and-access/seats/index.json | 1 + .../seats/mesh-grants/fixtures/events.json | 56 +++++ .../seats/mesh-grants/fixtures/verbs.json | 28 +++ .../seats/mesh-grants/seat.json | 222 ++++++++++++++++++ .../seats/mesh-vault/seat.json | 4 +- 6 files changed, 328 insertions(+), 3 deletions(-) create mode 100644 identity-and-access/seats/mesh-grants/fixtures/events.json create mode 100644 identity-and-access/seats/mesh-grants/fixtures/verbs.json create mode 100644 identity-and-access/seats/mesh-grants/seat.json diff --git a/identity-and-access/module.json b/identity-and-access/module.json index 20e2d2c..4f3b3f3 100644 --- a/identity-and-access/module.json +++ b/identity-and-access/module.json @@ -23,6 +23,16 @@ "series": "0.1", "generated-from": "." }, + { + "name": "go-meshgrants", + "kind": "package", + "language": "go", + "paths": [ + "go/seats/meshgrants" + ], + "series": "0.1", + "generated-from": "." + }, { "name": "go-meshvaultclient", "kind": "package", @@ -60,6 +70,16 @@ ], "series": "0.1", "generated-from": "." + }, + { + "name": "ts-meshgrants", + "kind": "package", + "language": "typescript", + "paths": [ + "ts/seats/meshgrants" + ], + "series": "0.1", + "generated-from": "." } ] }, diff --git a/identity-and-access/seats/index.json b/identity-and-access/seats/index.json index 72e28e3..c8222f2 100644 --- a/identity-and-access/seats/index.json +++ b/identity-and-access/seats/index.json @@ -1,6 +1,7 @@ { "format": 1, "seats": [ + "mesh-grants", "mesh-node-enroller", "mesh-vault", "node-secret-service" diff --git a/identity-and-access/seats/mesh-grants/fixtures/events.json b/identity-and-access/seats/mesh-grants/fixtures/events.json new file mode 100644 index 0000000..6e72de6 --- /dev/null +++ b/identity-and-access/seats/mesh-grants/fixtures/events.json @@ -0,0 +1,56 @@ +[ + { + "name": "a granting wait held", + "of": "event:wait-held", + "subject": "mesh.seat.mesh-grants.event.wait-held", + "given": { + "step": "grant", + "part": "mesh-grants", + "version": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "module": "mesh-tools", + "fp": "src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "since": "2026-11-09T21:00:00Z", + "bound": "10m", + "clock-from": "2026-11-09T20:55:00Z" + } + }, + { + "name": "a granting wait released", + "of": "event:wait-ended", + "subject": "mesh.seat.mesh-grants.event.wait-ended", + "given": { + "step": "grant", + "part": "mesh-grants", + "version": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "module": "mesh-tools", + "fp": "src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "since": "2026-11-09T21:00:00Z", + "bound": "10m", + "how": "released", + "by": "jochen: the new grants part is stuck", + "clock-from": "2026-11-09T20:55:00Z" + } + }, + { + "name": "filling is said past 80 %", + "of": "event:filling", + "subject": "mesh.seat.mesh-grants.event.filling", + "given": { + "store": "SEAT_mesh-pipeline-runner_pipeline-ended", + "bytes": 161061273, + "cap": 201326592, + "at": "2026-11-11T09:00:00Z" + } + }, + { + "name": "room is said below 70 %", + "of": "event:room", + "subject": "mesh.seat.mesh-grants.event.room", + "given": { + "store": "SEAT_mesh-pipeline-runner_pipeline-ended", + "bytes": 100663296, + "cap": 201326592, + "at": "2026-11-11T10:00:00Z" + } + } +] diff --git a/identity-and-access/seats/mesh-grants/fixtures/verbs.json b/identity-and-access/seats/mesh-grants/fixtures/verbs.json new file mode 100644 index 0000000..e2bd9f1 --- /dev/null +++ b/identity-and-access/seats/mesh-grants/fixtures/verbs.json @@ -0,0 +1,28 @@ +[ + { + "name": "grants-for answers the grants a candidate adds", + "of": "verb:grants-for.answer", + "given": { + "modules": [ + { + "module": "mesh-tools", + "added": [ + { + "subject": "mesh.seat.node-engine.verb.manifest-reads", + "verb": "manifest-reads" + } + ], + "removed": [] + } + ] + } + }, + { + "name": "grants-for asks a source revision on a branch", + "of": "verb:grants-for.input", + "given": { + "source": "a1b2c3d4", + "branch": "main" + } + } +] diff --git a/identity-and-access/seats/mesh-grants/seat.json b/identity-and-access/seats/mesh-grants/seat.json new file mode 100644 index 0000000..8fdb2ca --- /dev/null +++ b/identity-and-access/seats/mesh-grants/seat.json @@ -0,0 +1,222 @@ +{ + "format": 1, + "seat": "mesh-grants", + "scope": "mesh", + "grain": "whole", + "domain": "Identity and access", + "decision": "novox/hq ADR 0656, ADR 0547, ADR 0636", + "description": "Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).", + "acts": [ + { + "step": "grant", + "on": "every" + } + ], + "verbs": [ + { + "name": "grants-for", + "description": "The grants a candidate would compose, per module: the grants it would add and remove against the branch's newest, each named by its subject and verb. The candidate's catalog half is taken by mesh-catalog's revision (design 47 G 441).", + "class": "read", + "input": { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": "the candidate's source revision" + }, + "run": { + "type": "string", + "description": "or the id of a run" + }, + "branch": { + "type": "string", + "description": "its watched branch" + } + }, + "required": [ + "branch" + ], + "additionalProperties": false + }, + "answer": { + "$ref": "#/defs/GrantsFor" + } + } + ], + "events": [ + { + "name": "wait-held", + "body": { + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "body": { + "$ref": "#/defs/Wait" + } + }, + { + "name": "filling", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "room", + "body": { + "$ref": "#/defs/Fill" + } + } + ], + "family": { + "name": "mesh-grants.events", + "max-age-days": 7 + }, + "defs": { + "Wait": { + "type": "object", + "description": "a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*)", + "properties": { + "step": { + "type": "string", + "description": "the step, grant", + "enum": [ + "grant" + ] + }, + "part": { + "type": "string", + "description": "the acting part waited for" + }, + "version": { + "type": "string", + "description": "its new version's fingerprint" + }, + "module": { + "type": "string", + "description": "the entry that waits" + }, + "fp": { + "type": "string", + "description": "the entry's fingerprint, whose grant waits" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "bound": { + "type": "string", + "description": "a duration such as 10m" + }, + "how": { + "type": "string", + "description": "on wait-ended: ran or released", + "enum": [ + "ran", + "released" + ] + }, + "by": { + "type": "string", + "description": "on a release, who released it and why" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266)" + } + }, + "required": [ + "step", + "part", + "version", + "module", + "since", + "bound", + "clock-from" + ] + }, + "Fill": { + "type": "object", + "description": "a store's fill against its cap", + "properties": { + "store": { + "type": "string", + "description": "the store" + }, + "bytes": { + "type": "integer" + }, + "cap": { + "type": "integer", + "description": "bytes" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "store", + "bytes", + "cap" + ] + }, + "Grant": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "the bus subject" + }, + "verb": { + "type": "string", + "description": "the verb or event the grant is for" + } + }, + "required": [ + "subject", + "verb" + ] + }, + "GrantsFor": { + "type": "object", + "description": "the grants a candidate would compose, per module, added and removed against the branch's newest", + "properties": { + "modules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "added": { + "type": "array", + "items": { + "$ref": "#/defs/Grant" + } + }, + "removed": { + "type": "array", + "items": { + "$ref": "#/defs/Grant" + } + } + }, + "required": [ + "module", + "added", + "removed" + ] + } + }, + "error": { + "type": "string", + "description": "why it could not be answered: the catalog half of the candidate is not held" + } + } + } + } +} diff --git a/identity-and-access/seats/mesh-vault/seat.json b/identity-and-access/seats/mesh-vault/seat.json index 749f148..7c93f1b 100644 --- a/identity-and-access/seats/mesh-vault/seat.json +++ b/identity-and-access/seats/mesh-vault/seat.json @@ -597,9 +597,7 @@ "name": "retire", "optional": true, "description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.", - "callers": [ - "seat:mesh-config" - ], + "callers": "the holder of the seat mesh-config alone", "input": { "type": "object", "properties": { From e84b1e371242fedc32e50691f211918e0841a966 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:42:06 +0100 Subject: [PATCH 10/62] C10: operator-channel lists a held-back ask with since when and serves ask-again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit asks gains the state held-back and the field held-since (no behind); the seat gains the verb ask-again, of class act, the operator's and the healers'. Builds: design 47 G §40, §83, §394, §403; design 46 §6 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../operator-channel/fixtures/states.json | 13 +++++ .../seats/operator-channel/seat.json | 49 +++++++++++++++++-- 2 files changed, 59 insertions(+), 3 deletions(-) diff --git a/operator-and-conversation/seats/operator-channel/fixtures/states.json b/operator-and-conversation/seats/operator-channel/fixtures/states.json index 66bc5de..0df2cf4 100644 --- a/operator-and-conversation/seats/operator-channel/fixtures/states.json +++ b/operator-and-conversation/seats/operator-channel/fixtures/states.json @@ -32,5 +32,18 @@ "opened": "2026-11-05T10:14:04Z", "state": "cancelled" } + }, + { + "name": "a fourth ask, the asker's oldest held back behind newer ones", + "of": "state:asks/.", + "given": { + "asker": "mesh-delivery-teller", + "expires": "2026-11-11T10:00:00Z", + "headline": "Check failed - merge into main", + "held-since": "2026-11-10T10:30:00Z", + "key": "mesh-delivery-teller.b-1", + "opened": "2026-11-10T10:00:00Z", + "state": "held-back" + } } ] diff --git a/operator-and-conversation/seats/operator-channel/seat.json b/operator-and-conversation/seats/operator-channel/seat.json index 2043c1d..7a11f0f 100644 --- a/operator-and-conversation/seats/operator-channel/seat.json +++ b/operator-and-conversation/seats/operator-channel/seat.json @@ -126,7 +126,7 @@ }, "state": { "type": "string", - "description": "open (open and held), ended or all; none is open when no key or since is given, else all" + "description": "open (open, held and held-back), ended or all; none is open when no key or since is given, else all" }, "since": { "type": "string", @@ -154,7 +154,11 @@ }, "state": { "type": "string", - "description": "how the ask stands: open, held, or how it ended (answered, expired, cancelled)" + "description": "how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled)" + }, + "held-since": { + "type": "string", + "description": "when the ask was held back, RFC 3339; present while its state is held-back" } }, "required": [ @@ -176,6 +180,41 @@ "asks" ] } + }, + { + "name": "ask-again", + "description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).", + "class": "act", + "callers": [ + "operator", + "healers" + ], + "input": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": ". of the held-back ask" + } + }, + "required": [ + "key" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "where the ask stands after it was offered", + "properties": { + "state": { + "type": "string" + }, + "error": { + "type": "string", + "description": "why it was not offered; set alone" + } + } + } } ], "accepts": [ @@ -248,7 +287,7 @@ }, "state": { "type": "string", - "description": "how it stands: open, chosen, expired, cancelled, replaced or refused" + "description": "how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused" }, "opened": { "type": "string", @@ -269,6 +308,10 @@ "type": "boolean", "description": "its asker has been told how it ended" }, + "held-since": { + "type": "string", + "description": "when the ask was held back, RFC 3339; present while its state is held-back" + }, "answer": { "type": "string", "description": "how it ended, in words" From 41690f7c3fb6fb3e2abc3a4f5079b341c9e9e57c Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:42:51 +0100 Subject: [PATCH 11/62] C11: mesh-conditions says findings-asked, resyncs one observer, and defines the finding bodies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The event findings-asked (ask, at, by, module; 7 days, 16 MiB), resync with an optional module and callers operator, healers and sessions, and the section bodies: the finding with its layout whole, finding-written, finding-cleared and findings-stated. The state findings is its owner's alone. Whether findings-views is a state of this definition waits on a question. Builds: design 47 G §383, §384, §390, §434, §437, §439 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../mesh-conditions/fixtures/events.json | 23 ++ .../seats/mesh-conditions/seat.json | 249 +++++++++++++++++- 2 files changed, 267 insertions(+), 5 deletions(-) create mode 100644 health-and-repair/seats/mesh-conditions/fixtures/events.json diff --git a/health-and-repair/seats/mesh-conditions/fixtures/events.json b/health-and-repair/seats/mesh-conditions/fixtures/events.json new file mode 100644 index 0000000..dde417e --- /dev/null +++ b/health-and-repair/seats/mesh-conditions/fixtures/events.json @@ -0,0 +1,23 @@ +[ + { + "name": "the keeper asks one observer to state its findings", + "of": "event:findings-asked", + "subject": "mesh.seat.mesh-conditions.event.findings-asked", + "given": { + "ask": "a-20261111t100000", + "at": "2026-11-11T10:00:00Z", + "by": "jochen", + "module": "mesh-host" + } + }, + { + "name": "the keeper asks every observer", + "of": "event:findings-asked", + "subject": "mesh.seat.mesh-conditions.event.findings-asked", + "given": { + "ask": "a-20261111t100100", + "at": "2026-11-11T10:01:00Z", + "by": "mesh-conditions" + } + } +] diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index 76f464c..7f9fb80 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -84,15 +84,26 @@ }, { "name": "resync", - "description": "Read every observer's findings again and raise and clear what differs from the open conditions: the recovery of a keeper that missed a change.", + "description": "Ask the observers to state their findings again, every one or the one named, and raise and clear what differs from the open conditions: the recovery of a keeper that missed a change. Each call is written in the hand-act log of the seat mesh-hand-acts (design 47 G 390).", "input": { - "properties": {}, - "type": "object" + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "ask this observer alone; none asks all" + } + }, + "additionalProperties": false }, "answer": { "type": "object", "description": "what was raised and cleared again" - } + }, + "callers": [ + "operator", + "healers", + "sessions" + ] } ], "events": [ @@ -113,6 +124,40 @@ "body": { "$ref": "#/defs/ConditionEvent" } + }, + { + "name": "findings-asked", + "keep": { + "max-age-days": 7, + "max-mib": 16 + }, + "body": { + "type": "object", + "description": "the keeper asks every observer, or one, to state its findings (design 47 G 384, 390)", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "who asked: the keeper, or the person or session that called resync" + }, + "module": { + "type": "string", + "description": "to ask one observer; none asks all" + } + }, + "required": [ + "ask", + "at", + "by" + ] + } } ], "family": { @@ -363,6 +408,14 @@ "at": { "type": "string", "format": "date-time" + }, + "owner": { + "type": "string", + "description": "the module the finding is about, when not the observer" + }, + "waiting-on": { + "type": "string", + "description": "what it waits on: a person, a part or a call" } }, "required": [ @@ -380,7 +433,7 @@ "description": "one finding of the observer that wrote it" } ], - "description": "every observer's findings, one key per finding; a key written raises or changes the condition of the same key, a key deleted clears it" + "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" } ], "defs": { @@ -643,5 +696,191 @@ "change" ] } + }, + "bodies": { + "Finding": { + "type": "object", + "description": "one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439)", + "properties": { + "kind": { + "type": "string" + }, + "scope": { + "type": "string", + "description": "the key's first part: .. (ADR 0564)" + }, + "id": { + "type": "string", + "description": "the key's second part" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "since when the finding stands" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string" + }, + "explanation": { + "type": "string" + }, + "subject": { + "$ref": "#/defs/Subject" + }, + "evidence": { + "type": "array", + "description": "newest first, at most 10", + "items": { + "$ref": "#/defs/Evidence" + } + }, + "source": { + "type": "string", + "description": "the row, probe or event that saw it" + }, + "observer": { + "type": "string", + "description": "the module that wrote it" + }, + "owner": { + "type": "string", + "description": "the module the finding is about, when not the observer" + }, + "waiting-on": { + "type": "string", + "description": "what it waits on: a person, a part or a call" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/defs/Action" + } + }, + "needs": { + "type": "string" + }, + "resolver": { + "type": "string", + "description": "self, operator, agent or healer:" + }, + "ref": { + "type": "string", + "description": "the key's last part when it is not the kind" + }, + "run": { + "type": "string", + "description": "what of its own saw it last" + } + }, + "required": [ + "kind", + "scope", + "id", + "at", + "since", + "severity", + "summary", + "subject", + "source", + "observer" + ] + }, + "FindingWritten": { + "$ref": "#/bodies/Finding" + }, + "FindingCleared": { + "type": "object", + "description": "an observer no longer observes a finding", + "properties": { + "kind": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "id": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "why": { + "type": "string" + } + }, + "required": [ + "kind", + "scope", + "id", + "at", + "why" + ] + }, + "FindingsStated": { + "type": "object", + "description": "every finding an observer observes now, at its start and when asked (design 47 G 384, 439)", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "asked": { + "type": "string", + "description": "the ask it answers; none at a start" + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/bodies/Finding" + } + }, + "pending": { + "type": "array", + "description": "the keys the observer cannot judge yet since its start, with their since and bound", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "bound": { + "type": "string", + "description": "a duration such as 5m" + } + }, + "required": [ + "key", + "since", + "bound" + ] + } + } + }, + "required": [ + "at", + "findings", + "pending" + ] + } } } From 70b91f7a79cbddc67f16177830dc609b3457cf64 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:43:02 +0100 Subject: [PATCH 12/62] C12: mesh-watchdogs says machine-away and machine-back MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject parts name the machine, not the publisher; kept 90 days and 16 MiB. Builds: design 47 G §389, §436 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../seats/mesh-watchdogs/fixtures/events.json | 24 ++++++ .../seats/mesh-watchdogs/seat.json | 76 +++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 health-and-repair/seats/mesh-watchdogs/fixtures/events.json diff --git a/health-and-repair/seats/mesh-watchdogs/fixtures/events.json b/health-and-repair/seats/mesh-watchdogs/fixtures/events.json new file mode 100644 index 0000000..2c50557 --- /dev/null +++ b/health-and-repair/seats/mesh-watchdogs/fixtures/events.json @@ -0,0 +1,24 @@ +[ + { + "name": "a machine's presence expired", + "of": "event:machine-away", + "subject": "mesh.seat.mesh-watchdogs.event.machine-away.g14", + "given": { + "v": 1, + "machine": "g14", + "at": "2026-11-11T10:00:00Z", + "last-heard": "2026-11-11T09:58:00Z" + } + }, + { + "name": "a machine heard again", + "of": "event:machine-back", + "subject": "mesh.seat.mesh-watchdogs.event.machine-back.g14", + "given": { + "v": 1, + "machine": "g14", + "at": "2026-11-11T10:30:00Z", + "last-heard": "2026-11-11T10:30:00Z" + } + } +] diff --git a/health-and-repair/seats/mesh-watchdogs/seat.json b/health-and-repair/seats/mesh-watchdogs/seat.json index 1efe7a8..d94c9a1 100644 --- a/health-and-repair/seats/mesh-watchdogs/seat.json +++ b/health-and-repair/seats/mesh-watchdogs/seat.json @@ -159,6 +159,82 @@ } } ], + "events": [ + { + "name": "machine-away", + "subject": "machine-away.", + "keep": { + "max-age-days": 90, + "max-mib": 16 + }, + "body": { + "type": "object", + "description": "the watchman's presence key of a machine expired (ADR 0564 4); published by the holder of this seat alone for another machine (design 47 G 436)", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "machine": { + "type": "string", + "description": "the machine whose presence changed" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "last-heard": { + "type": "string", + "format": "date-time", + "description": "when the machine was last heard" + } + }, + "required": [ + "v", + "machine", + "at", + "last-heard" + ] + } + }, + { + "name": "machine-back", + "subject": "machine-back.", + "keep": { + "max-age-days": 90, + "max-mib": 16 + }, + "body": { + "type": "object", + "description": "a machine is heard again after it was away", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "machine": { + "type": "string", + "description": "the machine whose presence changed" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "last-heard": { + "type": "string", + "format": "date-time", + "description": "when the machine was last heard" + } + }, + "required": [ + "v", + "machine", + "at", + "last-heard" + ] + } + } + ], "states": [ { "name": "presence", From 26ef347d2790585459f72af0b5780a2cb9af4599 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:43:17 +0100 Subject: [PATCH 13/62] C13: every contracts manifest says version 0.1 and no artifact says series MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §368, §411 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- health-and-repair/module.json | 18 +++--------------- identity-and-access/module.json | 14 +++----------- module.json | 19 ++++--------------- operator-and-conversation/module.json | 7 ++----- provisioning/module.json | 7 ++----- 5 files changed, 14 insertions(+), 51 deletions(-) diff --git a/health-and-repair/module.json b/health-and-repair/module.json index d712009..db73ae1 100644 --- a/health-and-repair/module.json +++ b/health-and-repair/module.json @@ -1,6 +1,6 @@ { "module": "mesh-health-and-repair-contracts", - "version": "1", + "version": "0.1", "build": { "artifacts": [ { @@ -10,7 +10,6 @@ "paths": [ "go/seats/meshconditions" ], - "series": "0.1", "generated-from": "." }, { @@ -20,7 +19,6 @@ "paths": [ "go/seats/meshselfcheck" ], - "series": "0.1", "generated-from": "." }, { @@ -30,7 +28,6 @@ "paths": [ "go/seats/meshhealers" ], - "series": "0.1", "generated-from": "." }, { @@ -40,7 +37,6 @@ "paths": [ "go/seats/meshwatchdogs" ], - "series": "0.1", "generated-from": "." }, { @@ -50,7 +46,6 @@ "paths": [ "go/seats/meshhandacts" ], - "series": "0.1", "generated-from": "." }, { @@ -59,8 +54,7 @@ "language": "go", "paths": [ "go/clients/meshhandactsclient" - ], - "series": "0.1" + ] }, { "name": "go-meshconditionsclient", @@ -68,8 +62,7 @@ "language": "go", "paths": [ "go/clients/meshconditionsclient" - ], - "series": "0.1" + ] }, { "name": "ts-meshconditions", @@ -78,7 +71,6 @@ "paths": [ "ts/seats/meshconditions" ], - "series": "0.1", "generated-from": "." }, { @@ -88,7 +80,6 @@ "paths": [ "ts/seats/meshselfcheck" ], - "series": "0.1", "generated-from": "." }, { @@ -98,7 +89,6 @@ "paths": [ "ts/seats/meshhealers" ], - "series": "0.1", "generated-from": "." }, { @@ -108,7 +98,6 @@ "paths": [ "ts/seats/meshwatchdogs" ], - "series": "0.1", "generated-from": "." }, { @@ -118,7 +107,6 @@ "paths": [ "ts/seats/meshhandacts" ], - "series": "0.1", "generated-from": "." } ] diff --git a/identity-and-access/module.json b/identity-and-access/module.json index 4f3b3f3..c9dcc25 100644 --- a/identity-and-access/module.json +++ b/identity-and-access/module.json @@ -1,6 +1,6 @@ { "module": "mesh-identity-and-access-contracts", - "version": "1", + "version": "0.1", "build": { "artifacts": [ { @@ -10,7 +10,6 @@ "paths": [ "go/seats/meshvault" ], - "series": "0.1", "generated-from": "." }, { @@ -20,7 +19,6 @@ "paths": [ "go/seats/meshnodeenroller" ], - "series": "0.1", "generated-from": "." }, { @@ -30,7 +28,6 @@ "paths": [ "go/seats/meshgrants" ], - "series": "0.1", "generated-from": "." }, { @@ -39,8 +36,7 @@ "language": "go", "paths": [ "go/clients/meshvaultclient" - ], - "series": "0.1" + ] }, { "name": "go-meshnodeenrollerclient", @@ -48,8 +44,7 @@ "language": "go", "paths": [ "go/clients/meshnodeenrollerclient" - ], - "series": "0.1" + ] }, { "name": "ts-meshvault", @@ -58,7 +53,6 @@ "paths": [ "ts/seats/meshvault" ], - "series": "0.1", "generated-from": "." }, { @@ -68,7 +62,6 @@ "paths": [ "ts/seats/meshnodeenroller" ], - "series": "0.1", "generated-from": "." }, { @@ -78,7 +71,6 @@ "paths": [ "ts/seats/meshgrants" ], - "series": "0.1", "generated-from": "." } ] diff --git a/module.json b/module.json index 1d7d5c0..bfc775d 100644 --- a/module.json +++ b/module.json @@ -1,6 +1,6 @@ { "module": "mesh-contracts", - "version": "1", + "version": "0.1", "slug": "contracts", "build": { "artifacts": [ @@ -10,8 +10,7 @@ "language": "go", "paths": [ "go/clients/meshconfigclient" - ], - "series": "0.1" + ] }, { "name": "go-nodeengineclient", @@ -19,8 +18,7 @@ "language": "go", "paths": [ "go/clients/nodeengineclient" - ], - "series": "0.1" + ] }, { "name": "go-meshbroker", @@ -29,7 +27,6 @@ "paths": [ "go/seats/meshbroker" ], - "series": "0.1", "generated-from": "." }, { @@ -39,7 +36,6 @@ "paths": [ "go/seats/meshconfig" ], - "series": "0.1", "generated-from": "." }, { @@ -49,7 +45,6 @@ "paths": [ "go/seats/nodeengine" ], - "series": "0.1", "generated-from": "." }, { @@ -59,7 +54,6 @@ "paths": [ "ts/seats/meshbroker" ], - "series": "0.1", "generated-from": "." }, { @@ -69,7 +63,6 @@ "paths": [ "ts/seats/meshconfig" ], - "series": "0.1", "generated-from": "." }, { @@ -79,7 +72,6 @@ "paths": [ "ts/seats/nodeengine" ], - "series": "0.1", "generated-from": "." }, { @@ -89,7 +81,6 @@ "paths": [ "go/seats/meshmoduleassigner" ], - "series": "0.1", "generated-from": "." }, { @@ -98,8 +89,7 @@ "language": "go", "paths": [ "go/clients/meshmoduleassignerclient" - ], - "series": "0.1" + ] }, { "name": "ts-meshmoduleassigner", @@ -108,7 +98,6 @@ "paths": [ "ts/seats/meshmoduleassigner" ], - "series": "0.1", "generated-from": "." } ] diff --git a/operator-and-conversation/module.json b/operator-and-conversation/module.json index 2498f04..ac3dad3 100644 --- a/operator-and-conversation/module.json +++ b/operator-and-conversation/module.json @@ -1,6 +1,6 @@ { "module": "mesh-operator-and-conversation-contracts", - "version": "1", + "version": "0.1", "build": { "artifacts": [ { @@ -10,7 +10,6 @@ "paths": [ "go/seats/operatorchannel" ], - "series": "0.1", "generated-from": "." }, { @@ -19,8 +18,7 @@ "language": "go", "paths": [ "go/clients/operatorchannelclient" - ], - "series": "0.1" + ] }, { "name": "ts-operatorchannel", @@ -29,7 +27,6 @@ "paths": [ "ts/seats/operatorchannel" ], - "series": "0.1", "generated-from": "." } ] diff --git a/provisioning/module.json b/provisioning/module.json index f5796f5..5135607 100644 --- a/provisioning/module.json +++ b/provisioning/module.json @@ -1,6 +1,6 @@ { "module": "mesh-provisioning-contracts", - "version": "1", + "version": "0.1", "build": { "artifacts": [ { @@ -10,7 +10,6 @@ "paths": [ "go/seats/meshprovisioner" ], - "series": "0.1", "generated-from": "." }, { @@ -19,8 +18,7 @@ "language": "go", "paths": [ "go/clients/meshprovisionerclient" - ], - "series": "0.1" + ] }, { "name": "ts-meshprovisioner", @@ -29,7 +27,6 @@ "paths": [ "ts/seats/meshprovisioner" ], - "series": "0.1", "generated-from": "." } ] From 77e583be44750d8dfa52685811b2d7101afbfeee Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:44:34 +0100 Subject: [PATCH 14/62] C3, C5, C11 (answers): mesh-broker's write verbs name module:nats, node-engine's seat-list verbs the callers its code names, mesh-conditions declares findings-views MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit create and apply are of class act; recreate and drop of class warrant; all four called by module:nats. seat-list and seat-list-again name persons, sessions and healers as SeatListCallers does. Builds: design 47 G §336, §388, §391, §392, §393 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../seats/mesh-conditions/seat.json | 60 +++++++++++++++++++ seats/mesh-broker/seat.json | 28 ++++++--- seats/node-engine/seat.json | 4 +- 3 files changed, 83 insertions(+), 9 deletions(-) diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index 7f9fb80..e5fa435 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -434,6 +434,66 @@ } ], "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" + }, + { + "name": "findings-views", + "template": "state", + "description": "the keeper's sources: one key per observer and node, its last stated set with its at, its pending keys and the open asks; deleted when the module leaves the catalog or the node (design 47 G 388)", + "key-forms": [ + { + "key": ".", + "description": "one observer on one node", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "observer": { + "type": "string" + }, + "node": { + "type": "string" + }, + "stated": { + "type": "object", + "description": "the last findings-stated set", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/bodies/Finding" + } + } + } + }, + "pending": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the keys it cannot judge yet" + }, + "asks": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the open asks" + } + }, + "required": [ + "v", + "observer", + "node" + ] + } + } + ] } ], "defs": { diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index baff7db..a118c0e 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -143,43 +143,54 @@ { "name": "create", "description": "Create one entry now.", - "callers": "the bus module's own process only", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Entry" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "act" }, { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": "the bus module's own process only", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Named" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "act" }, { "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.", - "callers": "the bus module's process, on the operator's warrant", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Warranted" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "warrant" }, { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": "the bus module's process, on the operator's warrant", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Warranted" }, @@ -199,7 +210,8 @@ "dropped" ] }, - "optional": true + "optional": true, + "class": "warrant" }, { "name": "snapshot-kept", diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 1a08c68..63159fe 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -686,6 +686,7 @@ "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", "callers": [ "persons", + "sessions", "healers" ], "input": { @@ -700,7 +701,8 @@ "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", "callers": [ - "operator", + "persons", + "sessions", "healers" ], "input": { From 44492ce5556676cb6705b9e0c64172bca5aa7365 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:44:40 +0100 Subject: [PATCH 15/62] C3 (repair): mesh-vault retire names seat:mesh-config again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The checkout of C9 had laid back the earlier text. Builds: design 47 G §336, §392 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- identity-and-access/seats/mesh-vault/seat.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/identity-and-access/seats/mesh-vault/seat.json b/identity-and-access/seats/mesh-vault/seat.json index 7c93f1b..749f148 100644 --- a/identity-and-access/seats/mesh-vault/seat.json +++ b/identity-and-access/seats/mesh-vault/seat.json @@ -597,7 +597,9 @@ "name": "retire", "optional": true, "description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.", - "callers": "the holder of the seat mesh-config alone", + "callers": [ + "seat:mesh-config" + ], "input": { "type": "object", "properties": { From e529c372d0cc8394f00bf64af632ecef5f152d67 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:45:30 +0100 Subject: [PATCH 16/62] C14: the generated Go and TypeScript of every seat follow the definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Written by seatgen at c62650e4 (GEN3) with mesh-sdk b19fc7fa (reader release): the seat mesh-grants new, every TypeScript contract as index.js with index.d.ts, events with subject and stream. mesh-watchdogs gains its family, which a definition with events needs. Written with the reader as it is: the field needs-approval (node-login-shell) and the section bodies (mesh-conditions) are unknown to it, so they were laid aside for the run; nothing generated carries either. Builds: design 47 G §339, §341, §261, §389 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/seats/meshbroker/contract.go | 138 +++++++- go/seats/meshbroker/contract_test.go | 6 + go/seats/meshmoduleassigner/contract.go | 20 +- go/seats/meshmoduleassigner/contract_test.go | 12 + go/seats/nodeengine/contract.go | 131 +++++++- go/seats/nodeengine/contract_test.go | 18 + .../go/seats/meshconditions/contract.go | 87 ++++- .../go/seats/meshconditions/contract_test.go | 4 + .../go/seats/meshwatchdogs/contract.go | 60 ++++ .../go/seats/meshwatchdogs/contract_test.go | 4 + .../seats/mesh-watchdogs/seat.json | 4 + .../{src/index.ts => index.d.ts} | 112 ++++--- .../ts/seats/meshconditions/index.js | 86 +++++ .../ts/seats/meshconditions/package-lock.json | 4 +- .../ts/seats/meshconditions/package.json | 13 +- .../meshhandacts/{src/index.ts => index.d.ts} | 60 ++-- .../ts/seats/meshhandacts/index.js | 59 ++++ .../ts/seats/meshhandacts/package-lock.json | 4 +- .../ts/seats/meshhandacts/package.json | 13 +- .../meshhealers/{src/index.ts => index.d.ts} | 56 ++-- .../ts/seats/meshhealers/index.js | 55 ++++ .../ts/seats/meshhealers/package-lock.json | 4 +- .../ts/seats/meshhealers/package.json | 13 +- .../{src/index.ts => index.d.ts} | 20 +- .../ts/seats/meshselfcheck/index.js | 19 ++ .../ts/seats/meshselfcheck/package-lock.json | 4 +- .../ts/seats/meshselfcheck/package.json | 13 +- .../{src/index.ts => index.d.ts} | 133 ++++---- .../ts/seats/meshwatchdogs/index.js | 117 +++++++ .../ts/seats/meshwatchdogs/package-lock.json | 4 +- .../ts/seats/meshwatchdogs/package.json | 13 +- .../go/seats/meshgrants/contract.go | 139 ++++++++ .../go/seats/meshgrants/contract_test.go | 58 ++++ .../go/seats/meshgrants/go.mod | 3 + .../ts/seats/meshgrants/index.d.ts | 105 ++++++ .../ts/seats/meshgrants/index.js | 27 ++ .../ts/seats/meshgrants/package-lock.json | 12 + .../ts/seats/meshgrants/package.json | 18 + .../{src/index.ts => index.d.ts} | 80 ++--- .../ts/seats/meshnodeenroller/index.js | 73 +++++ .../seats/meshnodeenroller/package-lock.json | 4 +- .../ts/seats/meshnodeenroller/package.json | 13 +- .../meshvault/{src/index.ts => index.d.ts} | 151 +++------ .../ts/seats/meshvault/index.js | 130 ++++++++ .../ts/seats/meshvault/package-lock.json | 4 +- .../ts/seats/meshvault/package.json | 13 +- .../go/seats/operatorchannel/contract.go | 36 +- .../go/seats/operatorchannel/contract_test.go | 2 + .../{src/index.ts => index.d.ts} | 119 ++++--- .../ts/seats/operatorchannel/index.js | 84 +++++ .../seats/operatorchannel/package-lock.json | 4 +- .../ts/seats/operatorchannel/package.json | 13 +- .../{src/index.ts => index.d.ts} | 79 +---- .../ts/seats/meshprovisioner/index.js | 84 +++++ .../seats/meshprovisioner/package-lock.json | 4 +- .../ts/seats/meshprovisioner/package.json | 13 +- .../meshbroker/{src/index.ts => index.d.ts} | 181 ++++++++-- ts/seats/meshbroker/index.js | 51 +++ ts/seats/meshbroker/package.json | 11 +- .../meshconfig/{src/index.ts => index.d.ts} | 100 ++---- ts/seats/meshconfig/index.js | 97 ++++++ ts/seats/meshconfig/package.json | 11 +- .../{src/index.ts => index.d.ts} | 185 +++-------- ts/seats/meshmoduleassigner/index.js | 180 ++++++++++ ts/seats/meshmoduleassigner/package.json | 11 +- .../nodeengine/{src/index.ts => index.d.ts} | 310 +++++++++--------- ts/seats/nodeengine/index.js | 218 ++++++++++++ ts/seats/nodeengine/package.json | 11 +- 68 files changed, 2951 insertions(+), 969 deletions(-) rename health-and-repair/ts/seats/meshconditions/{src/index.ts => index.d.ts} (68%) create mode 100644 health-and-repair/ts/seats/meshconditions/index.js rename health-and-repair/ts/seats/meshhandacts/{src/index.ts => index.d.ts} (71%) create mode 100644 health-and-repair/ts/seats/meshhandacts/index.js rename health-and-repair/ts/seats/meshhealers/{src/index.ts => index.d.ts} (69%) create mode 100644 health-and-repair/ts/seats/meshhealers/index.js rename health-and-repair/ts/seats/meshselfcheck/{src/index.ts => index.d.ts} (79%) create mode 100644 health-and-repair/ts/seats/meshselfcheck/index.js rename health-and-repair/ts/seats/meshwatchdogs/{src/index.ts => index.d.ts} (64%) create mode 100644 health-and-repair/ts/seats/meshwatchdogs/index.js create mode 100644 identity-and-access/go/seats/meshgrants/contract.go create mode 100644 identity-and-access/go/seats/meshgrants/contract_test.go create mode 100644 identity-and-access/go/seats/meshgrants/go.mod create mode 100644 identity-and-access/ts/seats/meshgrants/index.d.ts create mode 100644 identity-and-access/ts/seats/meshgrants/index.js create mode 100644 identity-and-access/ts/seats/meshgrants/package-lock.json create mode 100644 identity-and-access/ts/seats/meshgrants/package.json rename identity-and-access/ts/seats/meshnodeenroller/{src/index.ts => index.d.ts} (70%) create mode 100644 identity-and-access/ts/seats/meshnodeenroller/index.js rename identity-and-access/ts/seats/meshvault/{src/index.ts => index.d.ts} (78%) create mode 100644 identity-and-access/ts/seats/meshvault/index.js rename operator-and-conversation/ts/seats/operatorchannel/{src/index.ts => index.d.ts} (81%) create mode 100644 operator-and-conversation/ts/seats/operatorchannel/index.js rename provisioning/ts/seats/meshprovisioner/{src/index.ts => index.d.ts} (68%) create mode 100644 provisioning/ts/seats/meshprovisioner/index.js rename ts/seats/meshbroker/{src/index.ts => index.d.ts} (55%) create mode 100644 ts/seats/meshbroker/index.js rename ts/seats/meshconfig/{src/index.ts => index.d.ts} (58%) create mode 100644 ts/seats/meshconfig/index.js rename ts/seats/meshmoduleassigner/{src/index.ts => index.d.ts} (71%) create mode 100644 ts/seats/meshmoduleassigner/index.js rename ts/seats/nodeengine/{src/index.ts => index.d.ts} (81%) create mode 100644 ts/seats/nodeengine/index.js diff --git a/go/seats/meshbroker/contract.go b/go/seats/meshbroker/contract.go index 5313b13..fa7fad7 100644 --- a/go/seats/meshbroker/contract.go +++ b/go/seats/meshbroker/contract.go @@ -3,18 +3,22 @@ // 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" + VerbList = "list" + VerbShow = "show" + VerbCheck = "check" + VerbOrphans = "orphans" + VerbCreate = "create" + VerbApply = "apply" + VerbRecreate = "recreate" + VerbDrop = "drop" + VerbSnapshotKept = "snapshot-kept" + VerbRestoreKept = "restore-kept" ) const ( @@ -31,7 +35,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} + return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop, VerbSnapshotKept, VerbRestoreKept} } // Events is every event published on the seat's subject: a new copy each call. @@ -72,10 +76,30 @@ 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). type Binding struct { // the entry's name on the bus BusName string `json:"bus-name"` + // the bus name of the state's -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 @@ -183,6 +207,44 @@ 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 @@ -335,6 +397,64 @@ 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 diff --git a/go/seats/meshbroker/contract_test.go b/go/seats/meshbroker/contract_test.go index 03c1f9c..84b09e9 100644 --- a/go/seats/meshbroker/contract_test.go +++ b/go/seats/meshbroker/contract_test.go @@ -41,6 +41,12 @@ 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}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/go/seats/meshmoduleassigner/contract.go b/go/seats/meshmoduleassigner/contract.go index e4ca190..2451180 100644 --- a/go/seats/meshmoduleassigner/contract.go +++ b/go/seats/meshmoduleassigner/contract.go @@ -423,9 +423,13 @@ type NodeDecided struct { // PlacedModule is one module placed on a node. type PlacedModule struct { // by provision, the provider each requirement that keeps data is bound to - Bindings map[string]Provider `json:"bindings,omitempty"` - HasLayer bool `json:"has-layer,omitempty"` - HasMeshWide bool `json:"has-mesh-wide,omitempty"` + Bindings map[string]Provider `json:"bindings,omitempty"` + // the watched branch this node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14) + Branch string `json:"branch,omitempty"` + // the fingerprint of the build the node runs; absent, the newest delivered of the branch (design 47 G 78, 402) + Build string `json:"build,omitempty"` + HasLayer bool `json:"has-layer,omitempty"` + HasMeshWide bool `json:"has-mesh-wide,omitempty"` // this node's settings layer of the module's assignments Layer map[string]any `json:"layer,omitempty"` // the whole mesh's settings layer of the module's assignments @@ -475,9 +479,13 @@ type ProposalChangeKeys struct { // ProposalChange is one change of a proposal. type ProposalChange struct { Bindings map[string]Provider `json:"bindings,omitempty"` - Claim string `json:"claim,omitempty"` - Decided *NodeDecided `json:"decided,omitempty"` - Field string `json:"field,omitempty"` + // for place, the watched branch the node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14) + Branch string `json:"branch,omitempty"` + // for place, the build of that branch the node runs, a return to an earlier build being this one value; absent, the newest delivered of the branch (ADR 0666 section 24) + Build string `json:"build,omitempty"` + Claim string `json:"claim,omitempty"` + Decided *NodeDecided `json:"decided,omitempty"` + Field string `json:"field,omitempty"` // the public halves of a joining node's keys Keys *ProposalChangeKeys `json:"keys,omitempty"` Kind string `json:"kind,omitempty"` diff --git a/go/seats/meshmoduleassigner/contract_test.go b/go/seats/meshmoduleassigner/contract_test.go index 29ddac3..b5f4fa0 100644 --- a/go/seats/meshmoduleassigner/contract_test.go +++ b/go/seats/meshmoduleassigner/contract_test.go @@ -41,12 +41,24 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, + {name: "a module's key on a watched branch and a build", subject: "", given: "{\"node\":\"ace\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", wire: "{\"node\":\"ace\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", + decode: func(b []byte) (any, error) { + var v AssignmentsByNodeModuleValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, {name: "an open proposal", subject: "", given: "{\"at\":\"2026-11-05T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"module\":\"plex\",\"node\":\"ace\",\"op\":\"place\",\"ports\":{\"32400\":32400}}],\"id\":\"p-20261105t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"move plex\"}", wire: "{\"at\":\"2026-11-05T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"module\":\"plex\",\"node\":\"ace\",\"op\":\"place\",\"ports\":{\"32400\":32400}}],\"id\":\"p-20261105t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"move plex\"}", decode: func(b []byte) (any, error) { var v ProposalsByProposalValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, + {name: "a proposal placing a module on a watched branch at an earlier build", subject: "", given: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", wire: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", + decode: func(b []byte) (any, error) { + var v ProposalsByProposalValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, {name: "a candidate", subject: "", given: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", wire: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", decode: func(b []byte) (any, error) { var v CandidatesByProposalNodeValue diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 26dc404..081ecee 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -1,6 +1,6 @@ // Code generated by seatgen from the seat definitions; DO NOT EDIT. -// Package nodeengine is the contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token. +// Package nodeengine is the contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2). package nodeengine import ( @@ -28,6 +28,7 @@ const ( VerbManifestReads = "manifest-reads" VerbSeatList = "seat-list" VerbSeatListAgain = "seat-list-again" + VerbProcessBuilds = "process-builds" ) const ( @@ -35,16 +36,19 @@ const ( EventDone = "done" EventRefused = "refused" EventManifestReadsChanged = "manifest-reads-changed" + EventComposed = "composed" + EventRunning = "running" + EventCapabilitiesChanged = "capabilities-changed" ) // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain} + return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbProcessBuilds} } // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged} + return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged, EventComposed, EventRunning, EventCapabilitiesChanged} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -67,6 +71,31 @@ func SubjectManifestReadsChanged(caller string) string { return "mesh.seat.node-engine.event.manifest-reads-changed." + caller } +// SubjectComposed is where composed is published, on mesh.seat.node-engine.event.composed.. +func SubjectComposed(node string) string { return "mesh.seat.node-engine.event.composed." + node } + +// SubjectComposedAll hears every composed. +const SubjectComposedAll = "mesh.seat.node-engine.event.composed.*" + +// StreamRunning is the stream running is kept in. +const StreamRunning = "SEAT_node-engine_running" + +// SubjectRunning is where running is published, on mesh.seat.node-engine.event.running... +func SubjectRunning(node, module string) string { + return "mesh.seat.node-engine.event.running." + node + "." + module +} + +// SubjectRunningAll hears every running. +const SubjectRunningAll = "mesh.seat.node-engine.event.running.*.*" + +// SubjectCapabilitiesChanged is where capabilities-changed is published, on mesh.seat.node-engine.event.capabilities-changed.. +func SubjectCapabilitiesChanged(node string) string { + return "mesh.seat.node-engine.event.capabilities-changed." + node +} + +// SubjectCapabilitiesChangedAll hears every capabilities-changed. +const SubjectCapabilitiesChangedAll = "mesh.seat.node-engine.event.capabilities-changed.*" + const ( StateHave = "have" StateComposed = "composed" @@ -523,6 +552,34 @@ type CandidateRefusal struct { Why string `json:"why"` } +// CapabilitiesChanged is a node's capabilities changed, which the assigner places by. +type CapabilitiesChanged struct { + // when, RFC 3339 + At time.Time `json:"at"` + // its capabilities now + Capabilities []string `json:"capabilities"` + // the node + Node string `json:"node"` + // the layout's version + V int64 `json:"v"` +} + +// Composed is an entry composed on a node (design 47 *What each step says*). +type Composed struct { + // when, RFC 3339 + At time.Time `json:"at"` + // the digest of the composition (design 47 G 404) + Digest string `json:"digest"` + // the fingerprint of the want composed + Fingerprint string `json:"fingerprint"` + // the module + Module string `json:"module"` + // the node + Node string `json:"node"` + // the layout's version + V int64 `json:"v"` +} + // DeclaredGroup is a group. type DeclaredGroup struct { Gid int64 `json:"gid"` @@ -742,6 +799,38 @@ type PlacedDataItem struct { Protection string `json:"protection,omitempty"` } +// ProcessBuild is the build one process of a module was started with. +type ProcessBuild struct { + // the fingerprint handed to it in MESH_FINGERPRINT; empty when it was started without one + Fingerprint string `json:"fingerprint,omitempty"` + // service or container + Kind string `json:"kind"` + // the module + Module string `json:"module"` + // the service's unit or the container's name + Process string `json:"process"` + // when it was started, RFC 3339 + Started *time.Time `json:"started,omitempty"` + // why its build is unknown: started before the node-engine handed MESH_FINGERPRINT, or the value could not be read + Unknown string `json:"unknown,omitempty"` +} + +// The values of ProcessBuild's kind. +const ( + ProcessBuildKindService = "service" + ProcessBuildKindContainer = "container" +) + +// ProcessBuilds is what process-builds answers. +type ProcessBuilds struct { + // why they could not be read + Error string `json:"error,omitempty"` + // the node + Node string `json:"node"` + // every process the node-engine started, by module + Processes []ProcessBuild `json:"processes"` +} + // PullWait is the pull from a store a failed apply waits on. type PullWait struct { // when the pull began @@ -796,6 +885,24 @@ type RootVerdict struct { Why string `json:"why"` } +// Running is a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit. +type Running struct { + // when it was seen running healthy, RFC 3339 + At time.Time `json:"at"` + // the fingerprint of the build it runs; none with stopped + Fingerprint string `json:"fingerprint,omitempty"` + // the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half + Manifest string `json:"manifest,omitempty"` + // the module + Module string `json:"module"` + // the node + Node string `json:"node"` + // true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there + Stopped bool `json:"stopped,omitempty"` + // the layout's version + V int64 `json:"v"` +} + // Said is the answer of a read-only judgement. type Said struct { // the node @@ -1217,6 +1324,15 @@ type SeatListAgainInput struct { // SeatListAgainAnswer is what seat-list-again answers. type SeatListAgainAnswer = SeatList +// ProcessBuildsInput is what process-builds takes. +type ProcessBuildsInput struct { + // only this module's processes + Module string `json:"module,omitempty"` +} + +// ProcessBuildsAnswer is what process-builds answers. +type ProcessBuildsAnswer = ProcessBuilds + // AskedEvent is the body of the event asked. type AskedEvent = ActSaid @@ -1229,6 +1345,15 @@ type RefusedEvent = ActSaid // ManifestReadsChangedEvent is the body of the event manifest-reads-changed. type ManifestReadsChangedEvent = ManifestReadsChanged +// ComposedEvent is the body of the event composed. +type ComposedEvent = Composed + +// RunningEvent is the body of the event running. +type RunningEvent = Running + +// CapabilitiesChangedEvent is the body of the event capabilities-changed. +type CapabilitiesChangedEvent = CapabilitiesChanged + // HaveByNodeModuleValue is one value of the state have under the key .. type HaveByNodeModuleValue struct { Build string `json:"build,omitempty"` diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index 5ca811b..e2ed2d8 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -35,6 +35,18 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.manifest-reads-changed\\.[A-Za-z0-9_-]+$")}, + {name: "composed is said", subject: "mesh.seat.node-engine.event.composed.ace", given: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + decode: func(b []byte) (any, error) { var v ComposedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.composed\\.[^.*> ]+$")}, + {name: "running is said, its node and module in its subject", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "running says a module stopped on the node, with no fingerprint", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", + decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "capabilities-changed is said", subject: "mesh.seat.node-engine.event.capabilities-changed.ace", given: "{\"at\":\"2026-11-09T20:02:00Z\",\"capabilities\":[\"build-go\",\"docker\"],\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:02:00Z\",\"capabilities\":[\"build-go\",\"docker\"],\"node\":\"ace\",\"v\":1}", + decode: func(b []byte) (any, error) { + var v CapabilitiesChangedEvent + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.capabilities-changed\\.[^.*> ]+$")}, {name: "the finding of a seat list unread, as the engine writes it", subject: "", given: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", wire: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a node's packages, present and absent (captured from ace, shortened)", subject: "", given: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}", wire: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}", @@ -91,6 +103,12 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v SeatListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "seat-list-again answers the error when the read failed", subject: "", given: "{\"error\":\"seatlist: no answer\",\"health\":\"the seat list is held from the bootstrap\",\"status\":{\"heard\":false,\"held\":[{\"seat\":\"node-engine\",\"source\":\"bootstrap\"}],\"waiting\":[\"node-engine\"]}}", wire: "{\"error\":\"seatlist: no answer\",\"health\":\"the seat list is held from the bootstrap\",\"status\":{\"heard\":false,\"held\":[{\"seat\":\"node-engine\",\"source\":\"bootstrap\"}],\"waiting\":[\"node-engine\"]}}", decode: func(b []byte) (any, error) { var v SeatListAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "process-builds asks one module", subject: "", given: "{\"module\":\"nats\"}", wire: "{\"module\":\"nats\"}", + decode: func(b []byte) (any, error) { var v ProcessBuildsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "process-builds answers each process's build", subject: "", given: "{\"node\":\"ace\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", wire: "{\"node\":\"ace\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", + decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "process-builds answers an error", subject: "", given: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", wire: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", + decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/health-and-repair/go/seats/meshconditions/contract.go b/health-and-repair/go/seats/meshconditions/contract.go index 0757680..7406782 100644 --- a/health-and-repair/go/seats/meshconditions/contract.go +++ b/health-and-repair/go/seats/meshconditions/contract.go @@ -7,6 +7,7 @@ import ( "bytes" "encoding/json" "errors" + "strings" "time" ) @@ -23,6 +24,7 @@ const ( EventConditionRaised = "condition-raised" EventConditionChanged = "condition-changed" EventConditionCleared = "condition-cleared" + EventFindingsAsked = "findings-asked" ) // Verbs is every verb the seat serves, in its definition's order: a new copy each call. @@ -32,7 +34,7 @@ func Verbs() []string { // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventConditionRaised, EventConditionChanged, EventConditionCleared} + return []string{EventConditionRaised, EventConditionChanged, EventConditionCleared, EventFindingsAsked} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -50,9 +52,16 @@ const SubjectConditionChanged = "mesh.seat.mesh-conditions.event.condition-chang // SubjectConditionCleared is where condition-cleared is published. const SubjectConditionCleared = "mesh.seat.mesh-conditions.event.condition-cleared" +// StreamFindingsAsked is the stream findings-asked is kept in. +const StreamFindingsAsked = "SEAT_mesh-conditions_findings-asked" + +// SubjectFindingsAsked is where findings-asked is published. +const SubjectFindingsAsked = "mesh.seat.mesh-conditions.event.findings-asked" + const ( - StateConditions = "conditions" - StateFindings = "findings" + StateConditions = "conditions" + StateFindings = "findings" + StateFindingsViews = "findings-views" ) // ConditionsByKeyKey is the key of one value of the state conditions under the form "". @@ -117,6 +126,42 @@ func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) { return v, nil } +// FindingsViewsByObserverNodeKey is the key of one value of the state findings-views under the form ".". +func FindingsViewsByObserverNodeKey(observer, node string) string { return observer + "." + node } + +// ParseFindingsViewsByObserverNodeKey reads the parts of a key of the form ".", in the order of the form; the last result is false for a key of another form. +func ParseFindingsViewsByObserverNodeKey(key string) (string, string, bool) { + rest := key + v0, after0, found0 := strings.Cut(rest, ".") + if !found0 || v0 == "" { + return "", "", false + } + rest = after0 + if rest == "" { + return "", "", false + } + v2 := rest + rest = "" + if rest != "" { + return "", "", false + } + return v0, v2, true +} + +// DecodeFindingsViewsByObserverNodeValue reads one value of the state findings-views under the form ".", refusing a field FindingsViewsByObserverNodeValue does not know and any text after the value. +func DecodeFindingsViewsByObserverNodeValue(raw []byte) (FindingsViewsByObserverNodeValue, error) { + var v FindingsViewsByObserverNodeValue + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + if err := dec.Decode(&v); err != nil { + return v, err + } + if dec.More() { + return v, errors.New("text after the value") + } + return v, nil +} + // Action is one answer the operator may give from a notification. type Action struct { Arguments map[string]string `json:"arguments,omitempty"` @@ -273,6 +318,8 @@ type SilenceAnswer = map[string]any // ResyncInput is what resync takes. type ResyncInput struct { + // ask this observer alone; none asks all + Module string `json:"module,omitempty"` } // ResyncAnswer is what resync answers. @@ -287,6 +334,17 @@ type ConditionChangedEvent = ConditionEvent // ConditionClearedEvent is the body of the event condition-cleared. type ConditionClearedEvent = ConditionEvent +// FindingsAskedEvent is the body of the event findings-asked. +type FindingsAskedEvent struct { + // the ask's id + Ask string `json:"ask"` + At time.Time `json:"at"` + // who asked: the keeper, or the person or session that called resync + By string `json:"by"` + // to ask one observer; none asks all + Module string `json:"module,omitempty"` +} + // ConditionsByKeyValueGapsItem is a type of the contract. type ConditionsByKeyValueGapsItem struct { Cleared *time.Time `json:"cleared,omitempty"` @@ -361,6 +419,8 @@ type FindingsByKeyValue struct { Needs string `json:"needs,omitempty"` // the module that wrote it Observer string `json:"observer"` + // the module the finding is about, when not the observer + Owner string `json:"owner,omitempty"` // the key's last part when it is not the kind Ref string `json:"ref,omitempty"` Resolved string `json:"resolved,omitempty"` @@ -376,6 +436,8 @@ type FindingsByKeyValue struct { Summary string `json:"summary"` // layout version, 1 V int64 `json:"v"` + // what it waits on: a person, a part or a call + WaitingOn string `json:"waiting-on,omitempty"` } // The values of FindingsByKeyValue's severity. @@ -383,3 +445,22 @@ const ( FindingsByKeyValueSeverityUrgent = "urgent" FindingsByKeyValueSeverityWarning = "warning" ) + +// FindingsViewsByObserverNodeValueStated is the last findings-stated set. +type FindingsViewsByObserverNodeValueStated struct { + At *time.Time `json:"at,omitempty"` + Findings []map[string]any `json:"findings,omitempty"` +} + +// FindingsViewsByObserverNodeValue is one value of the state findings-views under the key .. +type FindingsViewsByObserverNodeValue struct { + // the open asks + Asks []string `json:"asks,omitempty"` + Node string `json:"node"` + Observer string `json:"observer"` + // the keys it cannot judge yet + Pending []string `json:"pending,omitempty"` + // the last findings-stated set + Stated *FindingsViewsByObserverNodeValueStated `json:"stated,omitempty"` + V int64 `json:"v"` +} diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index fc0717f..2a769d7 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -17,6 +17,10 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ + {name: "the keeper asks one observer to state its findings", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"module\":\"mesh-host\"}", wire: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"module\":\"mesh-host\"}", + decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, + {name: "the keeper asks every observer", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", wire: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", + decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", diff --git a/health-and-repair/go/seats/meshwatchdogs/contract.go b/health-and-repair/go/seats/meshwatchdogs/contract.go index 7c1ec32..91207e1 100644 --- a/health-and-repair/go/seats/meshwatchdogs/contract.go +++ b/health-and-repair/go/seats/meshwatchdogs/contract.go @@ -22,11 +22,49 @@ const ( VerbResync = "resync" ) +const ( + EventMachineAway = "machine-away" + EventMachineBack = "machine-back" +) + // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { return []string{VerbSignals, VerbStuck, VerbPresence, VerbDeadLetters, VerbResync} } +// Events is every event published on the seat's subject: a new copy each call. +func Events() []string { + return []string{EventMachineAway, EventMachineBack} +} + +// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. +const ( + Family = "mesh-watchdogs.events" + FamilyMaxAgeDays = 7 +) + +// StreamMachineAway is the stream machine-away is kept in. +const StreamMachineAway = "SEAT_mesh-watchdogs_machine-away" + +// SubjectMachineAway is where machine-away is published, on mesh.seat.mesh-watchdogs.event.machine-away.. +func SubjectMachineAway(machine string) string { + return "mesh.seat.mesh-watchdogs.event.machine-away." + machine +} + +// SubjectMachineAwayAll hears every machine-away. +const SubjectMachineAwayAll = "mesh.seat.mesh-watchdogs.event.machine-away.*" + +// StreamMachineBack is the stream machine-back is kept in. +const StreamMachineBack = "SEAT_mesh-watchdogs_machine-back" + +// SubjectMachineBack is where machine-back is published, on mesh.seat.mesh-watchdogs.event.machine-back.. +func SubjectMachineBack(machine string) string { + return "mesh.seat.mesh-watchdogs.event.machine-back." + machine +} + +// SubjectMachineBackAll hears every machine-back. +const SubjectMachineBackAll = "mesh.seat.mesh-watchdogs.event.machine-back.*" + const ( StatePresence = "presence" StatePulse = "pulse" @@ -256,6 +294,28 @@ type ResyncInput struct { // ResyncAnswer is what resync answers. type ResyncAnswer = map[string]any +// MachineAwayEvent is the body of the event machine-away. +type MachineAwayEvent struct { + At time.Time `json:"at"` + // when the machine was last heard + LastHeard time.Time `json:"last-heard"` + // the machine whose presence changed + Machine string `json:"machine"` + // the layout's version + V int64 `json:"v"` +} + +// MachineBackEvent is the body of the event machine-back. +type MachineBackEvent struct { + At time.Time `json:"at"` + // when the machine was last heard + LastHeard time.Time `json:"last-heard"` + // the machine whose presence changed + Machine string `json:"machine"` + // the layout's version + V int64 `json:"v"` +} + // PresenceByNodeValue is one value of the state presence under the key . type PresenceByNodeValue struct { Online bool `json:"online"` diff --git a/health-and-repair/go/seats/meshwatchdogs/contract_test.go b/health-and-repair/go/seats/meshwatchdogs/contract_test.go index 564f824..7b3018b 100644 --- a/health-and-repair/go/seats/meshwatchdogs/contract_test.go +++ b/health-and-repair/go/seats/meshwatchdogs/contract_test.go @@ -17,6 +17,10 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ + {name: "a machine's presence expired", subject: "mesh.seat.mesh-watchdogs.event.machine-away.g14", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"g14\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"g14\",\"v\":1}", + decode: func(b []byte) (any, error) { var v MachineAwayEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-away\\.[^.*> ]+$")}, + {name: "a machine heard again", subject: "mesh.seat.mesh-watchdogs.event.machine-back.g14", given: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"g14\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"g14\",\"v\":1}", + decode: func(b []byte) (any, error) { var v MachineBackEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-back\\.[^.*> ]+$")}, {name: "a node's agent online (captured)", subject: "", given: "{\"online\":true,\"v\":1}", wire: "{\"online\":true,\"v\":1}", decode: func(b []byte) (any, error) { var v PresenceByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a delivery part's instance online (captured)", subject: "", given: "{\"online\":true,\"v\":1}", wire: "{\"online\":true,\"v\":1}", diff --git a/health-and-repair/seats/mesh-watchdogs/seat.json b/health-and-repair/seats/mesh-watchdogs/seat.json index d94c9a1..b532d27 100644 --- a/health-and-repair/seats/mesh-watchdogs/seat.json +++ b/health-and-repair/seats/mesh-watchdogs/seat.json @@ -235,6 +235,10 @@ } } ], + "family": { + "name": "mesh-watchdogs.events", + "max-age-days": 7 + }, "states": [ { "name": "presence", diff --git a/health-and-repair/ts/seats/meshconditions/src/index.ts b/health-and-repair/ts/seats/meshconditions/index.d.ts similarity index 68% rename from health-and-repair/ts/seats/meshconditions/src/index.ts rename to health-and-repair/ts/seats/meshconditions/index.d.ts index a18cdf0..1366690 100644 --- a/health-and-repair/ts/seats/meshconditions/src/index.ts +++ b/health-and-repair/ts/seats/meshconditions/index.d.ts @@ -2,62 +2,56 @@ // The contract of the seat "mesh-conditions", defined whole (seats/mesh-conditions/seat.json): What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes. -export const seat = "mesh-conditions"; +export declare const seat: "mesh-conditions"; -export const verbs = { - conditions: "conditions", - silence: "silence", - resync: "resync", -} as const; +export declare const verbs: { + readonly conditions: "conditions"; + readonly silence: "silence"; + readonly resync: "resync"; +}; -export const events = { - conditionRaised: "condition-raised", - conditionChanged: "condition-changed", - conditionCleared: "condition-cleared", -} as const; +export declare const events: { + readonly conditionRaised: "condition-raised"; + readonly conditionChanged: "condition-changed"; + readonly conditionCleared: "condition-cleared"; + readonly findingsAsked: "findings-asked"; +}; -export const family = { name: "mesh-conditions.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-conditions.events"; readonly maxAgeDays: 7 }; -export const conditionRaisedSubject = "mesh.seat.mesh-conditions.event.condition-raised"; +export declare const conditionRaisedSubject: "mesh.seat.mesh-conditions.event.condition-raised"; -export const conditionChangedSubject = "mesh.seat.mesh-conditions.event.condition-changed"; +export declare const conditionChangedSubject: "mesh.seat.mesh-conditions.event.condition-changed"; -export const conditionClearedSubject = "mesh.seat.mesh-conditions.event.condition-cleared"; +export declare const conditionClearedSubject: "mesh.seat.mesh-conditions.event.condition-cleared"; -export const states = { - conditions: "conditions", - findings: "findings", -} as const; +export declare const findingsAskedStream: "SEAT_mesh-conditions_findings-asked"; + +export declare const findingsAskedSubject: "mesh.seat.mesh-conditions.event.findings-asked"; + +export declare const states: { + readonly conditions: "conditions"; + readonly findings: "findings"; + readonly findingsViews: "findings-views"; +}; /** The key of one value of the state conditions under the form "". */ -export function conditionsByKeyKey(key: string): string { - return key; -} +export declare function conditionsByKeyKey(key: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseConditionsByKeyKey(_key: string): { key: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { key }; -} +export declare function parseConditionsByKeyKey(_key: string): { key: string } | undefined; /** The key of one value of the state findings under the form "". */ -export function findingsByKeyKey(key: string): string { - return key; -} +export declare function findingsByKeyKey(key: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseFindingsByKeyKey(_key: string): { key: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { key }; -} +export declare function parseFindingsByKeyKey(_key: string): { key: string } | undefined; + +/** The key of one value of the state findings-views under the form ".". */ +export declare function findingsViewsByObserverNodeKey(observer: string, node: string): string; + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export declare function parseFindingsViewsByObserverNodeKey(_key: string): { observer: string; node: string } | undefined; /** one answer the operator may give from a notification */ export interface Action { @@ -182,6 +176,8 @@ export type SilenceAnswer = Record; /** is what resync takes. */ export interface ResyncInput { + /** ask this observer alone; none asks all */ + "module"?: string; } /** is what resync answers. */ @@ -196,6 +192,17 @@ export type ConditionChangedEvent = ConditionEvent; /** is the body of the event condition-cleared. */ export type ConditionClearedEvent = ConditionEvent; +/** is the body of the event findings-asked. */ +export interface FindingsAskedEvent { + /** the ask's id */ + "ask": string; + "at": string; + /** who asked: the keeper, or the person or session that called resync */ + "by": string; + /** to ask one observer; none asks all */ + "module"?: string; +} + export interface ConditionsByKeyValueGapsItem { "cleared"?: string; "reopened"?: string; @@ -261,6 +268,8 @@ export interface FindingsByKeyValue { "needs"?: string; /** the module that wrote it */ "observer": string; + /** the module the finding is about, when not the observer */ + "owner"?: string; /** the key's last part when it is not the kind */ "ref"?: string; "resolved"?: string; @@ -276,5 +285,26 @@ export interface FindingsByKeyValue { "summary": string; /** layout version, 1 */ "v": number; + /** what it waits on: a person, a part or a call */ + "waiting-on"?: string; +} + +/** the last findings-stated set */ +export interface FindingsViewsByObserverNodeValueStated { + "at"?: string; + "findings"?: Record[]; +} + +/** is one value of the state findings-views under the key .. */ +export interface FindingsViewsByObserverNodeValue { + /** the open asks */ + "asks"?: string[]; + "node": string; + "observer": string; + /** the keys it cannot judge yet */ + "pending"?: string[]; + /** the last findings-stated set */ + "stated"?: FindingsViewsByObserverNodeValueStated; + "v": number; } diff --git a/health-and-repair/ts/seats/meshconditions/index.js b/health-and-repair/ts/seats/meshconditions/index.js new file mode 100644 index 0000000..115101a --- /dev/null +++ b/health-and-repair/ts/seats/meshconditions/index.js @@ -0,0 +1,86 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-conditions", defined whole (seats/mesh-conditions/seat.json): What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes. + +export const seat = "mesh-conditions"; + +export const verbs = { + conditions: "conditions", + silence: "silence", + resync: "resync", +}; + +export const events = { + conditionRaised: "condition-raised", + conditionChanged: "condition-changed", + conditionCleared: "condition-cleared", + findingsAsked: "findings-asked", +}; + +export const family = { name: "mesh-conditions.events", maxAgeDays: 7 }; + +export const conditionRaisedSubject = "mesh.seat.mesh-conditions.event.condition-raised"; + +export const conditionChangedSubject = "mesh.seat.mesh-conditions.event.condition-changed"; + +export const conditionClearedSubject = "mesh.seat.mesh-conditions.event.condition-cleared"; + +export const findingsAskedStream = "SEAT_mesh-conditions_findings-asked"; + +export const findingsAskedSubject = "mesh.seat.mesh-conditions.event.findings-asked"; + +export const states = { + conditions: "conditions", + findings: "findings", + findingsViews: "findings-views", +}; + +/** The key of one value of the state conditions under the form "". */ +export function conditionsByKeyKey(key) { + return key; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseConditionsByKeyKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { key }; +} + +/** The key of one value of the state findings under the form "". */ +export function findingsByKeyKey(key) { + return key; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseFindingsByKeyKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { key }; +} + +/** The key of one value of the state findings-views under the form ".". */ +export function findingsViewsByObserverNodeKey(observer, node) { + return observer + "." + node; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseFindingsViewsByObserverNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const observer = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { observer, node }; +} + diff --git a/health-and-repair/ts/seats/meshconditions/package-lock.json b/health-and-repair/ts/seats/meshconditions/package-lock.json index 6aa81e6..6ee6716 100644 --- a/health-and-repair/ts/seats/meshconditions/package-lock.json +++ b/health-and-repair/ts/seats/meshconditions/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-health-and-repair-contracts-mesh-conditions", + "name": "@novox/mesh-contracts-health-and-repair-mesh-conditions", "packages": { "": { - "name": "@novox/mesh-health-and-repair-contracts-mesh-conditions", + "name": "@novox/mesh-contracts-health-and-repair-mesh-conditions", "version": "0.1.0" } }, diff --git a/health-and-repair/ts/seats/meshconditions/package.json b/health-and-repair/ts/seats/meshconditions/package.json index 0be4987..d2efa33 100644 --- a/health-and-repair/ts/seats/meshconditions/package.json +++ b/health-and-repair/ts/seats/meshconditions/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-conditions, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-health-and-repair-contracts-mesh-conditions", + "name": "@novox/mesh-contracts-health-and-repair-mesh-conditions", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/health-and-repair/ts/seats/meshhandacts/src/index.ts b/health-and-repair/ts/seats/meshhandacts/index.d.ts similarity index 71% rename from health-and-repair/ts/seats/meshhandacts/src/index.ts rename to health-and-repair/ts/seats/meshhandacts/index.d.ts index 0b4ea7b..02f6433 100644 --- a/health-and-repair/ts/seats/meshhandacts/src/index.ts +++ b/health-and-repair/ts/seats/meshhandacts/index.d.ts @@ -2,60 +2,38 @@ // The contract of the seat "mesh-hand-acts", defined whole (seats/mesh-hand-acts/seat.json): Acts done by hand, recorded with who, why and cause (ADR 0565): the log every module records through. -export const seat = "mesh-hand-acts"; +export declare const seat: "mesh-hand-acts"; -export const verbs = { - handAct: "hand-act", - handActs: "hand-acts", - warranted: "warranted", -} as const; +export declare const verbs: { + readonly handAct: "hand-act"; + readonly handActs: "hand-acts"; + readonly warranted: "warranted"; +}; -export const events = { - actRecorded: "act-recorded", -} as const; +export declare const events: { + readonly actRecorded: "act-recorded"; +}; -export const family = { name: "mesh-hand-acts.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-hand-acts.events"; readonly maxAgeDays: 7 }; -export const actRecordedSubject = "mesh.seat.mesh-hand-acts.event.act-recorded"; +export declare const actRecordedSubject: "mesh.seat.mesh-hand-acts.event.act-recorded"; -export const states = { - acts: "acts", - warrants: "warrants", -} as const; +export declare const states: { + readonly acts: "acts"; + readonly warrants: "warrants"; +}; /** The key of one value of the state acts under the form "". */ -export function actsByIDKey(id: string): string { - return id; -} +export declare function actsByIDKey(id: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseActsByIDKey(_key: string): { id: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const id = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { id }; -} +export declare function parseActsByIDKey(_key: string): { id: string } | undefined; /** The key of one value of the state warrants under the form ".". */ -export function warrantsByAskerAskKey(asker: string, ask: string): string { - return asker + "." + ask; -} +export declare function warrantsByAskerAskKey(asker: string, ask: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseWarrantsByAskerAskKey(_key: string): { asker: string; ask: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const asker = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const ask = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { asker, ask }; -} +export declare function parseWarrantsByAskerAskKey(_key: string): { asker: string; ask: string } | undefined; /** one act done by hand */ export interface Act { diff --git a/health-and-repair/ts/seats/meshhandacts/index.js b/health-and-repair/ts/seats/meshhandacts/index.js new file mode 100644 index 0000000..4461e8d --- /dev/null +++ b/health-and-repair/ts/seats/meshhandacts/index.js @@ -0,0 +1,59 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-hand-acts", defined whole (seats/mesh-hand-acts/seat.json): Acts done by hand, recorded with who, why and cause (ADR 0565): the log every module records through. + +export const seat = "mesh-hand-acts"; + +export const verbs = { + handAct: "hand-act", + handActs: "hand-acts", + warranted: "warranted", +}; + +export const events = { + actRecorded: "act-recorded", +}; + +export const family = { name: "mesh-hand-acts.events", maxAgeDays: 7 }; + +export const actRecordedSubject = "mesh.seat.mesh-hand-acts.event.act-recorded"; + +export const states = { + acts: "acts", + warrants: "warrants", +}; + +/** The key of one value of the state acts under the form "". */ +export function actsByIDKey(id) { + return id; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseActsByIDKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const id = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { id }; +} + +/** The key of one value of the state warrants under the form ".". */ +export function warrantsByAskerAskKey(asker, ask) { + return asker + "." + ask; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseWarrantsByAskerAskKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const asker = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const ask = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { asker, ask }; +} + diff --git a/health-and-repair/ts/seats/meshhandacts/package-lock.json b/health-and-repair/ts/seats/meshhandacts/package-lock.json index c94f1e5..29a7c2a 100644 --- a/health-and-repair/ts/seats/meshhandacts/package-lock.json +++ b/health-and-repair/ts/seats/meshhandacts/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts", + "name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts", "packages": { "": { - "name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts", + "name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts", "version": "0.1.0" } }, diff --git a/health-and-repair/ts/seats/meshhandacts/package.json b/health-and-repair/ts/seats/meshhandacts/package.json index 20ebafd..cfb4c3f 100644 --- a/health-and-repair/ts/seats/meshhandacts/package.json +++ b/health-and-repair/ts/seats/meshhandacts/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-hand-acts, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-health-and-repair-contracts-mesh-hand-acts", + "name": "@novox/mesh-contracts-health-and-repair-mesh-hand-acts", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/health-and-repair/ts/seats/meshhealers/src/index.ts b/health-and-repair/ts/seats/meshhealers/index.d.ts similarity index 69% rename from health-and-repair/ts/seats/meshhealers/src/index.ts rename to health-and-repair/ts/seats/meshhealers/index.d.ts index 3840537..392573b 100644 --- a/health-and-repair/ts/seats/meshhealers/src/index.ts +++ b/health-and-repair/ts/seats/meshhealers/index.d.ts @@ -2,56 +2,38 @@ // The contract of the seat "mesh-healers", defined whole (seats/mesh-healers/seat.json): The healers (ADR 0564): each a registered response to one kind of condition, within a budget and the mesh-wide brake. -export const seat = "mesh-healers"; +export declare const seat: "mesh-healers"; -export const verbs = { - healers: "healers", - heal: "heal", - drill: "drill", -} as const; +export declare const verbs: { + readonly healers: "healers"; + readonly heal: "heal"; + readonly drill: "drill"; +}; -export const events = { - healerActed: "healer-acted", -} as const; +export declare const events: { + readonly healerActed: "healer-acted"; +}; -export const family = { name: "mesh-healers.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-healers.events"; readonly maxAgeDays: 7 }; -export const healerActedSubject = "mesh.seat.mesh-healers.event.healer-acted"; +export declare const healerActedSubject: "mesh.seat.mesh-healers.event.healer-acted"; -export const states = { - attempts: "attempts", - would: "would", -} as const; +export declare const states: { + readonly attempts: "attempts"; + readonly would: "would"; +}; /** The key of one value of the state attempts under the form "". */ -export function attemptsByAttemptKey(attempt: string): string { - return attempt; -} +export declare function attemptsByAttemptKey(attempt: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseAttemptsByAttemptKey(_key: string): { attempt: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const attempt = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { attempt }; -} +export declare function parseAttemptsByAttemptKey(_key: string): { attempt: string } | undefined; /** The key of one value of the state would under the form "". */ -export function wouldByWouldKey(would: string): string { - return would; -} +export declare function wouldByWouldKey(would: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseWouldByWouldKey(_key: string): { would: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const would = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { would }; -} +export declare function parseWouldByWouldKey(_key: string): { would: string } | undefined; /** is what healers takes. */ export interface HealersInput { diff --git a/health-and-repair/ts/seats/meshhealers/index.js b/health-and-repair/ts/seats/meshhealers/index.js new file mode 100644 index 0000000..05659bd --- /dev/null +++ b/health-and-repair/ts/seats/meshhealers/index.js @@ -0,0 +1,55 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-healers", defined whole (seats/mesh-healers/seat.json): The healers (ADR 0564): each a registered response to one kind of condition, within a budget and the mesh-wide brake. + +export const seat = "mesh-healers"; + +export const verbs = { + healers: "healers", + heal: "heal", + drill: "drill", +}; + +export const events = { + healerActed: "healer-acted", +}; + +export const family = { name: "mesh-healers.events", maxAgeDays: 7 }; + +export const healerActedSubject = "mesh.seat.mesh-healers.event.healer-acted"; + +export const states = { + attempts: "attempts", + would: "would", +}; + +/** The key of one value of the state attempts under the form "". */ +export function attemptsByAttemptKey(attempt) { + return attempt; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseAttemptsByAttemptKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const attempt = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { attempt }; +} + +/** The key of one value of the state would under the form "". */ +export function wouldByWouldKey(would) { + return would; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseWouldByWouldKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const would = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { would }; +} + diff --git a/health-and-repair/ts/seats/meshhealers/package-lock.json b/health-and-repair/ts/seats/meshhealers/package-lock.json index 9a26d5f..073e379 100644 --- a/health-and-repair/ts/seats/meshhealers/package-lock.json +++ b/health-and-repair/ts/seats/meshhealers/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-health-and-repair-contracts-mesh-healers", + "name": "@novox/mesh-contracts-health-and-repair-mesh-healers", "packages": { "": { - "name": "@novox/mesh-health-and-repair-contracts-mesh-healers", + "name": "@novox/mesh-contracts-health-and-repair-mesh-healers", "version": "0.1.0" } }, diff --git a/health-and-repair/ts/seats/meshhealers/package.json b/health-and-repair/ts/seats/meshhealers/package.json index 3d48314..e9834aa 100644 --- a/health-and-repair/ts/seats/meshhealers/package.json +++ b/health-and-repair/ts/seats/meshhealers/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-healers, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-health-and-repair-contracts-mesh-healers", + "name": "@novox/mesh-contracts-health-and-repair-mesh-healers", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/health-and-repair/ts/seats/meshselfcheck/src/index.ts b/health-and-repair/ts/seats/meshselfcheck/index.d.ts similarity index 79% rename from health-and-repair/ts/seats/meshselfcheck/src/index.ts rename to health-and-repair/ts/seats/meshselfcheck/index.d.ts index b76fc1d..256f61b 100644 --- a/health-and-repair/ts/seats/meshselfcheck/src/index.ts +++ b/health-and-repair/ts/seats/meshselfcheck/index.d.ts @@ -2,20 +2,20 @@ // The contract of the seat "mesh-self-check", defined whole (seats/mesh-self-check/seat.json): The mesh checking itself (ADR 0564): probes run every five minutes, each failure a finding the seat's conditions raise. -export const seat = "mesh-self-check"; +export declare const seat: "mesh-self-check"; -export const verbs = { - doctor: "doctor", - probes: "probes", -} as const; +export declare const verbs: { + readonly doctor: "doctor"; + readonly probes: "probes"; +}; -export const events = { - checked: "checked", -} as const; +export declare const events: { + readonly checked: "checked"; +}; -export const family = { name: "mesh-self-check.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-self-check.events"; readonly maxAgeDays: 7 }; -export const checkedSubject = "mesh.seat.mesh-self-check.event.checked"; +export declare const checkedSubject: "mesh.seat.mesh-self-check.event.checked"; /** one probe's verdict */ export interface ProbeVerdict { diff --git a/health-and-repair/ts/seats/meshselfcheck/index.js b/health-and-repair/ts/seats/meshselfcheck/index.js new file mode 100644 index 0000000..b74b201 --- /dev/null +++ b/health-and-repair/ts/seats/meshselfcheck/index.js @@ -0,0 +1,19 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-self-check", defined whole (seats/mesh-self-check/seat.json): The mesh checking itself (ADR 0564): probes run every five minutes, each failure a finding the seat's conditions raise. + +export const seat = "mesh-self-check"; + +export const verbs = { + doctor: "doctor", + probes: "probes", +}; + +export const events = { + checked: "checked", +}; + +export const family = { name: "mesh-self-check.events", maxAgeDays: 7 }; + +export const checkedSubject = "mesh.seat.mesh-self-check.event.checked"; + diff --git a/health-and-repair/ts/seats/meshselfcheck/package-lock.json b/health-and-repair/ts/seats/meshselfcheck/package-lock.json index 1590123..644ccbe 100644 --- a/health-and-repair/ts/seats/meshselfcheck/package-lock.json +++ b/health-and-repair/ts/seats/meshselfcheck/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-health-and-repair-contracts-mesh-self-check", + "name": "@novox/mesh-contracts-health-and-repair-mesh-self-check", "packages": { "": { - "name": "@novox/mesh-health-and-repair-contracts-mesh-self-check", + "name": "@novox/mesh-contracts-health-and-repair-mesh-self-check", "version": "0.1.0" } }, diff --git a/health-and-repair/ts/seats/meshselfcheck/package.json b/health-and-repair/ts/seats/meshselfcheck/package.json index f0027c9..4cabb52 100644 --- a/health-and-repair/ts/seats/meshselfcheck/package.json +++ b/health-and-repair/ts/seats/meshselfcheck/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-self-check, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-health-and-repair-contracts-mesh-self-check", + "name": "@novox/mesh-contracts-health-and-repair-mesh-self-check", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/health-and-repair/ts/seats/meshwatchdogs/src/index.ts b/health-and-repair/ts/seats/meshwatchdogs/index.d.ts similarity index 64% rename from health-and-repair/ts/seats/meshwatchdogs/src/index.ts rename to health-and-repair/ts/seats/meshwatchdogs/index.d.ts index 8f12999..ebe31a0 100644 --- a/health-and-repair/ts/seats/meshwatchdogs/src/index.ts +++ b/health-and-repair/ts/seats/meshwatchdogs/index.d.ts @@ -2,95 +2,64 @@ // The contract of the seat "mesh-watchdogs", defined whole (seats/mesh-watchdogs/seat.json): The watchman's seat (ADR 0564, ADR 0433): signals that expire unless renewed, what stopped moving, who is present, the dead letters. -export const seat = "mesh-watchdogs"; +export declare const seat: "mesh-watchdogs"; -export const verbs = { - signals: "signals", - stuck: "stuck", - presence: "presence", - deadLetters: "dead-letters", - resync: "resync", -} as const; +export declare const verbs: { + readonly signals: "signals"; + readonly stuck: "stuck"; + readonly presence: "presence"; + readonly deadLetters: "dead-letters"; + readonly resync: "resync"; +}; -export const states = { - presence: "presence", - pulse: "pulse", - stuck: "stuck", -} as const; +export declare const events: { + readonly machineAway: "machine-away"; + readonly machineBack: "machine-back"; +}; + +export declare const family: { readonly name: "mesh-watchdogs.events"; readonly maxAgeDays: 7 }; + +export declare const machineAwayStream: "SEAT_mesh-watchdogs_machine-away"; + +export declare function machineAwaySubject(machine: string): string; + +export declare const machineAwaySubjectAll: "mesh.seat.mesh-watchdogs.event.machine-away.*"; + +export declare const machineBackStream: "SEAT_mesh-watchdogs_machine-back"; + +export declare function machineBackSubject(machine: string): string; + +export declare const machineBackSubjectAll: "mesh.seat.mesh-watchdogs.event.machine-back.*"; + +export declare const states: { + readonly presence: "presence"; + readonly pulse: "pulse"; + readonly stuck: "stuck"; +}; /** The key of one value of the state presence under the form "". */ -export function presenceByNodeKey(node: string): string { - return node; -} +export declare function presenceByNodeKey(node: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parsePresenceByNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node }; -} +export declare function parsePresenceByNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state presence under the form "part..". */ -export function presenceByPartPartInstanceKey(part: string, instance: string): string { - return "part." + part + "." + instance; -} +export declare function presenceByPartPartInstanceKey(part: string, instance: string): string; /** The parts of a key of the form "part..", or undefined for a key of another form. */ -export function parsePresenceByPartPartInstanceKey(_key: string): { part: string; instance: string } | undefined { - let _rest = _key; - if (!_rest.startsWith("part.")) return undefined; - _rest = _rest.slice(5); - const _at1 = _rest.indexOf("."); - if (_at1 <= 0) return undefined; - const part = _rest.slice(0, _at1); - _rest = _rest.slice(_at1 + 1); - if (_rest === "") return undefined; - const instance = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { part, instance }; -} +export declare function parsePresenceByPartPartInstanceKey(_key: string): { part: string; instance: string } | undefined; /** The key of one value of the state pulse under the form ".". */ -export function pulseByBucketKeyKey(bucket: string, key: string): string { - return bucket + "." + key; -} +export declare function pulseByBucketKeyKey(bucket: string, key: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parsePulseByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const bucket = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { bucket, key }; -} +export declare function parsePulseByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined; /** The key of one value of the state stuck under the form ".". */ -export function stuckByBucketKeyKey(bucket: string, key: string): string { - return bucket + "." + key; -} +export declare function stuckByBucketKeyKey(bucket: string, key: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseStuckByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const bucket = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { bucket, key }; -} +export declare function parseStuckByBucketKeyKey(_key: string): { bucket: string; key: string } | undefined; /** is what signals takes. */ export interface SignalsInput { @@ -169,6 +138,28 @@ export interface ResyncInput { /** is what resync answers. */ export type ResyncAnswer = Record; +/** is the body of the event machine-away. */ +export interface MachineAwayEvent { + "at": string; + /** when the machine was last heard */ + "last-heard": string; + /** the machine whose presence changed */ + "machine": string; + /** the layout's version */ + "v": number; +} + +/** is the body of the event machine-back. */ +export interface MachineBackEvent { + "at": string; + /** when the machine was last heard */ + "last-heard": string; + /** the machine whose presence changed */ + "machine": string; + /** the layout's version */ + "v": number; +} + /** is one value of the state presence under the key . */ export interface PresenceByNodeValue { "online": boolean; diff --git a/health-and-repair/ts/seats/meshwatchdogs/index.js b/health-and-repair/ts/seats/meshwatchdogs/index.js new file mode 100644 index 0000000..b5b1e88 --- /dev/null +++ b/health-and-repair/ts/seats/meshwatchdogs/index.js @@ -0,0 +1,117 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-watchdogs", defined whole (seats/mesh-watchdogs/seat.json): The watchman's seat (ADR 0564, ADR 0433): signals that expire unless renewed, what stopped moving, who is present, the dead letters. + +export const seat = "mesh-watchdogs"; + +export const verbs = { + signals: "signals", + stuck: "stuck", + presence: "presence", + deadLetters: "dead-letters", + resync: "resync", +}; + +export const events = { + machineAway: "machine-away", + machineBack: "machine-back", +}; + +export const family = { name: "mesh-watchdogs.events", maxAgeDays: 7 }; + +export const machineAwayStream = "SEAT_mesh-watchdogs_machine-away"; + +export function machineAwaySubject(machine) { + return "mesh.seat.mesh-watchdogs.event.machine-away." + machine; +} + +export const machineAwaySubjectAll = "mesh.seat.mesh-watchdogs.event.machine-away.*"; + +export const machineBackStream = "SEAT_mesh-watchdogs_machine-back"; + +export function machineBackSubject(machine) { + return "mesh.seat.mesh-watchdogs.event.machine-back." + machine; +} + +export const machineBackSubjectAll = "mesh.seat.mesh-watchdogs.event.machine-back.*"; + +export const states = { + presence: "presence", + pulse: "pulse", + stuck: "stuck", +}; + +/** The key of one value of the state presence under the form "". */ +export function presenceByNodeKey(node) { + return node; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parsePresenceByNodeKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state presence under the form "part..". */ +export function presenceByPartPartInstanceKey(part, instance) { + return "part." + part + "." + instance; +} + +/** The parts of a key of the form "part..", or undefined for a key of another form. */ +export function parsePresenceByPartPartInstanceKey(_key) { + let _rest = _key; + if (!_rest.startsWith("part.")) return undefined; + _rest = _rest.slice(5); + const _at1 = _rest.indexOf("."); + if (_at1 <= 0) return undefined; + const part = _rest.slice(0, _at1); + _rest = _rest.slice(_at1 + 1); + if (_rest === "") return undefined; + const instance = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { part, instance }; +} + +/** The key of one value of the state pulse under the form ".". */ +export function pulseByBucketKeyKey(bucket, key) { + return bucket + "." + key; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parsePulseByBucketKeyKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const bucket = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { bucket, key }; +} + +/** The key of one value of the state stuck under the form ".". */ +export function stuckByBucketKeyKey(bucket, key) { + return bucket + "." + key; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseStuckByBucketKeyKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const bucket = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { bucket, key }; +} + diff --git a/health-and-repair/ts/seats/meshwatchdogs/package-lock.json b/health-and-repair/ts/seats/meshwatchdogs/package-lock.json index b236c0c..dc100c5 100644 --- a/health-and-repair/ts/seats/meshwatchdogs/package-lock.json +++ b/health-and-repair/ts/seats/meshwatchdogs/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs", + "name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs", "packages": { "": { - "name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs", + "name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs", "version": "0.1.0" } }, diff --git a/health-and-repair/ts/seats/meshwatchdogs/package.json b/health-and-repair/ts/seats/meshwatchdogs/package.json index 9dc0933..763e007 100644 --- a/health-and-repair/ts/seats/meshwatchdogs/package.json +++ b/health-and-repair/ts/seats/meshwatchdogs/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-watchdogs, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-health-and-repair-contracts-mesh-watchdogs", + "name": "@novox/mesh-contracts-health-and-repair-mesh-watchdogs", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/identity-and-access/go/seats/meshgrants/contract.go b/identity-and-access/go/seats/meshgrants/contract.go new file mode 100644 index 0000000..a2c3e2c --- /dev/null +++ b/identity-and-access/go/seats/meshgrants/contract.go @@ -0,0 +1,139 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// Package meshgrants is the contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441). +package meshgrants + +import "time" + +// Seat is the seat's name. +const Seat = "mesh-grants" + +const ( + VerbGrantsFor = "grants-for" +) + +const ( + EventWaitHeld = "wait-held" + EventWaitEnded = "wait-ended" + EventFilling = "filling" + EventRoom = "room" +) + +// Verbs is every verb the seat serves, in its definition's order: a new copy each call. +func Verbs() []string { + return []string{VerbGrantsFor} +} + +// Events is every event published on the seat's subject: a new copy each call. +func Events() []string { + return []string{EventWaitHeld, EventWaitEnded, EventFilling, EventRoom} +} + +// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. +const ( + Family = "mesh-grants.events" + FamilyMaxAgeDays = 7 +) + +// SubjectWaitHeld is where wait-held is published. +const SubjectWaitHeld = "mesh.seat.mesh-grants.event.wait-held" + +// SubjectWaitEnded is where wait-ended is published. +const SubjectWaitEnded = "mesh.seat.mesh-grants.event.wait-ended" + +// SubjectFilling is where filling is published. +const SubjectFilling = "mesh.seat.mesh-grants.event.filling" + +// SubjectRoom is where room is published. +const SubjectRoom = "mesh.seat.mesh-grants.event.room" + +// Fill is a store's fill against its cap. +type Fill struct { + At *time.Time `json:"at,omitempty"` + Bytes int64 `json:"bytes"` + // bytes + Cap int64 `json:"cap"` + // the store + Store string `json:"store"` +} + +// Grant is a type of the contract. +type Grant struct { + // the bus subject + Subject string `json:"subject"` + // the verb or event the grant is for + Verb string `json:"verb"` +} + +// GrantsForModulesItem is a type of the contract. +type GrantsForModulesItem struct { + Added []Grant `json:"added"` + Module string `json:"module"` + Removed []Grant `json:"removed"` +} + +// GrantsFor is the grants a candidate would compose, per module, added and removed against the branch's newest. +type GrantsFor struct { + // why it could not be answered: the catalog half of the candidate is not held + Error string `json:"error,omitempty"` + Modules []GrantsForModulesItem `json:"modules,omitempty"` +} + +// Wait is a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*). +type Wait struct { + // a duration such as 10m + Bound string `json:"bound"` + // on a release, who released it and why + By string `json:"by,omitempty"` + // when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266) + ClockFrom time.Time `json:"clock-from"` + // the entry's fingerprint, whose grant waits + Fp string `json:"fp,omitempty"` + // on wait-ended: ran or released + How string `json:"how,omitempty"` + // the entry that waits + Module string `json:"module"` + // the acting part waited for + Part string `json:"part"` + Since time.Time `json:"since"` + // the step, grant + Step string `json:"step"` + // its new version's fingerprint + Version string `json:"version"` +} + +// The values of Wait's how. +const ( + WaitHowRan = "ran" + WaitHowReleased = "released" +) + +// The values of Wait's step. +const ( + WaitStepGrant = "grant" +) + +// GrantsForInput is what grants-for takes. +type GrantsForInput struct { + // its watched branch + Branch string `json:"branch"` + // or the id of a run + Run string `json:"run,omitempty"` + // the candidate's source revision + Source string `json:"source,omitempty"` +} + +// GrantsForAnswer is what grants-for answers. +type GrantsForAnswer = GrantsFor + +// WaitHeldEvent is the body of the event wait-held. +type WaitHeldEvent = Wait + +// WaitEndedEvent is the body of the event wait-ended. +type WaitEndedEvent = Wait + +// FillingEvent is the body of the event filling. +type FillingEvent = Fill + +// RoomEvent is the body of the event room. +type RoomEvent = Fill diff --git a/identity-and-access/go/seats/meshgrants/contract_test.go b/identity-and-access/go/seats/meshgrants/contract_test.go new file mode 100644 index 0000000..ef84ac6 --- /dev/null +++ b/identity-and-access/go/seats/meshgrants/contract_test.go @@ -0,0 +1,58 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +package meshgrants + +import ( + "encoding/json" + "reflect" + "regexp" + "testing" +) + +// TestFixtures reads every fixture of seats/mesh-grants/fixtures: each decodes into its type, a field the type does not +// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's. +func TestFixtures(t *testing.T) { + cases := []struct { + name, subject, given, wire string + decode func([]byte) (any, error) + subjectIs *regexp.Regexp + }{ + {name: "a granting wait held", subject: "mesh.seat.mesh-grants.event.wait-held", given: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", + decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-held$")}, + {name: "a granting wait released", subject: "mesh.seat.mesh-grants.event.wait-ended", given: "{\"bound\":\"10m\",\"by\":\"jochen: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"by\":\"jochen: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", + decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-ended$")}, + {name: "filling is said past 80 %", subject: "mesh.seat.mesh-grants.event.filling", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", + decode: func(b []byte) (any, error) { var v FillingEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.filling$")}, + {name: "room is said below 70 %", subject: "mesh.seat.mesh-grants.event.room", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"bytes\":100663296,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"bytes\":100663296,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", + decode: func(b []byte) (any, error) { var v RoomEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.room$")}, + {name: "grants-for answers the grants a candidate adds", subject: "", given: "{\"modules\":[{\"added\":[{\"subject\":\"mesh.seat.node-engine.verb.manifest-reads\",\"verb\":\"manifest-reads\"}],\"module\":\"mesh-tools\",\"removed\":[]}]}", wire: "{\"modules\":[{\"added\":[{\"subject\":\"mesh.seat.node-engine.verb.manifest-reads\",\"verb\":\"manifest-reads\"}],\"module\":\"mesh-tools\",\"removed\":[]}]}", + decode: func(b []byte) (any, error) { var v GrantsForAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "grants-for asks a source revision on a branch", subject: "", given: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}", wire: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}", + decode: func(b []byte) (any, error) { var v GrantsForInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + } + for _, c := range cases { + v, err := c.decode([]byte(c.given)) + if err != nil { + t.Errorf("%s: does not decode: %v", c.name, err) + continue + } + back, err := json.Marshal(v) + if err != nil { + t.Errorf("%s: does not encode: %v", c.name, err) + continue + } + var got, want any + if err := json.Unmarshal(back, &got); err != nil { + t.Fatal(err) + } + if err := json.Unmarshal([]byte(c.wire), &want); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire) + } + if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) { + t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs) + } + } +} diff --git a/identity-and-access/go/seats/meshgrants/go.mod b/identity-and-access/go/seats/meshgrants/go.mod new file mode 100644 index 0000000..44a020b --- /dev/null +++ b/identity-and-access/go/seats/meshgrants/go.mod @@ -0,0 +1,3 @@ +module git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants + +go 1.26.0 diff --git a/identity-and-access/ts/seats/meshgrants/index.d.ts b/identity-and-access/ts/seats/meshgrants/index.d.ts new file mode 100644 index 0000000..167e2b8 --- /dev/null +++ b/identity-and-access/ts/seats/meshgrants/index.d.ts @@ -0,0 +1,105 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441). + +export declare const seat: "mesh-grants"; + +export declare const verbs: { + readonly grantsFor: "grants-for"; +}; + +export declare const events: { + readonly waitHeld: "wait-held"; + readonly waitEnded: "wait-ended"; + readonly filling: "filling"; + readonly room: "room"; +}; + +export declare const family: { readonly name: "mesh-grants.events"; readonly maxAgeDays: 7 }; + +export declare const waitHeldSubject: "mesh.seat.mesh-grants.event.wait-held"; + +export declare const waitEndedSubject: "mesh.seat.mesh-grants.event.wait-ended"; + +export declare const fillingSubject: "mesh.seat.mesh-grants.event.filling"; + +export declare const roomSubject: "mesh.seat.mesh-grants.event.room"; + +/** a store's fill against its cap */ +export interface Fill { + "at"?: string; + "bytes": number; + /** bytes */ + "cap": number; + /** the store */ + "store": string; +} + +export interface Grant { + /** the bus subject */ + "subject": string; + /** the verb or event the grant is for */ + "verb": string; +} + +export interface GrantsForModulesItem { + "added": Grant[]; + "module": string; + "removed": Grant[]; +} + +/** the grants a candidate would compose, per module, added and removed against the branch's newest */ +export interface GrantsFor { + /** why it could not be answered: the catalog half of the candidate is not held */ + "error"?: string; + "modules"?: GrantsForModulesItem[]; +} + +/** a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*) */ +export interface Wait { + /** a duration such as 10m */ + "bound": string; + /** on a release, who released it and why */ + "by"?: string; + /** when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266) */ + "clock-from": string; + /** the entry's fingerprint, whose grant waits */ + "fp"?: string; + /** on wait-ended: ran or released */ + "how"?: "ran" | "released"; + /** the entry that waits */ + "module": string; + /** the acting part waited for */ + "part": string; + "since": string; + /** the step, grant */ + "step": "grant"; + /** its new version's fingerprint */ + "version": string; +} + +/** is what grants-for takes. */ +export interface GrantsForInput { + /** its watched branch */ + "branch": string; + /** or the id of a run */ + "run"?: string; + /** the candidate's source revision */ + "source"?: string; +} + +/** is what grants-for answers. */ +export type GrantsForAnswer = GrantsFor; + +/** is the body of the event wait-held. */ +export type WaitHeldEvent = Wait; + +/** is the body of the event wait-ended. */ +export type WaitEndedEvent = Wait; + +/** is the body of the event filling. */ +export type FillingEvent = Fill; + +/** is the body of the event room. */ +export type RoomEvent = Fill; + diff --git a/identity-and-access/ts/seats/meshgrants/index.js b/identity-and-access/ts/seats/meshgrants/index.js new file mode 100644 index 0000000..e19f333 --- /dev/null +++ b/identity-and-access/ts/seats/meshgrants/index.js @@ -0,0 +1,27 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-grants", defined whole (seats/mesh-grants/seat.json): Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441). + +export const seat = "mesh-grants"; + +export const verbs = { + grantsFor: "grants-for", +}; + +export const events = { + waitHeld: "wait-held", + waitEnded: "wait-ended", + filling: "filling", + room: "room", +}; + +export const family = { name: "mesh-grants.events", maxAgeDays: 7 }; + +export const waitHeldSubject = "mesh.seat.mesh-grants.event.wait-held"; + +export const waitEndedSubject = "mesh.seat.mesh-grants.event.wait-ended"; + +export const fillingSubject = "mesh.seat.mesh-grants.event.filling"; + +export const roomSubject = "mesh.seat.mesh-grants.event.room"; + diff --git a/identity-and-access/ts/seats/meshgrants/package-lock.json b/identity-and-access/ts/seats/meshgrants/package-lock.json new file mode 100644 index 0000000..f57a656 --- /dev/null +++ b/identity-and-access/ts/seats/meshgrants/package-lock.json @@ -0,0 +1,12 @@ +{ + "lockfileVersion": 3, + "name": "@novox/mesh-contracts-identity-and-access-mesh-grants", + "packages": { + "": { + "name": "@novox/mesh-contracts-identity-and-access-mesh-grants", + "version": "0.1.0" + } + }, + "requires": true, + "version": "0.1.0" +} diff --git a/identity-and-access/ts/seats/meshgrants/package.json b/identity-and-access/ts/seats/meshgrants/package.json new file mode 100644 index 0000000..a4a8fce --- /dev/null +++ b/identity-and-access/ts/seats/meshgrants/package.json @@ -0,0 +1,18 @@ +{ + "description": "The contract of the seat mesh-grants, generated from its definition.", + "exports": { + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } + }, + "files": [ + "index.js", + "index.d.ts", + "parts" + ], + "name": "@novox/mesh-contracts-identity-and-access-mesh-grants", + "type": "module", + "types": "./index.d.ts", + "version": "0.1.0" +} diff --git a/identity-and-access/ts/seats/meshnodeenroller/src/index.ts b/identity-and-access/ts/seats/meshnodeenroller/index.d.ts similarity index 70% rename from identity-and-access/ts/seats/meshnodeenroller/src/index.ts rename to identity-and-access/ts/seats/meshnodeenroller/index.d.ts index 1312a13..2314949 100644 --- a/identity-and-access/ts/seats/meshnodeenroller/src/index.ts +++ b/identity-and-access/ts/seats/meshnodeenroller/index.d.ts @@ -2,74 +2,52 @@ // The contract of the seat "mesh-node-enroller", defined whole (seats/mesh-node-enroller/seat.json): The seat that enrols a new machine on the operator's Approve and a one-time token (ADR 0587). Renamed from mesh-enrolment (ADR 0634 §9). -export const seat = "mesh-node-enroller"; +export declare const seat: "mesh-node-enroller"; -export const verbs = { - issue: "issue", - redeem: "redeem", - confirm: "confirm", - revoke: "revoke", - tokens: "tokens", - again: "again", -} as const; +export declare const verbs: { + readonly issue: "issue"; + readonly redeem: "redeem"; + readonly confirm: "confirm"; + readonly revoke: "revoke"; + readonly tokens: "tokens"; + readonly again: "again"; +}; -export const events = { - enrolmentIssued: "enrolment-issued", - nodeEnrolled: "node-enrolled", - enrolmentRefused: "enrolment-refused", - enrolmentRevoked: "enrolment-revoked", - enrolmentExpired: "enrolment-expired", -} as const; +export declare const events: { + readonly enrolmentIssued: "enrolment-issued"; + readonly nodeEnrolled: "node-enrolled"; + readonly enrolmentRefused: "enrolment-refused"; + readonly enrolmentRevoked: "enrolment-revoked"; + readonly enrolmentExpired: "enrolment-expired"; +}; -export const family = { name: "mesh-node-enroller.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-node-enroller.events"; readonly maxAgeDays: 7 }; -export const enrolmentIssuedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-issued"; +export declare const enrolmentIssuedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-issued"; -export const nodeEnrolledSubject = "mesh.seat.mesh-node-enroller.event.node-enrolled"; +export declare const nodeEnrolledSubject: "mesh.seat.mesh-node-enroller.event.node-enrolled"; -export const enrolmentRefusedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-refused"; +export declare const enrolmentRefusedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-refused"; -export const enrolmentRevokedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-revoked"; +export declare const enrolmentRevokedSubject: "mesh.seat.mesh-node-enroller.event.enrolment-revoked"; -export const enrolmentExpiredSubject = "mesh.seat.mesh-node-enroller.event.enrolment-expired"; +export declare const enrolmentExpiredSubject: "mesh.seat.mesh-node-enroller.event.enrolment-expired"; -export const states = { - enrolments: "enrolments", -} as const; +export declare const states: { + readonly enrolments: "enrolments"; +}; /** The key of one value of the state enrolments under the form "node.". */ -export function enrolmentsByNodeNodeKey(node: string): string { - return "node." + node; -} +export declare function enrolmentsByNodeNodeKey(node: string): string; /** The parts of a key of the form "node.", or undefined for a key of another form. */ -export function parseEnrolmentsByNodeNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - if (!_rest.startsWith("node.")) return undefined; - _rest = _rest.slice(5); - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseEnrolmentsByNodeNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state enrolments under the form "address.
". */ -export function enrolmentsByAddressAddressKey(address: string): string { - return "address." + address; -} +export declare function enrolmentsByAddressAddressKey(address: string): string; /** The parts of a key of the form "address.
", or undefined for a key of another form. */ -export function parseEnrolmentsByAddressAddressKey(_key: string): { address: string } | undefined { - let _rest = _key; - if (!_rest.startsWith("address.")) return undefined; - _rest = _rest.slice(8); - if (_rest === "") return undefined; - const address = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { address }; -} +export declare function parseEnrolmentsByAddressAddressKey(_key: string): { address: string } | undefined; /** one open enrolment */ export interface Enrolment { diff --git a/identity-and-access/ts/seats/meshnodeenroller/index.js b/identity-and-access/ts/seats/meshnodeenroller/index.js new file mode 100644 index 0000000..23a4fb7 --- /dev/null +++ b/identity-and-access/ts/seats/meshnodeenroller/index.js @@ -0,0 +1,73 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-node-enroller", defined whole (seats/mesh-node-enroller/seat.json): The seat that enrols a new machine on the operator's Approve and a one-time token (ADR 0587). Renamed from mesh-enrolment (ADR 0634 §9). + +export const seat = "mesh-node-enroller"; + +export const verbs = { + issue: "issue", + redeem: "redeem", + confirm: "confirm", + revoke: "revoke", + tokens: "tokens", + again: "again", +}; + +export const events = { + enrolmentIssued: "enrolment-issued", + nodeEnrolled: "node-enrolled", + enrolmentRefused: "enrolment-refused", + enrolmentRevoked: "enrolment-revoked", + enrolmentExpired: "enrolment-expired", +}; + +export const family = { name: "mesh-node-enroller.events", maxAgeDays: 7 }; + +export const enrolmentIssuedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-issued"; + +export const nodeEnrolledSubject = "mesh.seat.mesh-node-enroller.event.node-enrolled"; + +export const enrolmentRefusedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-refused"; + +export const enrolmentRevokedSubject = "mesh.seat.mesh-node-enroller.event.enrolment-revoked"; + +export const enrolmentExpiredSubject = "mesh.seat.mesh-node-enroller.event.enrolment-expired"; + +export const states = { + enrolments: "enrolments", +}; + +/** The key of one value of the state enrolments under the form "node.". */ +export function enrolmentsByNodeNodeKey(node) { + return "node." + node; +} + +/** The parts of a key of the form "node.", or undefined for a key of another form. */ +export function parseEnrolmentsByNodeNodeKey(_key) { + let _rest = _key; + if (!_rest.startsWith("node.")) return undefined; + _rest = _rest.slice(5); + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state enrolments under the form "address.
". */ +export function enrolmentsByAddressAddressKey(address) { + return "address." + address; +} + +/** The parts of a key of the form "address.
", or undefined for a key of another form. */ +export function parseEnrolmentsByAddressAddressKey(_key) { + let _rest = _key; + if (!_rest.startsWith("address.")) return undefined; + _rest = _rest.slice(8); + if (_rest === "") return undefined; + const address = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { address }; +} + diff --git a/identity-and-access/ts/seats/meshnodeenroller/package-lock.json b/identity-and-access/ts/seats/meshnodeenroller/package-lock.json index 8e7f57d..97f7071 100644 --- a/identity-and-access/ts/seats/meshnodeenroller/package-lock.json +++ b/identity-and-access/ts/seats/meshnodeenroller/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller", + "name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller", "packages": { "": { - "name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller", + "name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller", "version": "0.1.0" } }, diff --git a/identity-and-access/ts/seats/meshnodeenroller/package.json b/identity-and-access/ts/seats/meshnodeenroller/package.json index 88192fc..7308ad7 100644 --- a/identity-and-access/ts/seats/meshnodeenroller/package.json +++ b/identity-and-access/ts/seats/meshnodeenroller/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-node-enroller, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-identity-and-access-contracts-mesh-node-enroller", + "name": "@novox/mesh-contracts-identity-and-access-mesh-node-enroller", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/identity-and-access/ts/seats/meshvault/src/index.ts b/identity-and-access/ts/seats/meshvault/index.d.ts similarity index 78% rename from identity-and-access/ts/seats/meshvault/src/index.ts rename to identity-and-access/ts/seats/meshvault/index.d.ts index e3f2c11..9179ae9 100644 --- a/identity-and-access/ts/seats/meshvault/src/index.ts +++ b/identity-and-access/ts/seats/meshvault/index.d.ts @@ -2,131 +2,84 @@ // The contract of the seat "mesh-vault", defined whole (seats/mesh-vault/seat.json): The mesh's secrets. accept and move-asks, which no holder served and nothing called, are left out (ADR 0620 §3). The vault's own events stay under its own subjects (ADR 0620 §2). -export const seat = "mesh-vault"; +export declare const seat: "mesh-vault"; -export const verbs = { - get: "get", - secretAsk: "secret-ask", - issued: "issued", - rotate: "rotate", - moveIn: "move-in", - nodeKey: "node-key", - own: "own", - issueAccount: "issue-account", - sign: "sign", - enrolmentToken: "enrolment-token", - nodeAccount: "node-account", - rotateNode: "rotate-node", - nodeAccountConfirm: "node-account-confirm", - abandon: "abandon", - retire: "retire", -} as const; +export declare const verbs: { + readonly get: "get"; + readonly secretAsk: "secret-ask"; + readonly issued: "issued"; + readonly rotate: "rotate"; + readonly moveIn: "move-in"; + readonly nodeKey: "node-key"; + readonly own: "own"; + readonly issueAccount: "issue-account"; + readonly sign: "sign"; + readonly enrolmentToken: "enrolment-token"; + readonly nodeAccount: "node-account"; + readonly rotateNode: "rotate-node"; + readonly nodeAccountConfirm: "node-account-confirm"; + readonly abandon: "abandon"; + readonly retire: "retire"; +}; -export const holderEvents = { - provisioned: "provisioned", - rotated: "rotated", - secretChanged: "secret-changed", - accountHashed: "account-hashed", - ownReplaced: "own-replaced", - accountIssued: "account-issued", - signed: "signed", - rotationBegun: "rotation-begun", - nodeAccountReady: "node-account-ready", - rotationDone: "rotation-done", - ownRetired: "own-retired", -} as const; +export declare const holderEvents: { + readonly provisioned: "provisioned"; + readonly rotated: "rotated"; + readonly secretChanged: "secret-changed"; + readonly accountHashed: "account-hashed"; + readonly ownReplaced: "own-replaced"; + readonly accountIssued: "account-issued"; + readonly signed: "signed"; + readonly rotationBegun: "rotation-begun"; + readonly nodeAccountReady: "node-account-ready"; + readonly rotationDone: "rotation-done"; + readonly ownRetired: "own-retired"; +}; -export function provisionedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.provisioned"; -} +export declare function provisionedHolderSubject(holder: string): string; -export function rotatedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.rotated"; -} +export declare function rotatedHolderSubject(holder: string): string; -export function secretChangedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.secret-changed"; -} +export declare function secretChangedHolderSubject(holder: string): string; -export function accountHashedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.account-hashed"; -} +export declare function accountHashedHolderSubject(holder: string): string; -export function ownReplacedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.own-replaced"; -} +export declare function ownReplacedHolderSubject(holder: string): string; -export function accountIssuedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.account-issued"; -} +export declare function accountIssuedHolderSubject(holder: string): string; -export function signedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.signed"; -} +export declare function signedHolderSubject(holder: string): string; -export function rotationBegunHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.rotation-begun"; -} +export declare function rotationBegunHolderSubject(holder: string): string; -export function nodeAccountReadyHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.node-account-ready"; -} +export declare function nodeAccountReadyHolderSubject(holder: string): string; -export function rotationDoneHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.rotation-done"; -} +export declare function rotationDoneHolderSubject(holder: string): string; -export function ownRetiredHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.own-retired"; -} +export declare function ownRetiredHolderSubject(holder: string): string; -export const states = { - signers: "signers", - nodeLogins: "node-logins", -} as const; +export declare const states: { + readonly signers: "signers"; + readonly nodeLogins: "node-logins"; +}; /** The key of one value of the state signers under the form "key". */ -export function signersByKeyKey(): string { - return "key"; -} +export declare function signersByKeyKey(): string; /** The parts of a key of the form "key", or undefined for a key of another form. */ -export function parseSignersByKeyKey(_key: string): { } | undefined { - let _rest = _key; - if (!_rest.startsWith("key")) return undefined; - _rest = _rest.slice(3); - if (_rest !== "") return undefined; - return { }; -} +export declare function parseSignersByKeyKey(_key: string): { } | undefined; /** The key of one value of the state signers under the form "authority". */ -export function signersByAuthorityKey(): string { - return "authority"; -} +export declare function signersByAuthorityKey(): string; /** The parts of a key of the form "authority", or undefined for a key of another form. */ -export function parseSignersByAuthorityKey(_key: string): { } | undefined { - let _rest = _key; - if (!_rest.startsWith("authority")) return undefined; - _rest = _rest.slice(9); - if (_rest !== "") return undefined; - return { }; -} +export declare function parseSignersByAuthorityKey(_key: string): { } | undefined; /** The key of one value of the state node-logins under the form "". */ -export function nodeLoginsByNodeKey(node: string): string { - return node; -} +export declare function nodeLoginsByNodeKey(node: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseNodeLoginsByNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseNodeLoginsByNodeKey(_key: string): { node: string } | undefined; /** is what get takes. */ export interface GetInput { diff --git a/identity-and-access/ts/seats/meshvault/index.js b/identity-and-access/ts/seats/meshvault/index.js new file mode 100644 index 0000000..793695b --- /dev/null +++ b/identity-and-access/ts/seats/meshvault/index.js @@ -0,0 +1,130 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-vault", defined whole (seats/mesh-vault/seat.json): The mesh's secrets. accept and move-asks, which no holder served and nothing called, are left out (ADR 0620 §3). The vault's own events stay under its own subjects (ADR 0620 §2). + +export const seat = "mesh-vault"; + +export const verbs = { + get: "get", + secretAsk: "secret-ask", + issued: "issued", + rotate: "rotate", + moveIn: "move-in", + nodeKey: "node-key", + own: "own", + issueAccount: "issue-account", + sign: "sign", + enrolmentToken: "enrolment-token", + nodeAccount: "node-account", + rotateNode: "rotate-node", + nodeAccountConfirm: "node-account-confirm", + abandon: "abandon", + retire: "retire", +}; + +export const holderEvents = { + provisioned: "provisioned", + rotated: "rotated", + secretChanged: "secret-changed", + accountHashed: "account-hashed", + ownReplaced: "own-replaced", + accountIssued: "account-issued", + signed: "signed", + rotationBegun: "rotation-begun", + nodeAccountReady: "node-account-ready", + rotationDone: "rotation-done", + ownRetired: "own-retired", +}; + +export function provisionedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.provisioned"; +} + +export function rotatedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.rotated"; +} + +export function secretChangedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.secret-changed"; +} + +export function accountHashedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.account-hashed"; +} + +export function ownReplacedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.own-replaced"; +} + +export function accountIssuedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.account-issued"; +} + +export function signedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.signed"; +} + +export function rotationBegunHolderSubject(holder) { + return "mesh.mod." + holder + ".event.rotation-begun"; +} + +export function nodeAccountReadyHolderSubject(holder) { + return "mesh.mod." + holder + ".event.node-account-ready"; +} + +export function rotationDoneHolderSubject(holder) { + return "mesh.mod." + holder + ".event.rotation-done"; +} + +export function ownRetiredHolderSubject(holder) { + return "mesh.mod." + holder + ".event.own-retired"; +} + +export const states = { + signers: "signers", + nodeLogins: "node-logins", +}; + +/** The key of one value of the state signers under the form "key". */ +export function signersByKeyKey() { + return "key"; +} + +/** The parts of a key of the form "key", or undefined for a key of another form. */ +export function parseSignersByKeyKey(_key) { + let _rest = _key; + if (!_rest.startsWith("key")) return undefined; + _rest = _rest.slice(3); + if (_rest !== "") return undefined; + return { }; +} + +/** The key of one value of the state signers under the form "authority". */ +export function signersByAuthorityKey() { + return "authority"; +} + +/** The parts of a key of the form "authority", or undefined for a key of another form. */ +export function parseSignersByAuthorityKey(_key) { + let _rest = _key; + if (!_rest.startsWith("authority")) return undefined; + _rest = _rest.slice(9); + if (_rest !== "") return undefined; + return { }; +} + +/** The key of one value of the state node-logins under the form "". */ +export function nodeLoginsByNodeKey(node) { + return node; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseNodeLoginsByNodeKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node }; +} + diff --git a/identity-and-access/ts/seats/meshvault/package-lock.json b/identity-and-access/ts/seats/meshvault/package-lock.json index c7aa797..76cfe8c 100644 --- a/identity-and-access/ts/seats/meshvault/package-lock.json +++ b/identity-and-access/ts/seats/meshvault/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-identity-and-access-contracts-mesh-vault", + "name": "@novox/mesh-contracts-identity-and-access-mesh-vault", "packages": { "": { - "name": "@novox/mesh-identity-and-access-contracts-mesh-vault", + "name": "@novox/mesh-contracts-identity-and-access-mesh-vault", "version": "0.1.0" } }, diff --git a/identity-and-access/ts/seats/meshvault/package.json b/identity-and-access/ts/seats/meshvault/package.json index 39944e5..a40e57a 100644 --- a/identity-and-access/ts/seats/meshvault/package.json +++ b/identity-and-access/ts/seats/meshvault/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-vault, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-identity-and-access-contracts-mesh-vault", + "name": "@novox/mesh-contracts-identity-and-access-mesh-vault", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/operator-and-conversation/go/seats/operatorchannel/contract.go b/operator-and-conversation/go/seats/operatorchannel/contract.go index 3e36498..4fd1a6d 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract.go @@ -15,11 +15,12 @@ import ( const Seat = "operator-channel" const ( - VerbOpen = "open" - VerbHistory = "history" - VerbNotify = "notify" - VerbTell = "tell" - VerbAsks = "asks" + VerbOpen = "open" + VerbHistory = "history" + VerbNotify = "notify" + VerbTell = "tell" + VerbAsks = "asks" + VerbAskAgain = "ask-again" ) const ( @@ -34,7 +35,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbOpen, VerbHistory, VerbNotify, VerbTell, VerbAsks} + return []string{VerbOpen, VerbHistory, VerbNotify, VerbTell, VerbAsks, VerbAskAgain} } // Events is every event published on the seat's subject: a new copy each call. @@ -433,15 +434,17 @@ type AsksInput struct { Key string `json:"key,omitempty"` // only the asks opened at or after this time, RFC 3339 Since string `json:"since,omitempty"` - // open (open and held), ended or all; none is open when no key or since is given, else all + // open (open, held and held-back), ended or all; none is open when no key or since is given, else all State string `json:"state,omitempty"` } // AsksAnswerAsksItem is a type of the contract. type AsksAnswerAsksItem struct { + // when the ask was held back, RFC 3339; present while its state is held-back + HeldSince string `json:"held-since,omitempty"` // . Key string `json:"key"` - // how the ask stands: open, held, or how it ended (answered, expired, cancelled) + // how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled) State string `json:"state"` } @@ -455,6 +458,19 @@ type AsksAnswer struct { Matched int64 `json:"matched,omitempty"` } +// AskAgainInput is what ask-again takes. +type AskAgainInput struct { + // . of the held-back ask + Key string `json:"key"` +} + +// AskAgainAnswer is what ask-again answers. +type AskAgainAnswer struct { + // why it was not offered; set alone + Error string `json:"error,omitempty"` + State string `json:"state,omitempty"` +} + // AskAccept is the body of ask. type AskAccept = Ask @@ -512,12 +528,14 @@ type AsksByAskerIDValue struct { Expires string `json:"expires"` // its headline Headline string `json:"headline"` + // when the ask was held back, RFC 3339; present while its state is held-back + HeldSince string `json:"held-since,omitempty"` // . Key string `json:"key"` // the channels it was offered on OfferedOn []string `json:"offered_on,omitempty"` // when it was opened, RFC 3339 Opened string `json:"opened"` - // how it stands: open, chosen, expired, cancelled, replaced or refused + // how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused State string `json:"state"` } diff --git a/operator-and-conversation/go/seats/operatorchannel/contract_test.go b/operator-and-conversation/go/seats/operatorchannel/contract_test.go index 440ac8a..aa1bd95 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract_test.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract_test.go @@ -35,6 +35,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "an ask its asker took back (captured)", subject: "", given: "{\"answer\":\"cancelled: its asker took it back\",\"asker\":\"mesh-delivery-teller\",\"asker_told\":true,\"expires\":\"2026-11-06T10:04:01Z\",\"headline\":\"Check failed - merge into main\",\"key\":\"mesh-delivery-teller.merge-feat_registry_milestone-3a038b9f8b4d-4-4da6ee3cd9d5\",\"offered_on\":[\"telegram\"],\"opened\":\"2026-11-05T10:14:04Z\",\"state\":\"cancelled\"}", wire: "{\"answer\":\"cancelled: its asker took it back\",\"asker\":\"mesh-delivery-teller\",\"asker_told\":true,\"expires\":\"2026-11-06T10:04:01Z\",\"headline\":\"Check failed - merge into main\",\"key\":\"mesh-delivery-teller.merge-feat_registry_milestone-3a038b9f8b4d-4-4da6ee3cd9d5\",\"offered_on\":[\"telegram\"],\"opened\":\"2026-11-05T10:14:04Z\",\"state\":\"cancelled\"}", decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a fourth ask, the asker's oldest held back behind newer ones", subject: "", given: "{\"asker\":\"mesh-delivery-teller\",\"expires\":\"2026-11-11T10:00:00Z\",\"headline\":\"Check failed - merge into main\",\"held-since\":\"2026-11-10T10:30:00Z\",\"key\":\"mesh-delivery-teller.b-1\",\"opened\":\"2026-11-10T10:00:00Z\",\"state\":\"held-back\"}", wire: "{\"asker\":\"mesh-delivery-teller\",\"expires\":\"2026-11-11T10:00:00Z\",\"headline\":\"Check failed - merge into main\",\"held-since\":\"2026-11-10T10:30:00Z\",\"key\":\"mesh-delivery-teller.b-1\",\"opened\":\"2026-11-10T10:00:00Z\",\"state\":\"held-back\"}", + decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/operator-and-conversation/ts/seats/operatorchannel/src/index.ts b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts similarity index 81% rename from operator-and-conversation/ts/seats/operatorchannel/src/index.ts rename to operator-and-conversation/ts/seats/operatorchannel/index.d.ts index ea709f8..43690c4 100644 --- a/operator-and-conversation/ts/seats/operatorchannel/src/index.ts +++ b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts @@ -2,84 +2,58 @@ // The contract of the seat "operator-channel", defined whole (seats/operator-channel/seat.json): Asking a person and answering on a channel (ADR 0259): held by the router, the messenger module, whose manifest declares the seat; written from that seat entry (design 26). -export const seat = "operator-channel"; +export declare const seat: "operator-channel"; -export const verbs = { - open: "open", - history: "history", - notify: "notify", - tell: "tell", - asks: "asks", -} as const; +export declare const verbs: { + readonly open: "open"; + readonly history: "history"; + readonly notify: "notify"; + readonly tell: "tell"; + readonly asks: "asks"; + readonly askAgain: "ask-again"; +}; -export const accepts = { - ask: "ask", - cancel: "cancel", - condition: "condition", -} as const; +export declare const accepts: { + readonly ask: "ask"; + readonly cancel: "cancel"; + readonly condition: "condition"; +}; -export const events = { - decided: "decided", -} as const; +export declare const events: { + readonly decided: "decided"; +}; -export const family = { name: "operator-channel.decided", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "operator-channel.decided"; readonly maxAgeDays: 7 }; -export function decidedSubject(caller: string): string { - return "mesh.seat.operator-channel.event.decided." + caller; -} +export declare function decidedSubject(caller: string): string; -export function askSubject(caller: string): string { - return "mesh.seat.operator-channel.accept.ask." + caller; -} +export declare function askSubject(caller: string): string; -export function cancelSubject(caller: string): string { - return "mesh.seat.operator-channel.accept.cancel." + caller; -} +export declare function cancelSubject(caller: string): string; -export function conditionSubject(caller: string): string { - return "mesh.seat.operator-channel.accept.condition." + caller; -} +export declare function conditionSubject(caller: string): string; -export const holderEvents = { - refused: "refused", - offered: "offered", - closed: "closed", -} as const; +export declare const holderEvents: { + readonly refused: "refused"; + readonly offered: "offered"; + readonly closed: "closed"; +}; -export function refusedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.refused"; -} +export declare function refusedHolderSubject(holder: string): string; -export function offeredHolderSubject(holder: string): string { - return "mesh.stream." + holder + ".event.offered"; -} +export declare function offeredHolderSubject(holder: string): string; -export function closedHolderSubject(holder: string): string { - return "mesh.stream." + holder + ".event.closed"; -} +export declare function closedHolderSubject(holder: string): string; -export const states = { - asks: "asks", -} as const; +export declare const states: { + readonly asks: "asks"; +}; /** The key of one value of the state asks under the form ".". */ -export function asksByAskerIDKey(asker: string, id: string): string { - return asker + "." + id; -} +export declare function asksByAskerIDKey(asker: string, id: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseAsksByAskerIDKey(_key: string): { asker: string; id: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const asker = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const id = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { asker, id }; -} +export declare function parseAsksByAskerIDKey(_key: string): { asker: string; id: string } | undefined; export interface Ask { /** what it is about: a newer ask about it replaces the older */ @@ -370,14 +344,16 @@ export interface AsksInput { "key"?: string; /** only the asks opened at or after this time, RFC 3339 */ "since"?: string; - /** open (open and held), ended or all; none is open when no key or since is given, else all */ + /** open (open, held and held-back), ended or all; none is open when no key or since is given, else all */ "state"?: string; } export interface AsksAnswerAsksItem { + /** when the ask was held back, RFC 3339; present while its state is held-back */ + "held-since"?: string; /** . */ "key": string; - /** how the ask stands: open, held, or how it ended (answered, expired, cancelled) */ + /** how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled) */ "state": string; } @@ -391,6 +367,19 @@ export interface AsksAnswer { "matched"?: number; } +/** is what ask-again takes. */ +export interface AskAgainInput { + /** . of the held-back ask */ + "key": string; +} + +/** is what ask-again answers. */ +export interface AskAgainAnswer { + /** why it was not offered; set alone */ + "error"?: string; + "state"?: string; +} + /** is the body of ask. */ export type AskAccept = Ask; @@ -439,13 +428,15 @@ export interface AsksByAskerIDValue { "expires": string; /** its headline */ "headline": string; + /** when the ask was held back, RFC 3339; present while its state is held-back */ + "held-since"?: string; /** . */ "key": string; /** the channels it was offered on */ "offered_on"?: string[]; /** when it was opened, RFC 3339 */ "opened": string; - /** how it stands: open, chosen, expired, cancelled, replaced or refused */ + /** how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused */ "state": string; } diff --git a/operator-and-conversation/ts/seats/operatorchannel/index.js b/operator-and-conversation/ts/seats/operatorchannel/index.js new file mode 100644 index 0000000..927f895 --- /dev/null +++ b/operator-and-conversation/ts/seats/operatorchannel/index.js @@ -0,0 +1,84 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "operator-channel", defined whole (seats/operator-channel/seat.json): Asking a person and answering on a channel (ADR 0259): held by the router, the messenger module, whose manifest declares the seat; written from that seat entry (design 26). + +export const seat = "operator-channel"; + +export const verbs = { + open: "open", + history: "history", + notify: "notify", + tell: "tell", + asks: "asks", + askAgain: "ask-again", +}; + +export const accepts = { + ask: "ask", + cancel: "cancel", + condition: "condition", +}; + +export const events = { + decided: "decided", +}; + +export const family = { name: "operator-channel.decided", maxAgeDays: 7 }; + +export function decidedSubject(caller) { + return "mesh.seat.operator-channel.event.decided." + caller; +} + +export function askSubject(caller) { + return "mesh.seat.operator-channel.accept.ask." + caller; +} + +export function cancelSubject(caller) { + return "mesh.seat.operator-channel.accept.cancel." + caller; +} + +export function conditionSubject(caller) { + return "mesh.seat.operator-channel.accept.condition." + caller; +} + +export const holderEvents = { + refused: "refused", + offered: "offered", + closed: "closed", +}; + +export function refusedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.refused"; +} + +export function offeredHolderSubject(holder) { + return "mesh.stream." + holder + ".event.offered"; +} + +export function closedHolderSubject(holder) { + return "mesh.stream." + holder + ".event.closed"; +} + +export const states = { + asks: "asks", +}; + +/** The key of one value of the state asks under the form ".". */ +export function asksByAskerIDKey(asker, id) { + return asker + "." + id; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseAsksByAskerIDKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const asker = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const id = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { asker, id }; +} + diff --git a/operator-and-conversation/ts/seats/operatorchannel/package-lock.json b/operator-and-conversation/ts/seats/operatorchannel/package-lock.json index 3061cb7..27e7d93 100644 --- a/operator-and-conversation/ts/seats/operatorchannel/package-lock.json +++ b/operator-and-conversation/ts/seats/operatorchannel/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-operator-and-conversation-contracts-operator-channel", + "name": "@novox/mesh-contracts-operator-and-conversation-operator-channel", "packages": { "": { - "name": "@novox/mesh-operator-and-conversation-contracts-operator-channel", + "name": "@novox/mesh-contracts-operator-and-conversation-operator-channel", "version": "0.1.0" } }, diff --git a/operator-and-conversation/ts/seats/operatorchannel/package.json b/operator-and-conversation/ts/seats/operatorchannel/package.json index 945f309..1cba008 100644 --- a/operator-and-conversation/ts/seats/operatorchannel/package.json +++ b/operator-and-conversation/ts/seats/operatorchannel/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat operator-channel, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-operator-and-conversation-contracts-operator-channel", + "name": "@novox/mesh-contracts-operator-and-conversation-operator-channel", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/provisioning/ts/seats/meshprovisioner/src/index.ts b/provisioning/ts/seats/meshprovisioner/index.d.ts similarity index 68% rename from provisioning/ts/seats/meshprovisioner/src/index.ts rename to provisioning/ts/seats/meshprovisioner/index.d.ts index 23c0e47..f262167 100644 --- a/provisioning/ts/seats/meshprovisioner/src/index.ts +++ b/provisioning/ts/seats/meshprovisioner/index.d.ts @@ -2,85 +2,34 @@ // The contract of the seat "mesh-provisioner", defined whole (seats/mesh-provisioner/seat.json): The provisioner (ADR 0349): which domain answers which kind of placeholder, what each module needs, what is applied where. -export const seat = "mesh-provisioner"; +export declare const seat: "mesh-provisioner"; -export const verbs = { - provisioning: "provisioning", -} as const; +export declare const verbs: { + readonly provisioning: "provisioning"; +}; -export const states = { - plans: "plans", - provisions: "provisions", -} as const; +export declare const states: { + readonly plans: "plans"; + readonly provisions: "provisions"; +}; /** The key of one value of the state plans under the form ".". */ -export function plansByNodeModuleKey(node: string, module: string): string { - return node + "." + module; -} +export declare function plansByNodeModuleKey(node: string, module: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parsePlansByNodeModuleKey(_key: string): { node: string; module: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const module = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module }; -} +export declare function parsePlansByNodeModuleKey(_key: string): { node: string; module: string } | undefined; /** The key of one value of the state provisions under the form "..". */ -export function provisionsByNodeConsumerProvisionKey(node: string, consumer: string, provision: string): string { - return node + "." + consumer + "." + provision; -} +export declare function provisionsByNodeConsumerProvisionKey(node: string, consumer: string, provision: string): string; /** The parts of a key of the form "..", or undefined for a key of another form. */ -export function parseProvisionsByNodeConsumerProvisionKey(_key: string): { node: string; consumer: string; provision: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - const _at2 = _rest.indexOf("."); - if (_at2 <= 0) return undefined; - const consumer = _rest.slice(0, _at2); - _rest = _rest.slice(_at2 + 1); - if (_rest === "") return undefined; - const provision = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, consumer, provision }; -} +export declare function parseProvisionsByNodeConsumerProvisionKey(_key: string): { node: string; consumer: string; provision: string } | undefined; /** The key of one value of the state provisions under the form "...". */ -export function provisionsByNodeConsumerProvisionLocalKey(node: string, consumer: string, provision: string, local: string): string { - return node + "." + consumer + "." + provision + "." + local; -} +export declare function provisionsByNodeConsumerProvisionLocalKey(node: string, consumer: string, provision: string, local: string): string; /** The parts of a key of the form "...", or undefined for a key of another form. */ -export function parseProvisionsByNodeConsumerProvisionLocalKey(_key: string): { node: string; consumer: string; provision: string; local: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - const _at2 = _rest.indexOf("."); - if (_at2 <= 0) return undefined; - const consumer = _rest.slice(0, _at2); - _rest = _rest.slice(_at2 + 1); - const _at4 = _rest.indexOf("."); - if (_at4 <= 0) return undefined; - const provision = _rest.slice(0, _at4); - _rest = _rest.slice(_at4 + 1); - if (_rest === "") return undefined; - const local = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, consumer, provision, local }; -} +export declare function parseProvisionsByNodeConsumerProvisionLocalKey(_key: string): { node: string; consumer: string; provision: string; local: string } | undefined; /** is what provisioning takes. */ export interface ProvisioningInput { diff --git a/provisioning/ts/seats/meshprovisioner/index.js b/provisioning/ts/seats/meshprovisioner/index.js new file mode 100644 index 0000000..9e51035 --- /dev/null +++ b/provisioning/ts/seats/meshprovisioner/index.js @@ -0,0 +1,84 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-provisioner", defined whole (seats/mesh-provisioner/seat.json): The provisioner (ADR 0349): which domain answers which kind of placeholder, what each module needs, what is applied where. + +export const seat = "mesh-provisioner"; + +export const verbs = { + provisioning: "provisioning", +}; + +export const states = { + plans: "plans", + provisions: "provisions", +}; + +/** The key of one value of the state plans under the form ".". */ +export function plansByNodeModuleKey(node, module) { + return node + "." + module; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parsePlansByNodeModuleKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const module = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module }; +} + +/** The key of one value of the state provisions under the form "..". */ +export function provisionsByNodeConsumerProvisionKey(node, consumer, provision) { + return node + "." + consumer + "." + provision; +} + +/** The parts of a key of the form "..", or undefined for a key of another form. */ +export function parseProvisionsByNodeConsumerProvisionKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const consumer = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); + if (_rest === "") return undefined; + const provision = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, consumer, provision }; +} + +/** The key of one value of the state provisions under the form "...". */ +export function provisionsByNodeConsumerProvisionLocalKey(node, consumer, provision, local) { + return node + "." + consumer + "." + provision + "." + local; +} + +/** The parts of a key of the form "...", or undefined for a key of another form. */ +export function parseProvisionsByNodeConsumerProvisionLocalKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const consumer = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); + const _at4 = _rest.indexOf("."); + if (_at4 <= 0) return undefined; + const provision = _rest.slice(0, _at4); + _rest = _rest.slice(_at4 + 1); + if (_rest === "") return undefined; + const local = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, consumer, provision, local }; +} + diff --git a/provisioning/ts/seats/meshprovisioner/package-lock.json b/provisioning/ts/seats/meshprovisioner/package-lock.json index fe0cee0..090754f 100644 --- a/provisioning/ts/seats/meshprovisioner/package-lock.json +++ b/provisioning/ts/seats/meshprovisioner/package-lock.json @@ -1,9 +1,9 @@ { "lockfileVersion": 3, - "name": "@novox/mesh-provisioning-contracts-mesh-provisioner", + "name": "@novox/mesh-contracts-provisioning-mesh-provisioner", "packages": { "": { - "name": "@novox/mesh-provisioning-contracts-mesh-provisioner", + "name": "@novox/mesh-contracts-provisioning-mesh-provisioner", "version": "0.1.0" } }, diff --git a/provisioning/ts/seats/meshprovisioner/package.json b/provisioning/ts/seats/meshprovisioner/package.json index 022c75d..4d8b9a7 100644 --- a/provisioning/ts/seats/meshprovisioner/package.json +++ b/provisioning/ts/seats/meshprovisioner/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-provisioner, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], - "name": "@novox/mesh-provisioning-contracts-mesh-provisioner", + "name": "@novox/mesh-contracts-provisioning-mesh-provisioner", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/ts/seats/meshbroker/src/index.ts b/ts/seats/meshbroker/index.d.ts similarity index 55% rename from ts/seats/meshbroker/src/index.ts rename to ts/seats/meshbroker/index.d.ts index a2b85a2..f3b0b53 100644 --- a/ts/seats/meshbroker/src/index.ts +++ b/ts/seats/meshbroker/index.d.ts @@ -2,55 +2,77 @@ // 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. -export const seat = "mesh-broker"; +export declare const seat: "mesh-broker"; -export const verbs = { - list: "list", - show: "show", - check: "check", - orphans: "orphans", - create: "create", - apply: "apply", - recreate: "recreate", - drop: "drop", -} as const; +export declare const verbs: { + readonly list: "list"; + readonly show: "show"; + readonly check: "check"; + readonly orphans: "orphans"; + readonly create: "create"; + readonly apply: "apply"; + readonly recreate: "recreate"; + readonly drop: "drop"; + readonly snapshotKept: "snapshot-kept"; + readonly restoreKept: "restore-kept"; +}; -export const events = { - created: "created", - refused: "refused", - drifted: "drifted", - driftCleared: "drift-cleared", - full: "full", - fullCleared: "full-cleared", - orphaned: "orphaned", - recreated: "recreated", - dropped: "dropped", -} as const; +export declare const events: { + readonly created: "created"; + readonly refused: "refused"; + readonly drifted: "drifted"; + readonly driftCleared: "drift-cleared"; + readonly full: "full"; + readonly fullCleared: "full-cleared"; + readonly orphaned: "orphaned"; + readonly recreated: "recreated"; + readonly dropped: "dropped"; +}; -export const family = { name: "mesh-broker.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-broker.events"; readonly maxAgeDays: 7 }; -export const createdSubject = "mesh.seat.mesh-broker.event.created"; +export declare const createdSubject: "mesh.seat.mesh-broker.event.created"; -export const refusedSubject = "mesh.seat.mesh-broker.event.refused"; +export declare const refusedSubject: "mesh.seat.mesh-broker.event.refused"; -export const driftedSubject = "mesh.seat.mesh-broker.event.drifted"; +export declare const driftedSubject: "mesh.seat.mesh-broker.event.drifted"; -export const driftClearedSubject = "mesh.seat.mesh-broker.event.drift-cleared"; +export declare const driftClearedSubject: "mesh.seat.mesh-broker.event.drift-cleared"; -export const fullSubject = "mesh.seat.mesh-broker.event.full"; +export declare const fullSubject: "mesh.seat.mesh-broker.event.full"; -export const fullClearedSubject = "mesh.seat.mesh-broker.event.full-cleared"; +export declare const fullClearedSubject: "mesh.seat.mesh-broker.event.full-cleared"; -export const orphanedSubject = "mesh.seat.mesh-broker.event.orphaned"; +export declare const orphanedSubject: "mesh.seat.mesh-broker.event.orphaned"; -export const recreatedSubject = "mesh.seat.mesh-broker.event.recreated"; +export declare const recreatedSubject: "mesh.seat.mesh-broker.event.recreated"; -export const droppedSubject = "mesh.seat.mesh-broker.event.dropped"; +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) */ export interface Binding { /** the entry's name on the bus */ "bus-name": string; + /** the bus name of the state's -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 */ @@ -109,6 +131,43 @@ 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; + "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; @@ -239,6 +298,64 @@ 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; + "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; diff --git a/ts/seats/meshbroker/index.js b/ts/seats/meshbroker/index.js new file mode 100644 index 0000000..b18e8ba --- /dev/null +++ b/ts/seats/meshbroker/index.js @@ -0,0 +1,51 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// 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. + +export const seat = "mesh-broker"; + +export const verbs = { + list: "list", + show: "show", + check: "check", + orphans: "orphans", + create: "create", + apply: "apply", + recreate: "recreate", + drop: "drop", + snapshotKept: "snapshot-kept", + restoreKept: "restore-kept", +}; + +export const events = { + created: "created", + refused: "refused", + drifted: "drifted", + driftCleared: "drift-cleared", + full: "full", + fullCleared: "full-cleared", + orphaned: "orphaned", + recreated: "recreated", + dropped: "dropped", +}; + +export const family = { name: "mesh-broker.events", maxAgeDays: 7 }; + +export const createdSubject = "mesh.seat.mesh-broker.event.created"; + +export const refusedSubject = "mesh.seat.mesh-broker.event.refused"; + +export const driftedSubject = "mesh.seat.mesh-broker.event.drifted"; + +export const driftClearedSubject = "mesh.seat.mesh-broker.event.drift-cleared"; + +export const fullSubject = "mesh.seat.mesh-broker.event.full"; + +export const fullClearedSubject = "mesh.seat.mesh-broker.event.full-cleared"; + +export const orphanedSubject = "mesh.seat.mesh-broker.event.orphaned"; + +export const recreatedSubject = "mesh.seat.mesh-broker.event.recreated"; + +export const droppedSubject = "mesh.seat.mesh-broker.event.dropped"; + diff --git a/ts/seats/meshbroker/package.json b/ts/seats/meshbroker/package.json index 0d845e8..03d00ef 100644 --- a/ts/seats/meshbroker/package.json +++ b/ts/seats/meshbroker/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-broker, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], "name": "@novox/mesh-contracts-mesh-broker", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/ts/seats/meshconfig/src/index.ts b/ts/seats/meshconfig/index.d.ts similarity index 58% rename from ts/seats/meshconfig/src/index.ts rename to ts/seats/meshconfig/index.d.ts index 7a6aa32..3188b8f 100644 --- a/ts/seats/meshconfig/src/index.ts +++ b/ts/seats/meshconfig/index.d.ts @@ -2,98 +2,44 @@ // The contract of the seat "mesh-config", defined whole (seats/mesh-config/seat.json): The mesh's config values: read and set one, and the renames still open. mesh-config's own events stay under its own subjects (ADR 0620 §2). -export const seat = "mesh-config"; +export declare const seat: "mesh-config"; -export const verbs = { - config: "config", - renames: "renames", -} as const; +export declare const verbs: { + readonly config: "config"; + readonly renames: "renames"; +}; -export const holderEvents = { - configChanged: "config-changed", - renamed: "renamed", - retiring: "retiring", - retired: "retired", -} as const; +export declare const holderEvents: { + readonly configChanged: "config-changed"; + readonly renamed: "renamed"; + readonly retiring: "retiring"; + readonly retired: "retired"; +}; -export function configChangedHolderSubject(holder: string): string { - return "mesh.mod." + holder + ".event.config-changed"; -} +export declare function configChangedHolderSubject(holder: string): string; -export function renamedHolderSubject(holder: string): string { - return "mesh.stream." + holder + ".event.renamed"; -} +export declare function renamedHolderSubject(holder: string): string; -export function retiringHolderSubject(holder: string): string { - return "mesh.stream." + holder + ".event.retiring"; -} +export declare function retiringHolderSubject(holder: string): string; -export function retiredHolderSubject(holder: string): string { - return "mesh.stream." + holder + ".event.retired"; -} +export declare function retiredHolderSubject(holder: string): string; -export const states = { - resolved: "resolved", - kept: "kept", -} as const; +export declare const states: { + readonly resolved: "resolved"; + readonly kept: "kept"; +}; /** The key of one value of the state resolved under the form "..". */ -export function resolvedByNodeModuleKeyKey(node: string, module: string, key: string): string { - return node + "." + module + "." + key; -} +export declare function resolvedByNodeModuleKeyKey(node: string, module: string, key: string): string; /** The parts of a key of the form "..", or undefined for a key of another form. */ -export function parseResolvedByNodeModuleKeyKey(_key: string): { node: string; module: string; key: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - const _at2 = _rest.indexOf("."); - if (_at2 <= 0) return undefined; - const module = _rest.slice(0, _at2); - _rest = _rest.slice(_at2 + 1); - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module, key }; -} +export declare function parseResolvedByNodeModuleKeyKey(_key: string): { node: string; module: string; key: string } | undefined; /** The key of one value of the state kept under the form ".....". */ -export function keptByOwnerRepositoryNumberNodeModuleKeyKey(owner: string, repository: string, number: string, node: string, module: string, key: string): string { - return owner + "." + repository + "." + number + "." + node + "." + module + "." + key; -} +export declare function keptByOwnerRepositoryNumberNodeModuleKeyKey(owner: string, repository: string, number: string, node: string, module: string, key: string): string; /** The parts of a key of the form ".....", or undefined for a key of another form. */ -export function parseKeptByOwnerRepositoryNumberNodeModuleKeyKey(_key: string): { owner: string; repository: string; number: string; node: string; module: string; key: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const owner = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - const _at2 = _rest.indexOf("."); - if (_at2 <= 0) return undefined; - const repository = _rest.slice(0, _at2); - _rest = _rest.slice(_at2 + 1); - const _at4 = _rest.indexOf("."); - if (_at4 <= 0) return undefined; - const number = _rest.slice(0, _at4); - _rest = _rest.slice(_at4 + 1); - const _at6 = _rest.indexOf("."); - if (_at6 <= 0) return undefined; - const node = _rest.slice(0, _at6); - _rest = _rest.slice(_at6 + 1); - const _at8 = _rest.indexOf("."); - if (_at8 <= 0) return undefined; - const module = _rest.slice(0, _at8); - _rest = _rest.slice(_at8 + 1); - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { owner, repository, number, node, module, key }; -} +export declare function parseKeptByOwnerRepositoryNumberNodeModuleKeyKey(_key: string): { owner: string; repository: string; number: string; node: string; module: string; key: string } | undefined; /** is what config takes. */ export interface ConfigInput { diff --git a/ts/seats/meshconfig/index.js b/ts/seats/meshconfig/index.js new file mode 100644 index 0000000..aeb7b3b --- /dev/null +++ b/ts/seats/meshconfig/index.js @@ -0,0 +1,97 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-config", defined whole (seats/mesh-config/seat.json): The mesh's config values: read and set one, and the renames still open. mesh-config's own events stay under its own subjects (ADR 0620 §2). + +export const seat = "mesh-config"; + +export const verbs = { + config: "config", + renames: "renames", +}; + +export const holderEvents = { + configChanged: "config-changed", + renamed: "renamed", + retiring: "retiring", + retired: "retired", +}; + +export function configChangedHolderSubject(holder) { + return "mesh.mod." + holder + ".event.config-changed"; +} + +export function renamedHolderSubject(holder) { + return "mesh.stream." + holder + ".event.renamed"; +} + +export function retiringHolderSubject(holder) { + return "mesh.stream." + holder + ".event.retiring"; +} + +export function retiredHolderSubject(holder) { + return "mesh.stream." + holder + ".event.retired"; +} + +export const states = { + resolved: "resolved", + kept: "kept", +}; + +/** The key of one value of the state resolved under the form "..". */ +export function resolvedByNodeModuleKeyKey(node, module, key) { + return node + "." + module + "." + key; +} + +/** The parts of a key of the form "..", or undefined for a key of another form. */ +export function parseResolvedByNodeModuleKeyKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const module = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module, key }; +} + +/** The key of one value of the state kept under the form ".....". */ +export function keptByOwnerRepositoryNumberNodeModuleKeyKey(owner, repository, number, node, module, key) { + return owner + "." + repository + "." + number + "." + node + "." + module + "." + key; +} + +/** The parts of a key of the form ".....", or undefined for a key of another form. */ +export function parseKeptByOwnerRepositoryNumberNodeModuleKeyKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const owner = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const repository = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); + const _at4 = _rest.indexOf("."); + if (_at4 <= 0) return undefined; + const number = _rest.slice(0, _at4); + _rest = _rest.slice(_at4 + 1); + const _at6 = _rest.indexOf("."); + if (_at6 <= 0) return undefined; + const node = _rest.slice(0, _at6); + _rest = _rest.slice(_at6 + 1); + const _at8 = _rest.indexOf("."); + if (_at8 <= 0) return undefined; + const module = _rest.slice(0, _at8); + _rest = _rest.slice(_at8 + 1); + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { owner, repository, number, node, module, key }; +} + diff --git a/ts/seats/meshconfig/package.json b/ts/seats/meshconfig/package.json index 3c4108c..fb29dd3 100644 --- a/ts/seats/meshconfig/package.json +++ b/ts/seats/meshconfig/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-config, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], "name": "@novox/mesh-contracts-mesh-config", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/ts/seats/meshmoduleassigner/src/index.ts b/ts/seats/meshmoduleassigner/index.d.ts similarity index 71% rename from ts/seats/meshmoduleassigner/src/index.ts rename to ts/seats/meshmoduleassigner/index.d.ts index 5ce1e00..b0f6280 100644 --- a/ts/seats/meshmoduleassigner/src/index.ts +++ b/ts/seats/meshmoduleassigner/index.d.ts @@ -2,181 +2,88 @@ // The contract of the seat "mesh-module-assigner", defined whole (seats/mesh-module-assigner/seat.json): The seat that places modules on nodes (ADR 0567): the state of assignments and the proposals that change it. -export const seat = "mesh-module-assigner"; +export declare const seat: "mesh-module-assigner"; -export const verbs = { - assignments: "assignments", - proposals: "proposals", - propose: "propose", - withdraw: "withdraw", - again: "again", -} as const; +export declare const verbs: { + readonly assignments: "assignments"; + readonly proposals: "proposals"; + readonly propose: "propose"; + readonly withdraw: "withdraw"; + readonly again: "again"; +}; -export const events = { - assignmentsProposed: "assignments-proposed", - assignmentsWithdrawn: "assignments-withdrawn", - assignmentsJudged: "assignments-judged", - assignmentsChanged: "assignments-changed", -} as const; +export declare const events: { + readonly assignmentsProposed: "assignments-proposed"; + readonly assignmentsWithdrawn: "assignments-withdrawn"; + readonly assignmentsJudged: "assignments-judged"; + readonly assignmentsChanged: "assignments-changed"; +}; -export const family = { name: "mesh-module-assigner.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "mesh-module-assigner.events"; readonly maxAgeDays: 7 }; -export const assignmentsProposedSubject = "mesh.seat.mesh-module-assigner.event.assignments-proposed"; +export declare const assignmentsProposedSubject: "mesh.seat.mesh-module-assigner.event.assignments-proposed"; -export const assignmentsWithdrawnSubject = "mesh.seat.mesh-module-assigner.event.assignments-withdrawn"; +export declare const assignmentsWithdrawnSubject: "mesh.seat.mesh-module-assigner.event.assignments-withdrawn"; -export const assignmentsJudgedSubject = "mesh.seat.mesh-module-assigner.event.assignments-judged"; +export declare const assignmentsJudgedSubject: "mesh.seat.mesh-module-assigner.event.assignments-judged"; -export const assignmentsChangedSubject = "mesh.seat.mesh-module-assigner.event.assignments-changed"; +export declare const assignmentsChangedSubject: "mesh.seat.mesh-module-assigner.event.assignments-changed"; -export const states = { - assignments: "assignments", - proposals: "proposals", - candidates: "candidates", - pulses: "pulses", - seatHolders: "seat-holders", -} as const; +export declare const states: { + readonly assignments: "assignments"; + readonly proposals: "proposals"; + readonly candidates: "candidates"; + readonly pulses: "pulses"; + readonly seatHolders: "seat-holders"; +}; /** The key of one value of the state assignments under the form ".node". */ -export function assignmentsByNodeNodeKey(node: string): string { - return node + ".node"; -} +export declare function assignmentsByNodeNodeKey(node: string): string; /** The parts of a key of the form ".node", or undefined for a key of another form. */ -export function parseAssignmentsByNodeNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf(".node"); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 5); - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseAssignmentsByNodeNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state assignments under the form ".". */ -export function assignmentsByNodeModuleKey(node: string, module: string): string { - return node + "." + module; -} +export declare function assignmentsByNodeModuleKey(node: string, module: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseAssignmentsByNodeModuleKey(_key: string): { node: string; module: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const module = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module }; -} +export declare function parseAssignmentsByNodeModuleKey(_key: string): { node: string; module: string } | undefined; /** The key of one value of the state proposals under the form "". */ -export function proposalsByProposalKey(proposal: string): string { - return proposal; -} +export declare function proposalsByProposalKey(proposal: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseProposalsByProposalKey(_key: string): { proposal: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const proposal = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { proposal }; -} +export declare function parseProposalsByProposalKey(_key: string): { proposal: string } | undefined; /** The key of one value of the state candidates under the form ".". */ -export function candidatesByProposalNodeKey(proposal: string, node: string): string { - return proposal + "." + node; -} +export declare function candidatesByProposalNodeKey(proposal: string, node: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseCandidatesByProposalNodeKey(_key: string): { proposal: string; node: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const proposal = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { proposal, node }; -} +export declare function parseCandidatesByProposalNodeKey(_key: string): { proposal: string; node: string } | undefined; /** The key of one value of the state pulses under the form "answer..". */ -export function pulsesByAnswerProposalNodeKey(proposal: string, node: string): string { - return "answer." + proposal + "." + node; -} +export declare function pulsesByAnswerProposalNodeKey(proposal: string, node: string): string; /** The parts of a key of the form "answer..", or undefined for a key of another form. */ -export function parsePulsesByAnswerProposalNodeKey(_key: string): { proposal: string; node: string } | undefined { - let _rest = _key; - if (!_rest.startsWith("answer.")) return undefined; - _rest = _rest.slice(7); - const _at1 = _rest.indexOf("."); - if (_at1 <= 0) return undefined; - const proposal = _rest.slice(0, _at1); - _rest = _rest.slice(_at1 + 1); - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { proposal, node }; -} +export declare function parsePulsesByAnswerProposalNodeKey(_key: string): { proposal: string; node: string } | undefined; /** The key of one value of the state pulses under the form "ask.". */ -export function pulsesByAskProposalKey(proposal: string): string { - return "ask." + proposal; -} +export declare function pulsesByAskProposalKey(proposal: string): string; /** The parts of a key of the form "ask.", or undefined for a key of another form. */ -export function parsePulsesByAskProposalKey(_key: string): { proposal: string } | undefined { - let _rest = _key; - if (!_rest.startsWith("ask.")) return undefined; - _rest = _rest.slice(4); - if (_rest === "") return undefined; - const proposal = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { proposal }; -} +export declare function parsePulsesByAskProposalKey(_key: string): { proposal: string } | undefined; /** The key of one value of the state seat-holders under the form "". */ -export function seatHoldersBySeatKey(seat: string): string { - return seat; -} +export declare function seatHoldersBySeatKey(seat: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseSeatHoldersBySeatKey(_key: string): { seat: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const seat = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { seat }; -} +export declare function parseSeatHoldersBySeatKey(_key: string): { seat: string } | undefined; /** The key of one value of the state seat-holders under the form ".". */ -export function seatHoldersBySeatNodeKey(seat: string, node: string): string { - return seat + "." + node; -} +export declare function seatHoldersBySeatNodeKey(seat: string, node: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseSeatHoldersBySeatNodeKey(_key: string): { seat: string; node: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const seat = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { seat, node }; -} +export declare function parseSeatHoldersBySeatNodeKey(_key: string): { seat: string; node: string } | undefined; /** one node's assignments assembled */ export interface Assignments { @@ -259,6 +166,10 @@ export interface NodeDecided { export interface PlacedModule { /** by provision, the provider each requirement that keeps data is bound to */ "bindings"?: Record; + /** the watched branch this node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14) */ + "branch"?: string; + /** the fingerprint of the build the node runs; absent, the newest delivered of the branch (design 47 G 78, 402) */ + "build"?: string; "has-layer"?: boolean; "has-mesh-wide"?: boolean; /** this node's settings layer of the module's assignments */ @@ -310,6 +221,10 @@ export interface ProposalChangeKeys { /** one change of a proposal */ export interface ProposalChange { "bindings"?: Record; + /** for place, the watched branch the node runs the module from; absent, the first watched branch of the module's registration (design 47 G 14) */ + "branch"?: string; + /** for place, the build of that branch the node runs, a return to an earlier build being this one value; absent, the newest delivered of the branch (ADR 0666 section 24) */ + "build"?: string; "claim"?: string; "decided"?: NodeDecided; "field"?: string; diff --git a/ts/seats/meshmoduleassigner/index.js b/ts/seats/meshmoduleassigner/index.js new file mode 100644 index 0000000..654af67 --- /dev/null +++ b/ts/seats/meshmoduleassigner/index.js @@ -0,0 +1,180 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-module-assigner", defined whole (seats/mesh-module-assigner/seat.json): The seat that places modules on nodes (ADR 0567): the state of assignments and the proposals that change it. + +export const seat = "mesh-module-assigner"; + +export const verbs = { + assignments: "assignments", + proposals: "proposals", + propose: "propose", + withdraw: "withdraw", + again: "again", +}; + +export const events = { + assignmentsProposed: "assignments-proposed", + assignmentsWithdrawn: "assignments-withdrawn", + assignmentsJudged: "assignments-judged", + assignmentsChanged: "assignments-changed", +}; + +export const family = { name: "mesh-module-assigner.events", maxAgeDays: 7 }; + +export const assignmentsProposedSubject = "mesh.seat.mesh-module-assigner.event.assignments-proposed"; + +export const assignmentsWithdrawnSubject = "mesh.seat.mesh-module-assigner.event.assignments-withdrawn"; + +export const assignmentsJudgedSubject = "mesh.seat.mesh-module-assigner.event.assignments-judged"; + +export const assignmentsChangedSubject = "mesh.seat.mesh-module-assigner.event.assignments-changed"; + +export const states = { + assignments: "assignments", + proposals: "proposals", + candidates: "candidates", + pulses: "pulses", + seatHolders: "seat-holders", +}; + +/** The key of one value of the state assignments under the form ".node". */ +export function assignmentsByNodeNodeKey(node) { + return node + ".node"; +} + +/** The parts of a key of the form ".node", or undefined for a key of another form. */ +export function parseAssignmentsByNodeNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf(".node"); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 5); + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state assignments under the form ".". */ +export function assignmentsByNodeModuleKey(node, module) { + return node + "." + module; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseAssignmentsByNodeModuleKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const module = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module }; +} + +/** The key of one value of the state proposals under the form "". */ +export function proposalsByProposalKey(proposal) { + return proposal; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseProposalsByProposalKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const proposal = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { proposal }; +} + +/** The key of one value of the state candidates under the form ".". */ +export function candidatesByProposalNodeKey(proposal, node) { + return proposal + "." + node; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseCandidatesByProposalNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const proposal = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { proposal, node }; +} + +/** The key of one value of the state pulses under the form "answer..". */ +export function pulsesByAnswerProposalNodeKey(proposal, node) { + return "answer." + proposal + "." + node; +} + +/** The parts of a key of the form "answer..", or undefined for a key of another form. */ +export function parsePulsesByAnswerProposalNodeKey(_key) { + let _rest = _key; + if (!_rest.startsWith("answer.")) return undefined; + _rest = _rest.slice(7); + const _at1 = _rest.indexOf("."); + if (_at1 <= 0) return undefined; + const proposal = _rest.slice(0, _at1); + _rest = _rest.slice(_at1 + 1); + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { proposal, node }; +} + +/** The key of one value of the state pulses under the form "ask.". */ +export function pulsesByAskProposalKey(proposal) { + return "ask." + proposal; +} + +/** The parts of a key of the form "ask.", or undefined for a key of another form. */ +export function parsePulsesByAskProposalKey(_key) { + let _rest = _key; + if (!_rest.startsWith("ask.")) return undefined; + _rest = _rest.slice(4); + if (_rest === "") return undefined; + const proposal = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { proposal }; +} + +/** The key of one value of the state seat-holders under the form "". */ +export function seatHoldersBySeatKey(seat) { + return seat; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseSeatHoldersBySeatKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const seat = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { seat }; +} + +/** The key of one value of the state seat-holders under the form ".". */ +export function seatHoldersBySeatNodeKey(seat, node) { + return seat + "." + node; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseSeatHoldersBySeatNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const seat = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { seat, node }; +} + diff --git a/ts/seats/meshmoduleassigner/package.json b/ts/seats/meshmoduleassigner/package.json index e7e83e9..5d8ff33 100644 --- a/ts/seats/meshmoduleassigner/package.json +++ b/ts/seats/meshmoduleassigner/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat mesh-module-assigner, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], "name": "@novox/mesh-contracts-mesh-module-assigner", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } diff --git a/ts/seats/nodeengine/src/index.ts b/ts/seats/nodeengine/index.d.ts similarity index 81% rename from ts/seats/nodeengine/src/index.ts rename to ts/seats/nodeengine/index.d.ts index d68248e..78d31e4 100644 --- a/ts/seats/nodeengine/src/index.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -1,196 +1,116 @@ // Code generated by seatgen from the seat definitions; DO NOT EDIT. -// The contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token. +// The contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2). -export const seat = "node-engine"; +export declare const seat: "node-engine"; -export const verbs = { - handOver: "hand-over", - accessAct: "access-act", - judgeDirectories: "judge-directories", - setuidSearch: "setuid-search", - rootFree: "root-free", - acts: "acts", - packages: "packages", - composition: "composition", - compose: "compose", - composeCandidate: "compose-candidate", - manifestReads: "manifest-reads", - seatList: "seat-list", - seatListAgain: "seat-list-again", -} as const; +export declare const verbs: { + readonly handOver: "hand-over"; + readonly accessAct: "access-act"; + readonly judgeDirectories: "judge-directories"; + readonly setuidSearch: "setuid-search"; + readonly rootFree: "root-free"; + readonly acts: "acts"; + readonly packages: "packages"; + readonly composition: "composition"; + readonly compose: "compose"; + readonly composeCandidate: "compose-candidate"; + readonly manifestReads: "manifest-reads"; + readonly seatList: "seat-list"; + readonly seatListAgain: "seat-list-again"; + readonly processBuilds: "process-builds"; +}; -export const events = { - asked: "asked", - done: "done", - refused: "refused", - manifestReadsChanged: "manifest-reads-changed", -} as const; +export declare const events: { + readonly asked: "asked"; + readonly done: "done"; + readonly refused: "refused"; + readonly manifestReadsChanged: "manifest-reads-changed"; + readonly composed: "composed"; + readonly running: "running"; + readonly capabilitiesChanged: "capabilities-changed"; +}; -export const family = { name: "node-engine.events", maxAgeDays: 7 } as const; +export declare const family: { readonly name: "node-engine.events"; readonly maxAgeDays: 7 }; -export function askedSubject(caller: string): string { - return "mesh.seat.node-engine.event.asked." + caller; -} +export declare function askedSubject(caller: string): string; -export function doneSubject(caller: string): string { - return "mesh.seat.node-engine.event.done." + caller; -} +export declare function doneSubject(caller: string): string; -export function refusedSubject(caller: string): string { - return "mesh.seat.node-engine.event.refused." + caller; -} +export declare function refusedSubject(caller: string): string; -export function manifestReadsChangedSubject(caller: string): string { - return "mesh.seat.node-engine.event.manifest-reads-changed." + caller; -} +export declare function manifestReadsChangedSubject(caller: string): string; -export const states = { - have: "have", - composed: "composed", - data: "data", - packages: "packages", - health: "health", - findings: "findings", -} as const; +export declare function composedSubject(node: string): string; + +export declare const composedSubjectAll: "mesh.seat.node-engine.event.composed.*"; + +export declare const runningStream: "SEAT_node-engine_running"; + +export declare function runningSubject(node: string, module: string): string; + +export declare const runningSubjectAll: "mesh.seat.node-engine.event.running.*.*"; + +export declare function capabilitiesChangedSubject(node: string): string; + +export declare const capabilitiesChangedSubjectAll: "mesh.seat.node-engine.event.capabilities-changed.*"; + +export declare const states: { + readonly have: "have"; + readonly composed: "composed"; + readonly data: "data"; + readonly packages: "packages"; + readonly health: "health"; + readonly findings: "findings"; +}; /** The key of one value of the state have under the form ".". */ -export function haveByNodeModuleKey(node: string, module: string): string { - return node + "." + module; -} +export declare function haveByNodeModuleKey(node: string, module: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseHaveByNodeModuleKey(_key: string): { node: string; module: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const module = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module }; -} +export declare function parseHaveByNodeModuleKey(_key: string): { node: string; module: string } | undefined; /** The key of one value of the state have under the form ".node". */ -export function haveByNodeNodeKey(node: string): string { - return node + ".node"; -} +export declare function haveByNodeNodeKey(node: string): string; /** The parts of a key of the form ".node", or undefined for a key of another form. */ -export function parseHaveByNodeNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf(".node"); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 5); - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseHaveByNodeNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state composed under the form "..". */ -export function composedByNodeModuleFingerprintKey(node: string, module: string, fingerprint: string): string { - return node + "." + module + "." + fingerprint; -} +export declare function composedByNodeModuleFingerprintKey(node: string, module: string, fingerprint: string): string; /** The parts of a key of the form "..", or undefined for a key of another form. */ -export function parseComposedByNodeModuleFingerprintKey(_key: string): { node: string; module: string; fingerprint: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - const _at2 = _rest.indexOf("."); - if (_at2 <= 0) return undefined; - const module = _rest.slice(0, _at2); - _rest = _rest.slice(_at2 + 1); - if (_rest === "") return undefined; - const fingerprint = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module, fingerprint }; -} +export declare function parseComposedByNodeModuleFingerprintKey(_key: string): { node: string; module: string; fingerprint: string } | undefined; /** The key of one value of the state composed under the form ".node". */ -export function composedByNodeNodeKey(node: string): string { - return node + ".node"; -} +export declare function composedByNodeNodeKey(node: string): string; /** The parts of a key of the form ".node", or undefined for a key of another form. */ -export function parseComposedByNodeNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf(".node"); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 5); - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseComposedByNodeNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state data under the form ".". */ -export function dataByNodeModuleKey(node: string, module: string): string { - return node + "." + module; -} +export declare function dataByNodeModuleKey(node: string, module: string): string; /** The parts of a key of the form ".", or undefined for a key of another form. */ -export function parseDataByNodeModuleKey(_key: string): { node: string; module: string } | undefined { - let _rest = _key; - const _at0 = _rest.indexOf("."); - if (_at0 <= 0) return undefined; - const node = _rest.slice(0, _at0); - _rest = _rest.slice(_at0 + 1); - if (_rest === "") return undefined; - const module = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node, module }; -} +export declare function parseDataByNodeModuleKey(_key: string): { node: string; module: string } | undefined; /** The key of one value of the state packages under the form "". */ -export function packagesByNodeKey(node: string): string { - return node; -} +export declare function packagesByNodeKey(node: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parsePackagesByNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node }; -} +export declare function parsePackagesByNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state health under the form "". */ -export function healthByNodeKey(node: string): string { - return node; -} +export declare function healthByNodeKey(node: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseHealthByNodeKey(_key: string): { node: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const node = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { node }; -} +export declare function parseHealthByNodeKey(_key: string): { node: string } | undefined; /** The key of one value of the state findings under the form "". */ -export function findingsByKeyKey(key: string): string { - return key; -} +export declare function findingsByKeyKey(key: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseFindingsByKeyKey(_key: string): { key: string } | undefined { - let _rest = _key; - if (_rest === "") return undefined; - const key = _rest; - _rest = ""; - if (_rest !== "") return undefined; - return { key }; -} +export declare function parseFindingsByKeyKey(_key: string): { key: string } | undefined; /** the hashes of the users of the list, sealed to the vault */ export interface AccountsHanded { @@ -347,6 +267,34 @@ export interface CandidateRefusal { "why": string; } +/** a node's capabilities changed, which the assigner places by */ +export interface CapabilitiesChanged { + /** when, RFC 3339 */ + "at": string; + /** its capabilities now */ + "capabilities": string[]; + /** the node */ + "node": string; + /** the layout's version */ + "v": number; +} + +/** an entry composed on a node (design 47 *What each step says*) */ +export interface Composed { + /** when, RFC 3339 */ + "at": string; + /** the digest of the composition (design 47 G 404) */ + "digest": string; + /** the fingerprint of the want composed */ + "fingerprint": string; + /** the module */ + "module": string; + /** the node */ + "node": string; + /** the layout's version */ + "v": number; +} + /** a group */ export interface DeclaredGroup { "gid": number; @@ -547,6 +495,32 @@ export interface PlacedDataItem { "protection"?: string; } +/** the build one process of a module was started with */ +export interface ProcessBuild { + /** the fingerprint handed to it in MESH_FINGERPRINT; empty when it was started without one */ + "fingerprint"?: string; + /** service or container */ + "kind": "service" | "container"; + /** the module */ + "module": string; + /** the service's unit or the container's name */ + "process": string; + /** when it was started, RFC 3339 */ + "started"?: string; + /** why its build is unknown: started before the node-engine handed MESH_FINGERPRINT, or the value could not be read */ + "unknown"?: string; +} + +/** what process-builds answers */ +export interface ProcessBuilds { + /** why they could not be read */ + "error"?: string; + /** the node */ + "node": string; + /** every process the node-engine started, by module */ + "processes": ProcessBuild[]; +} + /** the pull from a store a failed apply waits on */ export interface PullWait { /** when the pull began */ @@ -601,6 +575,24 @@ export interface RootVerdict { "why": string; } +/** a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit */ +export interface Running { + /** when it was seen running healthy, RFC 3339 */ + "at": string; + /** the fingerprint of the build it runs; none with stopped */ + "fingerprint"?: string; + /** the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half */ + "manifest"?: string; + /** the module */ + "module": string; + /** the node */ + "node": string; + /** true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there */ + "stopped"?: boolean; + /** the layout's version */ + "v": number; +} + /** the answer of a read-only judgement */ export interface Said { /** the node */ @@ -999,6 +991,15 @@ export interface SeatListAgainInput { /** is what seat-list-again answers. */ export type SeatListAgainAnswer = SeatList; +/** is what process-builds takes. */ +export interface ProcessBuildsInput { + /** only this module's processes */ + "module"?: string; +} + +/** is what process-builds answers. */ +export type ProcessBuildsAnswer = ProcessBuilds; + /** is the body of the event asked. */ export type AskedEvent = ActSaid; @@ -1011,6 +1012,15 @@ export type RefusedEvent = ActSaid; /** is the body of the event manifest-reads-changed. */ export type ManifestReadsChangedEvent = ManifestReadsChanged; +/** is the body of the event composed. */ +export type ComposedEvent = Composed; + +/** is the body of the event running. */ +export type RunningEvent = Running; + +/** is the body of the event capabilities-changed. */ +export type CapabilitiesChangedEvent = CapabilitiesChanged; + /** is one value of the state have under the key .. */ export interface HaveByNodeModuleValue { "build"?: string; diff --git a/ts/seats/nodeengine/index.js b/ts/seats/nodeengine/index.js new file mode 100644 index 0000000..1cb7831 --- /dev/null +++ b/ts/seats/nodeengine/index.js @@ -0,0 +1,218 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2). + +export const seat = "node-engine"; + +export const verbs = { + handOver: "hand-over", + accessAct: "access-act", + judgeDirectories: "judge-directories", + setuidSearch: "setuid-search", + rootFree: "root-free", + acts: "acts", + packages: "packages", + composition: "composition", + compose: "compose", + composeCandidate: "compose-candidate", + manifestReads: "manifest-reads", + seatList: "seat-list", + seatListAgain: "seat-list-again", + processBuilds: "process-builds", +}; + +export const events = { + asked: "asked", + done: "done", + refused: "refused", + manifestReadsChanged: "manifest-reads-changed", + composed: "composed", + running: "running", + capabilitiesChanged: "capabilities-changed", +}; + +export const family = { name: "node-engine.events", maxAgeDays: 7 }; + +export function askedSubject(caller) { + return "mesh.seat.node-engine.event.asked." + caller; +} + +export function doneSubject(caller) { + return "mesh.seat.node-engine.event.done." + caller; +} + +export function refusedSubject(caller) { + return "mesh.seat.node-engine.event.refused." + caller; +} + +export function manifestReadsChangedSubject(caller) { + return "mesh.seat.node-engine.event.manifest-reads-changed." + caller; +} + +export function composedSubject(node) { + return "mesh.seat.node-engine.event.composed." + node; +} + +export const composedSubjectAll = "mesh.seat.node-engine.event.composed.*"; + +export const runningStream = "SEAT_node-engine_running"; + +export function runningSubject(node, module) { + return "mesh.seat.node-engine.event.running." + node + "." + module; +} + +export const runningSubjectAll = "mesh.seat.node-engine.event.running.*.*"; + +export function capabilitiesChangedSubject(node) { + return "mesh.seat.node-engine.event.capabilities-changed." + node; +} + +export const capabilitiesChangedSubjectAll = "mesh.seat.node-engine.event.capabilities-changed.*"; + +export const states = { + have: "have", + composed: "composed", + data: "data", + packages: "packages", + health: "health", + findings: "findings", +}; + +/** The key of one value of the state have under the form ".". */ +export function haveByNodeModuleKey(node, module) { + return node + "." + module; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseHaveByNodeModuleKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const module = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module }; +} + +/** The key of one value of the state have under the form ".node". */ +export function haveByNodeNodeKey(node) { + return node + ".node"; +} + +/** The parts of a key of the form ".node", or undefined for a key of another form. */ +export function parseHaveByNodeNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf(".node"); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 5); + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state composed under the form "..". */ +export function composedByNodeModuleFingerprintKey(node, module, fingerprint) { + return node + "." + module + "." + fingerprint; +} + +/** The parts of a key of the form "..", or undefined for a key of another form. */ +export function parseComposedByNodeModuleFingerprintKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const module = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); + if (_rest === "") return undefined; + const fingerprint = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module, fingerprint }; +} + +/** The key of one value of the state composed under the form ".node". */ +export function composedByNodeNodeKey(node) { + return node + ".node"; +} + +/** The parts of a key of the form ".node", or undefined for a key of another form. */ +export function parseComposedByNodeNodeKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf(".node"); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 5); + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state data under the form ".". */ +export function dataByNodeModuleKey(node, module) { + return node + "." + module; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseDataByNodeModuleKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const node = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const module = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node, module }; +} + +/** The key of one value of the state packages under the form "". */ +export function packagesByNodeKey(node) { + return node; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parsePackagesByNodeKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state health under the form "". */ +export function healthByNodeKey(node) { + return node; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseHealthByNodeKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const node = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { node }; +} + +/** The key of one value of the state findings under the form "". */ +export function findingsByKeyKey(key) { + return key; +} + +/** The parts of a key of the form "", or undefined for a key of another form. */ +export function parseFindingsByKeyKey(_key) { + let _rest = _key; + if (_rest === "") return undefined; + const key = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { key }; +} + diff --git a/ts/seats/nodeengine/package.json b/ts/seats/nodeengine/package.json index b7ac56a..1f2319e 100644 --- a/ts/seats/nodeengine/package.json +++ b/ts/seats/nodeengine/package.json @@ -1,13 +1,18 @@ { "description": "The contract of the seat node-engine, generated from its definition.", "exports": { - ".": "./src/index.ts" + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } }, "files": [ - "src" + "index.js", + "index.d.ts", + "parts" ], "name": "@novox/mesh-contracts-node-engine", "type": "module", - "types": "./src/index.ts", + "types": "./index.d.ts", "version": "0.1.0" } From 5f7610f521bdb65ef72728022049d015e27ee93b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 10:45:58 +0100 Subject: [PATCH 17/62] C5 (answer): the node-engine's verbs name their class MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit hand-over and access-act are warrants, compose an act, the other six without callers reads. Builds: design 47 G §391, §393, §447 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/seat.json | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 63159fe..af5875e 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -35,7 +35,8 @@ }, "answer": { "$ref": "#/defs/Asked" - } + }, + "class": "warrant" }, { "name": "access-act", @@ -63,7 +64,8 @@ }, "answer": { "$ref": "#/defs/Asked" - } + }, + "class": "warrant" }, { "name": "judge-directories", @@ -74,7 +76,8 @@ }, "answer": { "$ref": "#/defs/Said" - } + }, + "class": "read" }, { "name": "setuid-search", @@ -90,7 +93,8 @@ }, "answer": { "$ref": "#/defs/Said" - } + }, + "class": "read" }, { "name": "root-free", @@ -113,7 +117,8 @@ "required": [ "machines" ] - } + }, + "class": "read" }, { "name": "acts", @@ -133,7 +138,8 @@ }, "answer": { "$ref": "#/defs/Acts" - } + }, + "class": "read" }, { "name": "packages", @@ -223,7 +229,8 @@ "node", "source" ] - } + }, + "class": "read" }, { "name": "composition", @@ -497,7 +504,8 @@ "composition", "judged" ] - } + }, + "class": "read" }, { "name": "compose", @@ -560,7 +568,8 @@ "required": [ "pass" ] - } + }, + "class": "act" }, { "name": "compose-candidate", @@ -639,7 +648,8 @@ "own", "took" ] - } + }, + "class": "read" }, { "name": "manifest-reads", @@ -679,7 +689,8 @@ "stated-at" ], "description": "what this machine's engine reads of a manifest (ADR 0618 §3)" - } + }, + "class": "read" }, { "name": "seat-list", From 9068aac406be6bed81f3d8825f8775201ea23115 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 11:33:06 +0100 Subject: [PATCH 18/62] C14 (regenerate): mesh-conditions' finding body types, no hand-kept tsconfig.json, the watchdogs client's artifact MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Regenerated by seatgen at mesh-catalog b5aebbbe (bodies types, design 47 G section 452, 454); the eight hand-kept tsconfig.json files are deleted (the generator writes none, section 341); health-and-repair/module.json names the artifact go-meshwatchdogsclient its client check asks for. Builds: design 47 G §439, §452, §454, §341 --- .../go/seats/meshconditions/contract.go | 76 ++++++++++++++++++- health-and-repair/module.json | 8 ++ .../ts/seats/meshconditions/index.d.ts | 66 +++++++++++++++- .../ts/seats/meshconditions/tsconfig.json | 12 --- .../ts/seats/meshhandacts/tsconfig.json | 12 --- .../ts/seats/meshhealers/tsconfig.json | 12 --- .../ts/seats/meshselfcheck/tsconfig.json | 12 --- .../ts/seats/meshwatchdogs/tsconfig.json | 12 --- .../ts/seats/meshnodeenroller/tsconfig.json | 12 --- .../ts/seats/meshvault/tsconfig.json | 12 --- .../ts/seats/operatorchannel/tsconfig.json | 12 --- .../ts/seats/meshprovisioner/tsconfig.json | 12 --- ts/seats/meshbroker/tsconfig.json | 12 --- ts/seats/meshconfig/tsconfig.json | 12 --- ts/seats/meshmoduleassigner/tsconfig.json | 12 --- ts/seats/nodeengine/tsconfig.json | 12 --- 16 files changed, 147 insertions(+), 159 deletions(-) delete mode 100644 health-and-repair/ts/seats/meshconditions/tsconfig.json delete mode 100644 health-and-repair/ts/seats/meshhandacts/tsconfig.json delete mode 100644 health-and-repair/ts/seats/meshhealers/tsconfig.json delete mode 100644 health-and-repair/ts/seats/meshselfcheck/tsconfig.json delete mode 100644 health-and-repair/ts/seats/meshwatchdogs/tsconfig.json delete mode 100644 identity-and-access/ts/seats/meshnodeenroller/tsconfig.json delete mode 100644 identity-and-access/ts/seats/meshvault/tsconfig.json delete mode 100644 operator-and-conversation/ts/seats/operatorchannel/tsconfig.json delete mode 100644 provisioning/ts/seats/meshprovisioner/tsconfig.json delete mode 100644 ts/seats/meshbroker/tsconfig.json delete mode 100644 ts/seats/meshconfig/tsconfig.json delete mode 100644 ts/seats/meshmoduleassigner/tsconfig.json delete mode 100644 ts/seats/nodeengine/tsconfig.json diff --git a/health-and-repair/go/seats/meshconditions/contract.go b/health-and-repair/go/seats/meshconditions/contract.go index 7406782..73984b6 100644 --- a/health-and-repair/go/seats/meshconditions/contract.go +++ b/health-and-repair/go/seats/meshconditions/contract.go @@ -276,6 +276,78 @@ type Subject struct { Scope string `json:"scope"` } +// Finding is one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439). +type Finding struct { + Actions []Action `json:"actions,omitempty"` + At time.Time `json:"at"` + // newest first, at most 10 + Evidence []Evidence `json:"evidence,omitempty"` + Explanation string `json:"explanation,omitempty"` + Headline string `json:"headline,omitempty"` + // the key's second part + ID string `json:"id"` + Kind string `json:"kind"` + Needs string `json:"needs,omitempty"` + // the module that wrote it + Observer string `json:"observer"` + // the module the finding is about, when not the observer + Owner string `json:"owner,omitempty"` + // the key's last part when it is not the kind + Ref string `json:"ref,omitempty"` + // self, operator, agent or healer: + Resolver string `json:"resolver,omitempty"` + // what of its own saw it last + Run string `json:"run,omitempty"` + // the key's first part: .. (ADR 0564) + Scope string `json:"scope"` + Severity string `json:"severity"` + // since when the finding stands + Since time.Time `json:"since"` + // the row, probe or event that saw it + Source string `json:"source"` + Subject Subject `json:"subject"` + // one line + Summary string `json:"summary"` + // what it waits on: a person, a part or a call + WaitingOn string `json:"waiting-on,omitempty"` +} + +// The values of Finding's severity. +const ( + FindingSeverityUrgent = "urgent" + FindingSeverityWarning = "warning" +) + +// FindingCleared is an observer no longer observes a finding. +type FindingCleared struct { + At time.Time `json:"at"` + ID string `json:"id"` + Kind string `json:"kind"` + Scope string `json:"scope"` + Why string `json:"why"` +} + +// FindingWritten is a type of the contract. +type FindingWritten = Finding + +// FindingsStatedPendingItem is a type of the contract. +type FindingsStatedPendingItem struct { + // a duration such as 5m + Bound string `json:"bound"` + Key string `json:"key"` + Since time.Time `json:"since"` +} + +// FindingsStated is every finding an observer observes now, at its start and when asked (design 47 G 384, 439). +type FindingsStated struct { + // the ask it answers; none at a start + Asked string `json:"asked,omitempty"` + At time.Time `json:"at"` + Findings []Finding `json:"findings"` + // the keys the observer cannot judge yet since its start, with their since and bound + Pending []FindingsStatedPendingItem `json:"pending"` +} + // ConditionsInput is what conditions takes. type ConditionsInput struct { // with history: how many days back (default 7, at most 90) @@ -448,8 +520,8 @@ const ( // FindingsViewsByObserverNodeValueStated is the last findings-stated set. type FindingsViewsByObserverNodeValueStated struct { - At *time.Time `json:"at,omitempty"` - Findings []map[string]any `json:"findings,omitempty"` + At *time.Time `json:"at,omitempty"` + Findings []Finding `json:"findings,omitempty"` } // FindingsViewsByObserverNodeValue is one value of the state findings-views under the key .. diff --git a/health-and-repair/module.json b/health-and-repair/module.json index db73ae1..9dc4693 100644 --- a/health-and-repair/module.json +++ b/health-and-repair/module.json @@ -56,6 +56,14 @@ "go/clients/meshhandactsclient" ] }, + { + "name": "go-meshwatchdogsclient", + "kind": "package", + "language": "go", + "paths": [ + "go/clients/meshwatchdogsclient" + ] + }, { "name": "go-meshconditionsclient", "kind": "package", diff --git a/health-and-repair/ts/seats/meshconditions/index.d.ts b/health-and-repair/ts/seats/meshconditions/index.d.ts index 1366690..3cebb90 100644 --- a/health-and-repair/ts/seats/meshconditions/index.d.ts +++ b/health-and-repair/ts/seats/meshconditions/index.d.ts @@ -140,6 +140,70 @@ export interface Subject { "scope": string; } +/** one finding as an observer says it: the layout whole, plus scope, id and since (design 47 G 437, 439) */ +export interface Finding { + "actions"?: Action[]; + "at": string; + /** newest first, at most 10 */ + "evidence"?: Evidence[]; + "explanation"?: string; + "headline"?: string; + /** the key's second part */ + "id": string; + "kind": string; + "needs"?: string; + /** the module that wrote it */ + "observer": string; + /** the module the finding is about, when not the observer */ + "owner"?: string; + /** the key's last part when it is not the kind */ + "ref"?: string; + /** self, operator, agent or healer: */ + "resolver"?: string; + /** what of its own saw it last */ + "run"?: string; + /** the key's first part: .. (ADR 0564) */ + "scope": string; + "severity": "urgent" | "warning"; + /** since when the finding stands */ + "since": string; + /** the row, probe or event that saw it */ + "source": string; + "subject": Subject; + /** one line */ + "summary": string; + /** what it waits on: a person, a part or a call */ + "waiting-on"?: string; +} + +/** an observer no longer observes a finding */ +export interface FindingCleared { + "at": string; + "id": string; + "kind": string; + "scope": string; + "why": string; +} + +export type FindingWritten = Finding; + +export interface FindingsStatedPendingItem { + /** a duration such as 5m */ + "bound": string; + "key": string; + "since": string; +} + +/** every finding an observer observes now, at its start and when asked (design 47 G 384, 439) */ +export interface FindingsStated { + /** the ask it answers; none at a start */ + "asked"?: string; + "at": string; + "findings": Finding[]; + /** the keys the observer cannot judge yet since its start, with their since and bound */ + "pending": FindingsStatedPendingItem[]; +} + /** is what conditions takes. */ export interface ConditionsInput { /** with history: how many days back (default 7, at most 90) */ @@ -292,7 +356,7 @@ export interface FindingsByKeyValue { /** the last findings-stated set */ export interface FindingsViewsByObserverNodeValueStated { "at"?: string; - "findings"?: Record[]; + "findings"?: Finding[]; } /** is one value of the state findings-views under the key .. */ diff --git a/health-and-repair/ts/seats/meshconditions/tsconfig.json b/health-and-repair/ts/seats/meshconditions/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/health-and-repair/ts/seats/meshconditions/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/health-and-repair/ts/seats/meshhandacts/tsconfig.json b/health-and-repair/ts/seats/meshhandacts/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/health-and-repair/ts/seats/meshhandacts/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/health-and-repair/ts/seats/meshhealers/tsconfig.json b/health-and-repair/ts/seats/meshhealers/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/health-and-repair/ts/seats/meshhealers/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/health-and-repair/ts/seats/meshselfcheck/tsconfig.json b/health-and-repair/ts/seats/meshselfcheck/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/health-and-repair/ts/seats/meshselfcheck/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/health-and-repair/ts/seats/meshwatchdogs/tsconfig.json b/health-and-repair/ts/seats/meshwatchdogs/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/health-and-repair/ts/seats/meshwatchdogs/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/identity-and-access/ts/seats/meshnodeenroller/tsconfig.json b/identity-and-access/ts/seats/meshnodeenroller/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/identity-and-access/ts/seats/meshnodeenroller/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/identity-and-access/ts/seats/meshvault/tsconfig.json b/identity-and-access/ts/seats/meshvault/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/identity-and-access/ts/seats/meshvault/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/operator-and-conversation/ts/seats/operatorchannel/tsconfig.json b/operator-and-conversation/ts/seats/operatorchannel/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/operator-and-conversation/ts/seats/operatorchannel/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/provisioning/ts/seats/meshprovisioner/tsconfig.json b/provisioning/ts/seats/meshprovisioner/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/provisioning/ts/seats/meshprovisioner/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/ts/seats/meshbroker/tsconfig.json b/ts/seats/meshbroker/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/ts/seats/meshbroker/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/ts/seats/meshconfig/tsconfig.json b/ts/seats/meshconfig/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/ts/seats/meshconfig/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/ts/seats/meshmoduleassigner/tsconfig.json b/ts/seats/meshmoduleassigner/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/ts/seats/meshmoduleassigner/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} diff --git a/ts/seats/nodeengine/tsconfig.json b/ts/seats/nodeengine/tsconfig.json deleted file mode 100644 index 60274c6..0000000 --- a/ts/seats/nodeengine/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "compilerOptions": { - "target": "ES2022", - "module": "NodeNext", - "moduleResolution": "NodeNext", - "noEmit": true, - "strict": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["src/**/*.ts"] -} From 2f680c661e01ca01407b98cfe525a6b7e542263f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 14:40:11 +0100 Subject: [PATCH 19/62] Take out C7: node-backup's aside, discard-aside, ended and restored, and the kept, form and fingerprint arguments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit G section 555: the seat node-backup gains nothing for kept data on the bus; its now and restore keep the class act (§405). Builds: design 47 G §555, §405 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-backup/fixtures/events.json | 29 ---- seats/node-backup/seat.json | 213 +------------------------ 2 files changed, 3 insertions(+), 239 deletions(-) delete mode 100644 seats/node-backup/fixtures/events.json diff --git a/seats/node-backup/fixtures/events.json b/seats/node-backup/fixtures/events.json deleted file mode 100644 index 9a5e58f..0000000 --- a/seats/node-backup/fixtures/events.json +++ /dev/null @@ -1,29 +0,0 @@ -[ - { - "name": "ended is said, its node, module and kept data in its subject", - "of": "event:ended", - "subject": "mesh.seat.node-backup.event.ended.ace.plex.library", - "given": { - "v": 1, - "module": "plex", - "kept": "library", - "form": 2, - "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "outcome": "done" - } - }, - { - "name": "restored failed says why", - "of": "event:restored", - "subject": "mesh.seat.node-backup.event.restored.ace.plex.library", - "given": { - "v": 1, - "module": "plex", - "kept": "library", - "form": 2, - "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "outcome": "failed", - "error": "restore point missing" - } - } -] diff --git a/seats/node-backup/seat.json b/seats/node-backup/seat.json index 66653b7..e9a8efe 100644 --- a/seats/node-backup/seat.json +++ b/seats/node-backup/seat.json @@ -8,7 +8,7 @@ "verbs": [ { "name": "backed-up", - "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size. Also each module's restore points of its kept data on the bus (the kept data, the form, the fingerprint each was taken before) and the data set aside at each restore, with its size.", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", "replaces": [ "restic snapshots" ], @@ -24,7 +24,7 @@ }, { "name": "now", - "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. With kept, a restore point of one kept data on the bus instead, said by the event ended.", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", "replaces": [ "restic backup" ], @@ -33,33 +33,6 @@ "module": { "description": "one module (optional)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - }, - "catch-up": { - "type": "object", - "description": "with kept: the catch-up tool the newer manifest declares beside it and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] } }, "type": "object" @@ -68,7 +41,7 @@ }, { "name": "restore", - "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named. With kept, the restore point of one kept data on the bus by its module, kept data and form, the live data set aside and never removed, said by the event restored.", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named.", "replaces": [ "restic restore" ], @@ -85,18 +58,6 @@ "snapshot": { "description": "the restore point (from `backed-up`; the newest when omitted)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" } }, "required": [ @@ -105,76 +66,6 @@ "type": "object" }, "class": "act" - }, - { - "name": "aside", - "description": "Set one module's live kept data on the bus aside under a name of its own and restore nothing, after the node agent stopped the newer build (design 47 G 297, 405); the data set aside is listed by backed-up and removed only by discard-aside.", - "class": "act", - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ] - }, - "answer": { - "type": "object", - "properties": { - "aside": { - "type": "string", - "description": "the name the live data is set aside under" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - } - } - }, - { - "name": "discard-aside", - "description": "Remove data a restore set aside, on a person's call alone; writes the act, who and why in the hand-act log of the seat mesh-hand-acts.", - "callers": [ - "operator" - ], - "input": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "the aside's id, as backed-up lists it" - }, - "why": { - "type": "string", - "description": "why" - } - }, - "required": [ - "id", - "why" - ] - }, - "class": "act" } ], "receives": [ @@ -188,103 +79,5 @@ "comment": "#", "dirs": true } - ], - "events": [ - { - "name": "ended", - "subject": "ended...", - "body": { - "type": "object", - "description": "a restore point of a kept data on the bus taken, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - }, - { - "name": "restored", - "subject": "restored...", - "body": { - "type": "object", - "description": "a kept data on the bus restored from its restore point beside the live data, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - } ] } From 37a906ed4e09b71ab484cf2d693da8bc3715064b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:47:44 +0100 Subject: [PATCH 20/62] K1 (format): an accepted kind names its stream, and a verb naming no class is a read MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The format's accepted kind gains stream (check or delivery), so the build seats' step on both streams and run on check validate against it; the class description says a verb that names no class takes read, on main or added in G, and that nothing refuses it. Builds: design 47 G §455, §456 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- format/seat-definition.schema.json | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index 1b0888b..7ca51ea 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -354,7 +354,7 @@ "act", "warrant" ], - "description": "read: invokers, persons and sessions; act: operator and sessions; warrant: operator alone, with needs-approval (design 47 G 391). A verb without it on main is a read; a verb added in design 47 G names it" + "description": "read: invokers, persons and sessions; act: operator and sessions; warrant: operator alone, with needs-approval (design 47 G 391). A verb that names no class is a read, whether it is on main or design 47 G adds it, and nothing refuses a verb for naming none (design 47 G 456)" }, "needs-approval": { "type": "boolean", @@ -373,6 +373,13 @@ "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }, + "stream": { + "enum": [ + "check", + "delivery" + ], + "description": "the stream an accepted kind rides: its subject is ., and one kind name may ride both streams, as the build seats accept step on check and on delivery (design 47 G 455)" + }, "body": { "type": "object", "description": "a JSON Schema" From 3ccc3cc3cb32c6e03ce6b2501d4dfef5602d43f7 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:50:06 +0100 Subject: [PATCH 21/62] K2 (node-engine verbs): the seat is claimed as one module, and its first views are seat verbs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The definition drops held-by-the-engine, so one module's claim of the seat is read as any other. It gains first-views (read; any person and the healers) and first-view-again (act; the operator and the healers), not optional, their inputs and answers those of the view's two tools mesh-sdk's runtime serves; a fixture reads first-view-again's input. Generated code waits for K21. Builds: design 47 G §508, §422, §204, §400 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/fixtures/verbs.json | 9 +++ seats/node-engine/seat.json | 112 +++++++++++++++++++++++++- 2 files changed, 120 insertions(+), 1 deletion(-) diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index 8c72985..a1488ee 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -156,5 +156,14 @@ "processes": [], "error": "the service manager did not answer" } + }, + { + "name": "first-view-again names the owner, its state and why", + "of": "verb:first-view-again.input", + "given": { + "owner": "mesh-delivery-indexer", + "state": "manifests", + "why": "the picture lags the indexer by hand" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index af5875e..ab45d89 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -6,7 +6,6 @@ "domain": "Core", "decision": "novox/hq ADR 0563", "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", - "held-by-the-engine": true, "acts": [ { "step": "compose", @@ -724,6 +723,117 @@ "$ref": "#/defs/SeatList" } }, + { + "name": "first-views", + "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", + "class": "read", + "callers": [ + "persons", + "healers" + ], + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "first-views" + ], + "properties": { + "first-views": { + "type": "array", + "items": { + "type": "object" + }, + "description": "one status per owner and state followed, as mesh-sdk's views runtime keeps it" + } + } + } + }, + { + "name": "first-view-again", + "description": "Ask the node-engine's first view of an owner's state again now, by hand (design 47 G 422, 204): a hand act, its caller and why kept in the status first-views reads; served by mesh-sdk's runtime as the view's again tool.", + "class": "act", + "callers": [ + "operator", + "healers" + ], + "input": { + "type": "object", + "required": [ + "owner", + "state", + "why" + ], + "properties": { + "owner": { + "type": "string", + "description": "the owner module, as first-views names it" + }, + "state": { + "type": "string", + "description": "the owner's state, as first-views names it" + }, + "why": { + "type": "string", + "description": "why it is asked again, in plain words" + } + } + }, + "answer": { + "type": "object", + "required": [ + "asked", + "read" + ], + "properties": { + "asked": { + "type": "object", + "description": "the hand ask written", + "required": [ + "v", + "owner", + "state", + "why", + "by", + "at" + ], + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "owner": { + "type": "string", + "description": "the owner module" + }, + "state": { + "type": "string", + "description": "the owner's state" + }, + "why": { + "type": "string", + "description": "why it was asked again" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was asked, RFC 3339" + } + } + }, + "read": { + "type": "string", + "description": "the verb that reads the status, first-views" + } + } + } + }, { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", From 5e8dce621ba19f8a8bba52aa03627afe0a08cac7 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:51:53 +0100 Subject: [PATCH 22/62] K3 (running healthy): running says the health of the build that runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The node-engine seat's Running gains healthy, a nullable boolean so that a false survives the wire and a running said by a node-engine of before G, with none, is told apart and reads as healthy; stopped is said only when the have no longer holds the module. Two fixtures read healthy true and false; the one without it still decodes. Generated code waits for K21. Builds: design 47 G §520 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/fixtures/events.json | 28 ++++++++++++++++++++++++++ seats/node-engine/seat.json | 13 +++++++++--- 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index 657566e..56731bd 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -92,6 +92,34 @@ "at": "2026-11-09T20:01:00Z" } }, + { + "name": "running says the build that runs is healthy", + "of": "event:running", + "subject": "mesh.seat.node-engine.event.running.ace.nats", + "given": { + "v": 1, + "node": "ace", + "module": "nats", + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", + "healthy": true, + "at": "2026-11-11T09:00:00Z" + } + }, + { + "name": "running says the build that runs turned unhealthy, still running", + "of": "event:running", + "subject": "mesh.seat.node-engine.event.running.ace.nats", + "given": { + "v": 1, + "node": "ace", + "module": "nats", + "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", + "healthy": false, + "at": "2026-11-11T09:05:00Z" + } + }, { "name": "running says a module stopped on the node, with no fingerprint", "of": "event:running", diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index ab45d89..89352fa 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -2883,7 +2883,7 @@ }, "Running": { "type": "object", - "description": "a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit", + "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "properties": { "v": { "type": "integer", @@ -2905,14 +2905,21 @@ "type": "string", "description": "the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half" }, + "healthy": { + "type": [ + "boolean", + "null" + ], + "description": "the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat" + }, "at": { "type": "string", - "description": "when it was seen running healthy, RFC 3339", + "description": "when it was said, RFC 3339", "format": "date-time" }, "stopped": { "type": "boolean", - "description": "true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there" + "description": "true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there" } }, "required": [ From 24d58f07869530e3e690b9a52483d11f28e5fd91 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:54:17 +0100 Subject: [PATCH 23/62] K10 (backup items): node-backup says when each item starts and ends MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seat gains item-started and item-ended on ..., kept last per subject for 7 days, each with at, and item-ended with outcome (done, failed or put-off), the restore's act it gave way to and an error, so the recovery module and the backup holder each read the other's start and never overlap. The seat is of the seat-list grain: nothing is generated and its fixtures are not read, so mesh-sdk's definition reader and its bootstrapped copy of this file are what read it. Builds: design 47 G §554, §555, §563, §523 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-backup/seat.json | 64 +++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/seats/node-backup/seat.json b/seats/node-backup/seat.json index e9a8efe..a2b0ece 100644 --- a/seats/node-backup/seat.json +++ b/seats/node-backup/seat.json @@ -68,6 +68,70 @@ "class": "act" } ], + "events": [ + { + "name": "item-started", + "subject": "item-started...", + "keep": { + "max-age-days": 7, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "the holder started backing up one item of a module on its node, said before it reads the recovery module's restore-started and restored (design 47 G 554, 563)", + "required": [ + "at" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time", + "description": "when the item started, RFC 3339" + } + } + } + }, + { + "name": "item-ended", + "subject": "item-ended...", + "keep": { + "max-age-days": 7, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "the holder ended one item: done, failed (error stopped for an item it said started and never ended, at its start) or put-off while a restore of the recovery module runs, the item started again when that restore's restored is heard (design 47 G 554, 563)", + "required": [ + "at", + "outcome" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time", + "description": "when the item ended, RFC 3339" + }, + "outcome": { + "type": "string", + "enum": [ + "done", + "failed", + "put-off" + ], + "description": "how the item ended; a put-off item is that night's backup once it runs, neither failed nor missed" + }, + "restore": { + "type": "string", + "description": "with put-off, the act of the recovery module's restore the item gave way to" + }, + "error": { + "type": "string", + "description": "with failed, why, in words; stopped for an item ended at the holder's start" + } + } + } + } + ], "receives": [ { "kind": "backup", From b3526b762c640ce5ba7c7aa9cdf90208be079506 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:55:58 +0100 Subject: [PATCH 24/62] K13 (stated kinds): a findings statement names the kinds it states MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FindingsStated gains kinds, the finding kinds the stating bundle owns; a statement deletes only keys of those kinds and one with none covers every kind, as before. A body of bodies yields its type alone, so no fixture reads it here: mesh-sdk's writer is what reads and tests it. Generated code waits for K21. Builds: design 47 G §580 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- health-and-repair/seats/mesh-conditions/seat.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index e5fa435..0591b4a 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -904,6 +904,13 @@ "type": "string", "description": "the ask it answers; none at a start" }, + "kinds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)" + }, "findings": { "type": "array", "items": { From a090a447d3c8655c7d04661d8e592ba26f0a086f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 15:56:39 +0100 Subject: [PATCH 25/62] K16 (notify every channel): notify may ask a message sent on every channel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit operator-channel's notify takes every-channel, which the router sends on every channel's send, as a break-glass act is announced; the teller tells widens, recovery-merged and forge-made through it. A fixture reads the input. Generated code waits for K21. Builds: design 47 G §514 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../seats/operator-channel/fixtures/verbs.json | 13 +++++++++++++ .../seats/operator-channel/seat.json | 4 ++++ 2 files changed, 17 insertions(+) create mode 100644 operator-and-conversation/seats/operator-channel/fixtures/verbs.json diff --git a/operator-and-conversation/seats/operator-channel/fixtures/verbs.json b/operator-and-conversation/seats/operator-channel/fixtures/verbs.json new file mode 100644 index 0000000..2bad6cc --- /dev/null +++ b/operator-and-conversation/seats/operator-channel/fixtures/verbs.json @@ -0,0 +1,13 @@ +[ + { + "name": "notify asks the message sent on every channel", + "of": "verb:notify.input", + "given": { + "key": "widens.mesh-delivery", + "severity": "warning", + "summary": "a change widens what a module may do", + "subject": "mesh-delivery", + "every-channel": true + } + } +] diff --git a/operator-and-conversation/seats/operator-channel/seat.json b/operator-and-conversation/seats/operator-channel/seat.json index 7a11f0f..4ecbb69 100644 --- a/operator-and-conversation/seats/operator-channel/seat.json +++ b/operator-and-conversation/seats/operator-channel/seat.json @@ -78,6 +78,10 @@ "clear": { "type": "boolean", "description": "it is over" + }, + "every-channel": { + "type": "boolean", + "description": "send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514)" } } }, From f4d0d58619798f63d19dfebaf8cf51f07c9f1e65 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:24:46 +0100 Subject: [PATCH 26/62] K14 (owner forms): a finding's owner and waiting-on are one of three forms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit owner and waiting-on carry the pattern of the three forms (session who@node, a seat's name, forge:) in the layout and the state value, and the fixtures read two forms. mesh-sdk's writer is what refuses another. Generated code waits for K21. Builds: design 47 G §678, §540, §451 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../mesh-conditions/fixtures/states.json | 42 +++++++++++++++++++ .../seats/mesh-conditions/seat.json | 12 ++++-- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index 0cac1dd..f8b2682 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -113,5 +113,47 @@ ], "at": "2026-10-26T20:19:41.474823121Z" } + }, + { + "name": "a finding owned by a session and waiting on a seat (design 47 G 678)", + "of": "state:findings/", + "given": { + "v": 1, + "key": "module.mesh-host.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "subject": { + "scope": "module", + "id": "mesh-host.ace", + "machine": "ace" + }, + "severity": "warning", + "summary": "a directory waits for a hand", + "source": "health-report", + "observer": "mesh-delivery-watchman", + "at": "2026-11-11T10:00:00Z", + "owner": "jochen@shanks", + "waiting-on": "node-engine" + } + }, + { + "name": "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", + "of": "state:findings/", + "given": { + "v": 1, + "key": "module.mesh-host.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "subject": { + "scope": "module", + "id": "mesh-host.ace", + "machine": "ace" + }, + "severity": "warning", + "summary": "a directory waits for a hand", + "source": "health-report", + "observer": "mesh-delivery-watchman", + "at": "2026-11-11T10:00:00Z", + "owner": "node-engine", + "waiting-on": "forge:jochen" + } } ] diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index 0591b4a..e4fc40a 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -411,11 +411,13 @@ }, "owner": { "type": "string", - "description": "the module the finding is about, when not the observer" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "waiting-on": { "type": "string", - "description": "what it waits on: a person, a part or a call" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" } }, "required": [ @@ -819,11 +821,13 @@ }, "owner": { "type": "string", - "description": "the module the finding is about, when not the observer" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "waiting-on": { "type": "string", - "description": "what it waits on: a person, a part or a call" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "actions": { "type": "array", From c65628de23bb3e50ab1ce5097768c80b61a652c9 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:25:41 +0100 Subject: [PATCH 27/62] K1b (format): a verb may say by-caller MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §554, §621, §656 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- format/seat-definition.schema.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index 7ca51ea..dfba914 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -359,6 +359,10 @@ "needs-approval": { "type": "boolean", "description": "the verb runs only on the operator's Approve of the call, for every holder (design 46 milestone 7, 2)" + }, + "by-caller": { + "type": "boolean", + "description": "the holder's process answers the verb itself and tells callers apart by the account the bus proved (ADR 0259 3; design 47 G 554, 621, 656)" } } }, From 7d730a4a756a8b81b7c0bb5be5cc4991151cd18c Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:26:26 +0100 Subject: [PATCH 28/62] K6 (one capabilities event): the node-engine seat says manifest-reads-changed alone MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit capabilities-changed and its body go, the one event of a node's stated capabilities is manifest-reads-changed, which already carries why. Generated code waits for K21. Builds: design 47 G §590 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/fixtures/events.json | 14 --------- seats/node-engine/seat.json | 39 -------------------------- 2 files changed, 53 deletions(-) diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index 56731bd..66f0f87 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -131,19 +131,5 @@ "stopped": true, "at": "2026-11-11T09:00:00Z" } - }, - { - "name": "capabilities-changed is said", - "of": "event:capabilities-changed", - "subject": "mesh.seat.node-engine.event.capabilities-changed.ace", - "given": { - "v": 1, - "node": "ace", - "capabilities": [ - "build-go", - "docker" - ], - "at": "2026-11-09T20:02:00Z" - } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 89352fa..ff03a96 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -904,13 +904,6 @@ "body": { "$ref": "#/defs/Running" } - }, - { - "name": "capabilities-changed", - "subject": "capabilities-changed.", - "body": { - "$ref": "#/defs/CapabilitiesChanged" - } } ], "family": { @@ -2929,38 +2922,6 @@ "at" ] }, - "CapabilitiesChanged": { - "type": "object", - "description": "a node's capabilities changed, which the assigner places by", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "node": { - "type": "string", - "description": "the node" - }, - "capabilities": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its capabilities now" - }, - "at": { - "type": "string", - "description": "when, RFC 3339", - "format": "date-time" - } - }, - "required": [ - "v", - "node", - "capabilities", - "at" - ] - }, "ProcessBuild": { "type": "object", "description": "the build one process of a module was started with", From a5cf2c5df13ce44f2fa7544fa3677587a793d856 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:26:36 +0100 Subject: [PATCH 29/62] K4, K5 (node-engine waits): the seat says wait-held and wait-ended, and the have carries its wait MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit defs.Wait has the fields of a wait (owner, step compose or kept-build, node, on, bound, since, clock-from, words, reason) and, in the have, ask-at and act; wait-held.. and wait-ended.. are kept last per subject on the stream running is kept on; the have's value gains wait, waits stays. Generated code waits for K21. Builds: design 47 G §498, §499, §541, §556, §560, §629 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/node-engine/fixtures/events.json | 27 ++++++++ seats/node-engine/fixtures/states.json | 23 +++++++ seats/node-engine/seat.json | 85 ++++++++++++++++++++++++++ 3 files changed, 135 insertions(+) diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index 66f0f87..bf8142c 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -131,5 +131,32 @@ "stopped": true, "at": "2026-11-11T09:00:00Z" } + }, + { + "name": "a kept build's wait is held", + "of": "event:wait-held", + "subject": "mesh.seat.node-engine.event.wait-held.ace.postgres", + "given": { + "owner": "node-engine", + "step": "kept-build", + "node": "ace", + "on": "the kept build of postgres", + "bound": "60m", + "since": "2026-11-11T10:00:00Z", + "clock-from": "2026-11-11T10:00:00Z", + "words": "waiting for the kept build of postgres on ace", + "reason": "node away" + } + }, + { + "name": "a hold of the composition ends", + "of": "event:wait-ended", + "subject": "mesh.seat.node-engine.event.wait-ended.ace.postgres", + "given": { + "owner": "node-engine", + "step": "compose", + "since": "2026-11-11T10:00:00Z", + "reason": "restore point missing" + } } ] diff --git a/seats/node-engine/fixtures/states.json b/seats/node-engine/fixtures/states.json index 35631e7..aa0ae83 100644 --- a/seats/node-engine/fixtures/states.json +++ b/seats/node-engine/fixtures/states.json @@ -515,5 +515,28 @@ "contract": 3, "at": "2026-11-05T12:00:00Z" } + }, + { + "name": "a have that waits for the recovery module, with its wait, ask-at and act (design 47 G 560, 629)", + "of": "state:have/.", + "given": { + "v": 1, + "fp": "0123456789ab", + "phase": "held", + "detail": "waiting for a restore point", + "wait": { + "owner": "node-engine", + "step": "compose", + "on": "the recovery module's ended", + "bound": "90m", + "since": "2026-11-11T10:00:00Z", + "clock-from": "2026-11-11T10:00:00Z", + "words": "waiting for the point of postgres's data", + "reason": "recovery wait", + "ask-at": "2026-11-11T10:00:00Z", + "act": "a-20261111t100000" + }, + "health": "waits" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index ff03a96..3156047 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -904,6 +904,28 @@ "body": { "$ref": "#/defs/Running" } + }, + { + "name": "wait-held", + "subject": "wait-held..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "subject": "wait-ended..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Wait" + } } ], "family": { @@ -1008,6 +1030,9 @@ }, "handed": { "$ref": "#/defs/AccountsHanded" + }, + "wait": { + "$ref": "#/defs/Wait" } }, "required": [ @@ -2986,6 +3011,66 @@ "node", "processes" ] + }, + "Wait": { + "type": "object", + "description": "a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560)", + "properties": { + "owner": { + "type": "string", + "description": "the seat holding the wait: node-engine" + }, + "step": { + "type": "string", + "enum": [ + "compose", + "kept-build" + ], + "description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)" + }, + "node": { + "type": "string", + "description": "the node waited on: the build node for a kept build; the subject's is the node that says it" + }, + "on": { + "type": "string", + "description": "what it waits on" + }, + "bound": { + "type": "string", + "description": "a duration such as 30m" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "the time the bound counts from (design 47 G 266, 269, 498)" + }, + "words": { + "type": "string", + "description": "the wait said in words" + }, + "reason": { + "type": "string", + "description": "why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499)" + }, + "ask-at": { + "type": "string", + "format": "date-time", + "description": "in the have: the time of the first ask of the recovery module for this wait (design 47 G 560)" + }, + "act": { + "type": "string", + "description": "in the have: the act the recovery module answered accepted with (design 47 G 560)" + } + }, + "required": [ + "step", + "since" + ] } } } From 22911c3644035a500e086a840d30c5ef60e50e48 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:26:53 +0100 Subject: [PATCH 30/62] K12 (healers attempts): mesh-healers says attempt-changed, keyed by condition and attempt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit attempt-changed.., kept last per subject, 7 days and 16 MiB, its body the attempt's value whole with until, or removed. Generated code waits for K21. Builds: design 47 G §541, §665 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../seats/mesh-healers/fixtures/events.json | 26 ++++++++ .../seats/mesh-healers/seat.json | 60 +++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 health-and-repair/seats/mesh-healers/fixtures/events.json diff --git a/health-and-repair/seats/mesh-healers/fixtures/events.json b/health-and-repair/seats/mesh-healers/fixtures/events.json new file mode 100644 index 0000000..abe6d7f --- /dev/null +++ b/health-and-repair/seats/mesh-healers/fixtures/events.json @@ -0,0 +1,26 @@ +[ + { + "name": "an attempt begun, said with its end (design 47 G 665)", + "of": "event:attempt-changed", + "subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", + "given": { + "healer": "directory", + "condition": "module.mesh-host.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "budget-key": "module.mesh-host.ace.directory-used-as-found", + "act": "hand-over", + "outcome": "acting", + "begun": "2026-11-11T10:00:00Z", + "until": "2026-11-11T12:00:00Z" + } + }, + { + "name": "an attempt ended by its healer", + "of": "event:attempt-changed", + "subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", + "given": { + "condition": "module.mesh-host.ace.directory-used-as-found", + "removed": true + } + } +] diff --git a/health-and-repair/seats/mesh-healers/seat.json b/health-and-repair/seats/mesh-healers/seat.json index 23772b0..38b0bb4 100644 --- a/health-and-repair/seats/mesh-healers/seat.json +++ b/health-and-repair/seats/mesh-healers/seat.json @@ -135,6 +135,66 @@ "outcome" ] } + }, + { + "name": "attempt-changed", + "subject": "attempt-changed..", + "keep": { + "max-age-days": 7, + "max-mib": 16, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "an attempt as the attempts state holds it, whole, with until, or removed: true when the healer ends it; said again for every open attempt at the healers' start (design 47 G 541, 665)", + "properties": { + "healer": { + "type": "string" + }, + "condition": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "budget-key": { + "type": "string", + "description": "what the budget counts by: the condition's key unless the healer says another" + }, + "act": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "acting", + "acted", + "failed", + "escalated" + ] + }, + "said": { + "type": "string" + }, + "begun": { + "type": "string", + "format": "date-time" + }, + "finished": { + "type": "string", + "format": "date-time" + }, + "until": { + "type": "string", + "format": "date-time", + "description": "the end of that key's lifetime, which the keeper drops the attempt at on its own clock" + }, + "removed": { + "type": "boolean", + "description": "true when the healer ends the attempt" + } + } + } } ], "family": { From 68b0c970790b27daef66c4f61f754c95513885c4 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:27:12 +0100 Subject: [PATCH 31/62] K15 (findings state): the state findings is keyed .. and holds the Finding body MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §660, §461, §437, §439 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../mesh-conditions/fixtures/states.json | 45 ++++---- .../seats/mesh-conditions/seat.json | 104 +----------------- 2 files changed, 27 insertions(+), 122 deletions(-) diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index f8b2682..6b421c1 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -7,7 +7,7 @@ "evidence": [ { "at": "2026-10-26T20:19:41.474823121Z", - "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it \u2014 `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", @@ -27,7 +27,7 @@ "machine": "ace", "scope": "module" }, - "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it \u2014 `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } }, { @@ -61,11 +61,9 @@ } }, { - "name": "a finding of the bus scope with its zero time (captured from the watchman; empty fields left out)", - "of": "state:findings/", + "name": "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", + "of": "state:findings/..", "given": { - "v": 1, - "key": "bus.EVENTS.controller.max-deliveries", "kind": "max-deliveries", "subject": { "id": "EVENTS.controller", @@ -82,15 +80,16 @@ "said": "1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)" } ], - "at": "0001-01-01T00:00:00Z" + "at": "0001-01-01T00:00:00Z", + "scope": "bus", + "id": "EVENTS.controller", + "since": "0001-01-01T00:00:00Z" } }, { - "name": "a finding of the module scope with its machine (captured from the watchman; empty fields left out)", - "of": "state:findings/", + "name": "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", + "of": "state:findings/..", "given": { - "v": 1, - "key": "module.mesh-build-node.ace.directory-used-as-found", "kind": "directory-used-as-found", "subject": { "id": "mesh-build-node.ace", @@ -102,7 +101,6 @@ "explanation": "Needs you: hand the directory over from the control-node, as the operator.", "headline": "mesh-build-node waits for a directory on ace", "needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.", - "resolved": "mesh-build-node's directory on ace is the mesh's", "observer": "mesh-delivery-watchman", "source": "health-report", "evidence": [ @@ -111,15 +109,16 @@ "said": "mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found" } ], - "at": "2026-10-26T20:19:41.474823121Z" + "at": "2026-10-26T20:19:41.474823121Z", + "scope": "module", + "id": "mesh-build-node.ace", + "since": "2026-10-26T20:19:41.474823121Z" } }, { "name": "a finding owned by a session and waiting on a seat (design 47 G 678)", - "of": "state:findings/", + "of": "state:findings/..", "given": { - "v": 1, - "key": "module.mesh-host.ace.directory-used-as-found", "kind": "directory-used-as-found", "subject": { "scope": "module", @@ -132,15 +131,16 @@ "observer": "mesh-delivery-watchman", "at": "2026-11-11T10:00:00Z", "owner": "jochen@shanks", - "waiting-on": "node-engine" + "waiting-on": "node-engine", + "scope": "module", + "id": "mesh-host.ace", + "since": "2026-11-11T10:00:00Z" } }, { "name": "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", - "of": "state:findings/", + "of": "state:findings/..", "given": { - "v": 1, - "key": "module.mesh-host.ace.directory-used-as-found", "kind": "directory-used-as-found", "subject": { "scope": "module", @@ -153,7 +153,10 @@ "observer": "mesh-delivery-watchman", "at": "2026-11-11T10:00:00Z", "owner": "node-engine", - "waiting-on": "forge:jochen" + "waiting-on": "forge:jochen", + "scope": "module", + "id": "mesh-host.ace", + "since": "2026-11-11T10:00:00Z" } } ] diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index e4fc40a..14be042 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -330,109 +330,11 @@ "writer": "caller", "key-forms": [ { - "key": "", + "key": "..", "value": { - "type": "object", - "description": "one thing an observer sees wrong now", - "properties": { - "v": { - "type": "integer", - "description": "layout version, 1" - }, - "key": { - "type": "string", - "description": "scope.id.token" - }, - "kind": { - "type": "string" - }, - "subject": { - "$ref": "#/defs/Subject" - }, - "severity": { - "type": "string", - "enum": [ - "urgent", - "warning" - ] - }, - "summary": { - "type": "string", - "description": "one line" - }, - "headline": { - "type": "string" - }, - "explanation": { - "type": "string" - }, - "resolved": { - "type": "string" - }, - "needs": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "$ref": "#/defs/Action" - } - }, - "evidence": { - "type": "array", - "description": "newest first, at most 10", - "items": { - "$ref": "#/defs/Evidence" - } - }, - "source": { - "type": "string", - "description": "the row, probe or event that saw it" - }, - "resolver": { - "type": "string", - "description": "self, operator, agent or healer:" - }, - "ref": { - "type": "string", - "description": "the key's last part when it is not the kind" - }, - "observer": { - "type": "string", - "description": "the module that wrote it" - }, - "run": { - "type": "string", - "description": "what of its own saw it last" - }, - "at": { - "type": "string", - "format": "date-time" - }, - "owner": { - "type": "string", - "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", - "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" - }, - "waiting-on": { - "type": "string", - "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", - "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" - } - }, - "required": [ - "v", - "key", - "kind", - "subject", - "severity", - "summary", - "source", - "observer", - "at" - ] + "$ref": "#/bodies/Finding" }, - "description": "one finding of the observer that wrote it" + "description": "one finding of the observer that wrote it, its layout the body Finding (design 47 G 439, 461, 660)" } ], "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" From 86a5dcc93af95e6bf3e9a3b7f8a4b3a4072db906 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:27:23 +0100 Subject: [PATCH 32/62] K20 (adapter goes): meshconditionsclient/findings is deleted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mesh-sdk's writer is the one place a finding is written; seatgen -check is clean for health-and-repair but for the generated code K21 writes. Builds: design 47 G §461, §503 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../meshconditionsclient/findings/findings.go | 88 ------------------- .../findings/findings_test.go | 71 --------------- 2 files changed, 159 deletions(-) delete mode 100644 health-and-repair/go/clients/meshconditionsclient/findings/findings.go delete mode 100644 health-and-repair/go/clients/meshconditionsclient/findings/findings_test.go diff --git a/health-and-repair/go/clients/meshconditionsclient/findings/findings.go b/health-and-repair/go/clients/meshconditionsclient/findings/findings.go deleted file mode 100644 index 903eb29..0000000 --- a/health-and-repair/go/clients/meshconditionsclient/findings/findings.go +++ /dev/null @@ -1,88 +0,0 @@ -// Package findings is a part's own bucket `findings` as the state the seat mesh-conditions' client writes into -// (meshconditionsclient.FindingState), so a part gives mesh-sdk's views the FindingWriter of the seat's layout without -// each writing the same adapter over its bucket (novox/hq ADR 0564 §2, ADR 0635 §4). -package findings - -import ( - "context" - "encoding/json" - "errors" - - "github.com/nats-io/nats.go/jetstream" - - "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient" - "git.novox.be/novox/mesh-sdk/go/views" -) - -// ErrUnbound says the bucket is not on the bus yet, so the finding is not written (the part says it in its log). -var ErrUnbound = errors.New("the findings state is not bound yet") - -// State is the bucket the part's state `findings` is, given when it is bound (process.AwaitedBucket.KV): nil is not bound yet. -type State struct { - Ctx context.Context - KV func() jetstream.KeyValue -} - -var _ meshconditionsclient.FindingState = State{} - -// Put writes one value under its key as JSON. -func (s State) Put(key string, value any) (uint64, error) { - kv := s.KV() - if kv == nil { - return 0, ErrUnbound - } - data, err := json.Marshal(value) - if err != nil { - return 0, err - } - return kv.Put(s.Ctx, key, data) -} - -// Delete clears one key. -func (s State) Delete(key string) error { - kv := s.KV() - if kv == nil { - return ErrUnbound - } - return kv.Delete(s.Ctx, key) -} - -// Writer is the part's views.FindingWriter over its bucket; the function is what views.ProcessReader.Findings and the -// emitter's Findings take. -func Writer(ctx context.Context, kv func() jetstream.KeyValue) views.FindingWriter { - return meshconditionsclient.FindingWriter{State: State{Ctx: ctx, KV: kv}} -} - -// Funcs is a findings state held as the two functions a part keeps over it (the assigner's findings, which also say -// its conditions): a value is put as JSON. -type Funcs struct { - PutBytes func(key string, value []byte) error - DeleteKey func(key string) error -} - -var _ meshconditionsclient.FindingState = Funcs{} - -// Put writes one value under its key as JSON; the state not bound (no function) is ErrUnbound. -func (f Funcs) Put(key string, value any) (uint64, error) { - if f.PutBytes == nil { - return 0, ErrUnbound - } - data, err := json.Marshal(value) - if err != nil { - return 0, err - } - return 0, f.PutBytes(key, data) -} - -// Delete clears one key. -func (f Funcs) Delete(key string) error { - if f.DeleteKey == nil { - return ErrUnbound - } - return f.DeleteKey(key) -} - -// WriterOver is the part's views.FindingWriter over its two functions. -func WriterOver(put func(string, []byte) error, del func(string) error) views.FindingWriter { - return meshconditionsclient.FindingWriter{State: Funcs{PutBytes: put, DeleteKey: del}} -} diff --git a/health-and-repair/go/clients/meshconditionsclient/findings/findings_test.go b/health-and-repair/go/clients/meshconditionsclient/findings/findings_test.go deleted file mode 100644 index 01052ac..0000000 --- a/health-and-repair/go/clients/meshconditionsclient/findings/findings_test.go +++ /dev/null @@ -1,71 +0,0 @@ -package findings - -import ( - "context" - "encoding/json" - "errors" - "testing" - "time" - - "github.com/nats-io/nats.go/jetstream" - - "git.novox.be/novox/mesh-sdk/go/views" -) - -// fakeKV is the two calls a findings state makes of its bucket. -type fakeKV struct { - jetstream.KeyValue - held map[string][]byte -} - -func (f *fakeKV) Put(_ context.Context, key string, value []byte) (uint64, error) { - f.held[key] = value - return uint64(len(f.held)), nil -} - -func (f *fakeKV) Delete(_ context.Context, key string, _ ...jetstream.KVDeleteOpt) error { - delete(f.held, key) - return nil -} - -// A part's finding is written in the seat mesh-conditions' layout under the key the condition keeper reads, cleared by the -// same finding, and refused while the bucket is not bound (the part says that in its log). -func TestAFindingIsWrittenInTheSeatsLayoutAndClearedAndRefusedUnbound(t *testing.T) { - kv := &fakeKV{held: map[string][]byte{}} - var bound jetstream.KeyValue - w := Writer(context.Background(), func() jetstream.KeyValue { return bound }) - f := views.Finding{Observer: "mesh-delivery-teller", Kind: views.UnansweredKind, ID: "mesh-delivery-teller.asks", Summary: "s", Headline: "h", - Explanation: "e", At: time.Date(2026, 11, 5, 15, 0, 0, 0, time.UTC)} - if err := w.Put(f); !errors.Is(err, ErrUnbound) { - t.Fatalf("an unbound bucket took the finding: %v", err) - } - bound = kv - if err := w.Put(f); err != nil { - t.Fatal(err) - } - var got struct{ Key, Kind, Observer, Source string } - for key, value := range kv.held { - if err := json.Unmarshal(value, &got); err != nil || got.Key != key || got.Kind != views.UnansweredKind || - got.Observer != f.Observer || got.Source != f.Observer+"."+f.Kind { - t.Fatalf("%s holds %s (%v)", key, value, err) - } - } - if len(kv.held) != 1 { - t.Fatalf("the bucket holds %d findings, want 1", len(kv.held)) - } - if err := w.Delete(f); err != nil || len(kv.held) != 0 { - t.Fatalf("the finding is not cleared: %v, %d left", err, len(kv.held)) - } - // The same finding over two functions (a part whose findings also say its conditions). - held := map[string][]byte{} - o := WriterOver(func(k string, v []byte) error { held[k] = v; return nil }, func(k string) error { delete(held, k); return nil }) - if err := o.Put(f); err != nil || len(held) != 1 { - t.Fatalf("over functions: %v, %d held", err, len(held)) - } - if err := o.Delete(f); err != nil || len(held) != 0 { - t.Fatalf("over functions not cleared: %v, %d left", err, len(held)) - } - if err := WriterOver(nil, nil).Put(f); !errors.Is(err, ErrUnbound) { - t.Fatalf("no functions took the finding: %v", err) - } -} From a16cf80bd62fcce6127451b18290e18141cb0b76 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:27:34 +0100 Subject: [PATCH 33/62] K19 (caps in list): mesh-broker's list answers the sum of the caps and the limits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §661, §547 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- seats/mesh-broker/fixtures/verbs.json | 22 ++++++++++++++++++++++ seats/mesh-broker/seat.json | 21 +++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/seats/mesh-broker/fixtures/verbs.json b/seats/mesh-broker/fixtures/verbs.json index fd280c7..5cf98ac 100644 --- a/seats/mesh-broker/fixtures/verbs.json +++ b/seats/mesh-broker/fixtures/verbs.json @@ -114,5 +114,27 @@ } ] } + }, + { + "name": "list answers the sum of the caps and both limits (design 47 G 661)", + "of": "verb:list.answer", + "given": { + "entries": [], + "caps": { + "sum-mib": 512, + "account-limit-mib": 1024, + "server-limit-mib": 2048 + } + } + }, + { + "name": "list answers a sum with no limit, which is unlimited", + "of": "verb:list.answer", + "given": { + "entries": [], + "caps": { + "sum-mib": 64 + } + } } ] diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index fefb7c4..69c0849 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -32,6 +32,27 @@ "$ref": "#/defs/Held" }, "description": "every entry" + }, + "caps": { + "type": "object", + "description": "the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)", + "properties": { + "sum-mib": { + "type": "integer", + "minimum": 0 + }, + "account-limit-mib": { + "type": "integer", + "minimum": 0 + }, + "server-limit-mib": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "sum-mib" + ] } }, "required": [ From 6beae382b35c235bea20683daf4591bcc6468ce5 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:27:48 +0100 Subject: [PATCH 34/62] K17 (refused said): the asks record says when an ask ended MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit decided already names ask, outcome refused, words and at; the record gains at beside state refused and answer. Generated code waits for K21. Builds: design 47 G §570, §638 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../seats/operator-channel/fixtures/states.json | 15 +++++++++++++++ .../seats/operator-channel/seat.json | 4 ++++ 2 files changed, 19 insertions(+) diff --git a/operator-and-conversation/seats/operator-channel/fixtures/states.json b/operator-and-conversation/seats/operator-channel/fixtures/states.json index 0df2cf4..36e8ba0 100644 --- a/operator-and-conversation/seats/operator-channel/fixtures/states.json +++ b/operator-and-conversation/seats/operator-channel/fixtures/states.json @@ -45,5 +45,20 @@ "opened": "2026-11-10T10:00:00Z", "state": "held-back" } + }, + { + "name": "an ask the router refused at take-in, closed (design 47 G 570)", + "of": "state:asks/.", + "given": { + "answer": "refused: its expiry passes the bound of its highest option level", + "asker": "nats", + "at": "2026-11-11T10:00:01Z", + "asker_told": true, + "expires": "2026-11-12T10:00:00Z", + "headline": "Recreate a bus entry", + "key": "nats.r-1", + "opened": "2026-11-11T10:00:00Z", + "state": "refused" + } } ] diff --git a/operator-and-conversation/seats/operator-channel/seat.json b/operator-and-conversation/seats/operator-channel/seat.json index 4ecbb69..38d9ad2 100644 --- a/operator-and-conversation/seats/operator-channel/seat.json +++ b/operator-and-conversation/seats/operator-channel/seat.json @@ -319,6 +319,10 @@ "answer": { "type": "string", "description": "how it ended, in words" + }, + "at": { + "type": "string", + "description": "when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638)" } }, "required": [ From 9cefd4722387befdf68187dc70de17196ad7f20f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:28:44 +0100 Subject: [PATCH 35/62] K18 (asker hears refused): Take answers Refused with the router's words for a refused ask MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ask is closed as any ended ask is, then the asker's request ends with why. Builds: design 47 G §570, §638 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../go/clients/operatorchannelclient/client.go | 4 ++++ .../clients/operatorchannelclient/client_test.go | 14 ++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client.go b/operator-and-conversation/go/clients/operatorchannelclient/client.go index 645e48e..4acd445 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client.go @@ -153,6 +153,10 @@ func (c *Client) Take(w seat.Warrant, act func(seat.Option, seat.Warrant) error) if _, err := c.State.Update(c.key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) { return "", err } + if w.Outcome == OutcomeRefused { + // The router never took the ask (design 47 G 570): its asker's request ends with the router's words. + return Refused, fmt.Errorf("the ask %s was refused: %s", w.Ask, w.Words) + } return Recorded, nil } o, err := For(w, c.Module, k.Ask) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 8798ea5..2007142 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -140,6 +140,20 @@ func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) { } } +func TestAnAskTheRouterRefusedEndsTheRequestWithItsWords(t *testing.T) { + c, _ := client() + _ = c.Ask(askedHeld()) + w := askedWarrant() + w.Outcome, w.Option, w.By, w.Words = OutcomeRefused, "", nil, "its expiry passes the bound of its level" + h, err := c.Take(w, func(seat.Option, seat.Warrant) error { t.Fatal("acted"); return nil }) + if h != Refused || err == nil || !strings.Contains(err.Error(), w.Words) { + t.Fatalf("%s %v, want refused with the router's words", h, err) + } + if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done { + t.Errorf("the refused ask was not closed: %s", h) + } +} + func TestAKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere(t *testing.T) { for _, tc := range []struct{ prefix, key string }{{"n1.", "n1.ask.d-1"}, {"", "ask.d-1"}} { c, _ := client() From 9243f8c44f7852a63faf50967d90eba4067e9ee8 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:30:35 +0100 Subject: [PATCH 36/62] K7, K8, K9 (the seat mesh-recovery): its verbs, its events and its place in the module MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seat is defined whole in scope mesh: snapshot-kept, restore-kept, kept-points, restore-aside and cancel (the verbs of the four forms §516 gives and §566 names; take, restore, retry, aside, discard-aside and expire-points wait for D-19), events ended, restore-started, restored, set-aside, aside-discarded, point-removed (.) and expiry-ended, each kept 90 days and last per subject but expiry-ended, which has no parts and so no last-per-subject. The four acts that a process answers say by-caller; no verb names callers. The artifacts go-meshrecovery and ts-meshrecovery are in module.json, the seat in seats/index.json. Generated code waits for K21; the generator reads a verb's by-caller only once mesh-sdk's reader release (§621) knows it. Builds: design 47 G §516, §517, §523, §551, §554, §560, §563, §566, §567, §656, §659 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- module.json | 18 + seats/index.json | 1 + seats/mesh-recovery/fixtures/events.json | 121 ++++ seats/mesh-recovery/fixtures/verbs.json | 124 ++++ seats/mesh-recovery/seat.json | 788 +++++++++++++++++++++++ 5 files changed, 1052 insertions(+) create mode 100644 seats/mesh-recovery/fixtures/events.json create mode 100644 seats/mesh-recovery/fixtures/verbs.json create mode 100644 seats/mesh-recovery/seat.json diff --git a/module.json b/module.json index bfc775d..4631d72 100644 --- a/module.json +++ b/module.json @@ -29,6 +29,15 @@ ], "generated-from": "." }, + { + "name": "go-meshrecovery", + "kind": "package", + "language": "go", + "paths": [ + "go/seats/meshrecovery" + ], + "generated-from": "." + }, { "name": "go-meshconfig", "kind": "package", @@ -56,6 +65,15 @@ ], "generated-from": "." }, + { + "name": "ts-meshrecovery", + "kind": "package", + "language": "typescript", + "paths": [ + "ts/seats/meshrecovery" + ], + "generated-from": "." + }, { "name": "ts-meshconfig", "kind": "package", diff --git a/seats/index.json b/seats/index.json index 1b83c4b..7c54fd8 100644 --- a/seats/index.json +++ b/seats/index.json @@ -3,6 +3,7 @@ "seats": [ "mesh-store", "mesh-broker", + "mesh-recovery", "mesh-config", "node-login-shell", "node-power", diff --git a/seats/mesh-recovery/fixtures/events.json b/seats/mesh-recovery/fixtures/events.json new file mode 100644 index 0000000..2b13fb8 --- /dev/null +++ b/seats/mesh-recovery/fixtures/events.json @@ -0,0 +1,121 @@ +[ + { + "name": "ended is said", + "of": "event:ended", + "subject": "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", + "given": { + "act": "a-1", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "form": 2, + "fingerprint": "0123456789ab", + "snapshot": "2-0123456789ab", + "outcome": "done", + "consumers": [ + { + "stream": "KV_x", + "name": "c1", + "sequence": 42 + } + ], + "size": 2048, + "catch-up": { + "tool": "knowledge_catch_up" + }, + "digests": [ + { + "name": "KV_x", + "digest": "sha256:00" + } + ] + } + }, + { + "name": "ended is said", + "of": "event:ended", + "subject": "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", + "given": { + "act": "a-2", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "outcome": "failed", + "error": "stopped" + } + }, + { + "name": "restore-started is said", + "of": "event:restore-started", + "subject": "mesh.seat.mesh-recovery.event.restore-started.mesh-knowledge.ledger", + "given": { + "act": "a-3", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "form": 2, + "fingerprint": "0123456789ab", + "snapshot": "2-0123456789ab" + } + }, + { + "name": "restored is said", + "of": "event:restored", + "subject": "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", + "given": { + "act": "a-3", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "outcome": "failed", + "error": "restore point missing", + "missing": true + } + }, + { + "name": "set-aside is said", + "of": "event:set-aside", + "subject": "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", + "given": { + "act": "a-4", + "at": "2026-11-11T10:00:00Z", + "id": "20261111T121200Z", + "name": "mesh-knowledge_ledger", + "size": 4096 + } + }, + { + "name": "aside-discarded is said", + "of": "event:aside-discarded", + "subject": "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", + "given": { + "act": "a-5", + "at": "2026-11-11T10:00:00Z", + "id": "20261111T121200Z", + "name": "mesh-knowledge_ledger", + "size": 4096 + } + }, + { + "name": "point-removed is said", + "of": "event:point-removed", + "subject": "mesh.seat.mesh-recovery.event.point-removed.mesh-knowledge.ledger", + "given": { + "act": "a-6", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "snapshot": "1-aaaaaaaaaaaa" + } + }, + { + "name": "expiry-ended says 0 when it removed nothing", + "of": "event:expiry-ended", + "subject": "mesh.seat.mesh-recovery.event.expiry-ended", + "given": { + "act": "a-7", + "at": "2026-11-11T10:00:00Z", + "removed": 0 + } + } +] diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json new file mode 100644 index 0000000..71fbe83 --- /dev/null +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -0,0 +1,124 @@ +[ + { + "name": "snapshot-kept takes the point of a kept data before its form changes", + "of": "verb:snapshot-kept.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "form": 2, + "fingerprint": "0123456789ab", + "why": "form change of mesh-knowledge's ledger to 0123456789ab", + "catch-up": { + "tool": "knowledge_catch_up", + "arguments": { + "since": "0" + } + } + } + }, + { + "name": "snapshot-kept answers accepted with the act", + "of": "verb:snapshot-kept.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "restore-kept answers busy with the act that runs", + "of": "verb:restore-kept.answer", + "given": { + "busy": "a-20261111t100000" + } + }, + { + "name": "restore-kept takes a point and asks the backup for its directory", + "of": "verb:restore-kept.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "form": 2, + "fingerprint": "0123456789ab", + "why": "revert of mesh-knowledge's ledger from 0123456789ab", + "from-backup": true, + "snapshot": "2-0123456789ab" + } + }, + { + "name": "restore-kept answers an error naming why", + "of": "verb:restore-kept.answer", + "given": { + "error": "aside-only is the operator's hand tool alone" + } + }, + { + "name": "kept-points lists a point, an aside and the act that runs", + "of": "verb:kept-points.answer", + "given": { + "points": [ + { + "module": "mesh-knowledge", + "kept": "ledger", + "form": 2, + "fingerprint": "0123456789ab", + "snapshot": "2-0123456789ab", + "consumers": [ + { + "stream": "KV_x", + "name": "c1", + "sequence": 42 + } + ], + "size": 2048, + "at": "2026-11-11T10:00:00Z", + "catch-up": { + "tool": "knowledge_catch_up" + }, + "digests": [ + { + "name": "KV_x", + "digest": "sha256:00" + } + ] + } + ], + "asides": [ + { + "id": "20261111T121200Z", + "name": "mesh-knowledge_ledger", + "size": 4096 + } + ], + "running": { + "act": "a-1", + "step": "waiting on the dump", + "since": "2026-11-11T10:00:00Z", + "waits-on": "item-ended of the bus item" + } + } + }, + { + "name": "restore-aside names the aside", + "of": "verb:restore-aside.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "id": "20261111T121200Z", + "why": "an aside left at removed" + } + }, + { + "name": "cancel names the act", + "of": "verb:cancel.input", + "given": { + "act": "a-1", + "why": "the dump waits too long" + } + }, + { + "name": "cancel answers an error naming the step an act has begun", + "of": "verb:cancel.answer", + "given": { + "error": "the act has begun: step restoring" + } + } +] diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json new file mode 100644 index 0000000..92ca793 --- /dev/null +++ b/seats/mesh-recovery/seat.json @@ -0,0 +1,788 @@ +{ + "format": 1, + "seat": "mesh-recovery", + "scope": "mesh", + "grain": "whole", + "domain": "Core", + "decision": "novox/hq ADR 0672", + "description": "Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event.", + "verbs": [ + { + "name": "snapshot-kept", + "description": "Take the restore point of one module's kept data on the bus before it moves across a form change: the data whole and the position of each durable consumer. Answers accepted, busy or error at once; the point comes on the event ended (design 47 G 516, 554, 560).", + "by-caller": true, + "class": "act", + "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, or reverted from", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "restore-kept", + "description": "Restore one module's kept data from its restore point, the live data set aside first and never over it. Answers accepted, busy or error at once; the result comes on the event restored. It refuses aside-only and discard-aside: those are hand acts alone (design 47 G 516, 554, 560).", + "by-caller": true, + "class": "act", + "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, or reverted from", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "from-backup": { + "type": "boolean", + "description": "ask the backup holder for the points directory when the point is missing there (design 47 G 516)" + }, + "snapshot": { + "type": "string", + "description": "the restore point's name", + "minLength": 1 + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "kept-points", + "description": "Every restore point and aside the recovery module holds, with its module, kept data, form, fingerprint, size and when, and the act that runs, with since when and what it waits on (design 47 G 517, 554).", + "class": "read", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module (optional)" + }, + "kept": { + "type": "string", + "description": "one kept data (optional)" + } + }, + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "points": { + "type": "array", + "items": { + "$ref": "#/defs/Point" + } + }, + "asides": { + "type": "array", + "items": { + "$ref": "#/defs/Aside" + } + }, + "running": { + "$ref": "#/defs/Running" + } + }, + "required": [ + "points", + "asides" + ] + } + }, + { + "name": "restore-aside", + "description": "Restore an aside under the live names it was taken from, for an aside whose record ends at removed that no running act holds; it refuses while live objects of those names exist. Ends with restored (design 47 G 566).", + "by-caller": true, + "class": "act", + "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 + }, + "id": { + "type": "string", + "description": "the aside's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + } + }, + "required": [ + "module", + "kept", + "id", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "cancel", + "description": "End an accepted act that has not begun its work, with its ending event, outcome failed and error cancelled; it refuses an act that has begun, naming its step (design 47 G 566).", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "act": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + } + }, + "required": [ + "act", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "cancelled": { + "type": "boolean", + "description": "the act ended cancelled" + }, + "error": { + "type": "string", + "description": "why not, naming the step an act has begun; set alone" + } + } + } + } + ], + "events": [ + { + "name": "ended", + "subject": "ended..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a point taken, or the act failed; on done the point whole, on failed the error (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "how the act ended", + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string", + "description": "when failed" + }, + "consumers": { + "type": "array", + "items": { + "$ref": "#/defs/Consumer" + } + }, + "size": { + "type": "integer", + "minimum": 0 + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + }, + "digests": { + "type": "array", + "items": { + "$ref": "#/defs/Digest" + } + } + }, + "required": [ + "act", + "at", + "module", + "kept", + "outcome" + ] + } + }, + { + "name": "restore-started", + "subject": "restore-started..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore begins, said before it reads the dump's item events and before any aside is taken (design 47 G 560, 563)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + } + }, + "required": [ + "act", + "at", + "module", + "kept" + ] + } + }, + { + "name": "restored", + "subject": "restored..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore ended (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "how the act ended", + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string" + }, + "aside": { + "$ref": "#/defs/Aside" + }, + "missing": { + "type": "boolean", + "description": "the point is not in the recovery module's directory" + } + }, + "required": [ + "act", + "at", + "module", + "kept", + "outcome" + ] + } + }, + { + "name": "set-aside", + "subject": "set-aside..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "live data set aside by the hand act (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "size": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "id", + "name", + "size" + ] + } + }, + { + "name": "aside-discarded", + "subject": "aside-discarded..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "an aside discarded by the hand act (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "size": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "id", + "name", + "size" + ] + } + }, + { + "name": "point-removed", + "subject": "point-removed..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore point removed after its days, never the newest (design 47 G 551, 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + } + }, + "required": [ + "act", + "at", + "module", + "kept" + ] + } + }, + { + "name": "expiry-ended", + "keep": { + "max-age-days": 90 + }, + "body": { + "type": "object", + "description": "a run of the removal ended, also when it removed nothing (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "removed": { + "type": "integer", + "description": "the number of points the run removed, 0 included", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "removed" + ] + } + } + ], + "family": { + "name": "mesh-recovery.events", + "max-age-days": 7 + }, + "defs": { + "Consumer": { + "type": "object", + "description": "one durable consumer of the kept data and the sequence it had acknowledged", + "properties": { + "stream": { + "type": "string" + }, + "name": { + "type": "string" + }, + "sequence": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "stream", + "name", + "sequence" + ] + }, + "Digest": { + "type": "object", + "description": "the digest of one object of a point's bytes", + "properties": { + "name": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "name", + "digest" + ] + }, + "Point": { + "type": "object", + "description": "a restore point: the kept data whole and its consumers' positions, in the recovery module's points directory (design 47 G 516, 560)", + "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 it was taken before" + }, + "snapshot": { + "type": "string", + "description": "the point's name, also its directory's" + }, + "consumers": { + "type": "array", + "items": { + "$ref": "#/defs/Consumer" + } + }, + "size": { + "type": "integer", + "description": "its bytes", + "minimum": 0 + }, + "at": { + "type": "string", + "description": "when it was taken, RFC 3339", + "format": "date-time" + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + }, + "digests": { + "type": "array", + "items": { + "$ref": "#/defs/Digest" + }, + "description": "the digest of each object's bytes, checked before a restore (design 47 G 567)" + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "snapshot", + "size", + "at" + ] + }, + "Aside": { + "type": "object", + "description": "the live data set aside before a restore: a directory under aside/ in the recovery module's directory, nothing of it on the bus (design 47 G 516)", + "properties": { + "id": { + "type": "string", + "description": "the directory's name" + }, + "name": { + "type": "string", + "description": "the bus name it was live under" + }, + "size": { + "type": "integer", + "description": "its bytes on disk", + "minimum": 0 + } + }, + "required": [ + "id", + "name", + "size" + ] + }, + "Running": { + "type": "object", + "description": "the act that runs, since when and what it waits on (design 47 G 517, 554)", + "properties": { + "act": { + "type": "string" + }, + "step": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "waits-on": { + "type": "string", + "description": "what it waits on, when it waits" + } + }, + "required": [ + "act", + "since" + ] + }, + "CatchUp": { + "type": "object", + "description": "the catch-up of the newer manifest: a tool and its arguments, never text (design 47 G 451, 516, 631)", + "properties": { + "tool": { + "type": "string" + }, + "arguments": { + "type": "object" + } + }, + "required": [ + "tool" + ] + } + } +} From 74b616280709edb44af7c763dd61bc97c16c0133 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:31:55 +0100 Subject: [PATCH 37/62] K21a (regenerate, in between): the generated Go and TypeScript follow the definitions so far MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The conditions developer reads kinds, attempt-changed, wait-held and wait-ended from it. K21 regenerates last. The client meshconditionsclient does not build against the findings state's new layout until the question on it is answered. Builds: design 47 G §341, §523, §580, §541, §499 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/seats/meshbroker/contract.go | 9 + go/seats/meshbroker/contract_test.go | 4 + go/seats/meshrecovery/contract.go | 391 ++++++++++++++++++ go/seats/meshrecovery/contract_test.go | 80 ++++ go/seats/meshrecovery/go.mod | 3 + go/seats/nodeengine/contract.go | 136 ++++-- go/seats/nodeengine/contract_test.go | 18 +- .../go/seats/meshconditions/contract.go | 82 ++-- .../go/seats/meshconditions/contract_test.go | 28 +- .../go/seats/meshhealers/contract.go | 42 +- .../go/seats/meshhealers/contract_test.go | 4 + .../ts/seats/meshconditions/index.d.ts | 50 +-- .../ts/seats/meshconditions/index.js | 22 +- .../ts/seats/meshhealers/index.d.ts | 25 ++ .../ts/seats/meshhealers/index.js | 9 + .../go/seats/operatorchannel/contract.go | 4 + .../go/seats/operatorchannel/contract_test.go | 4 + .../ts/seats/operatorchannel/index.d.ts | 4 + ts/seats/meshbroker/index.d.ts | 9 + ts/seats/meshrecovery/index.d.ts | 330 +++++++++++++++ ts/seats/meshrecovery/index.js | 78 ++++ ts/seats/meshrecovery/package-lock.json | 12 + ts/seats/meshrecovery/package.json | 18 + ts/seats/nodeengine/index.d.ts | 114 ++++- ts/seats/nodeengine/index.js | 21 +- 25 files changed, 1335 insertions(+), 162 deletions(-) create mode 100644 go/seats/meshrecovery/contract.go create mode 100644 go/seats/meshrecovery/contract_test.go create mode 100644 go/seats/meshrecovery/go.mod create mode 100644 ts/seats/meshrecovery/index.d.ts create mode 100644 ts/seats/meshrecovery/index.js create mode 100644 ts/seats/meshrecovery/package-lock.json create mode 100644 ts/seats/meshrecovery/package.json diff --git a/go/seats/meshbroker/contract.go b/go/seats/meshbroker/contract.go index a44f83d..50f6366 100644 --- a/go/seats/meshbroker/contract.go +++ b/go/seats/meshbroker/contract.go @@ -278,8 +278,17 @@ type ListInput struct { Module string `json:"module,omitempty"` } +// ListAnswerCaps is the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661). +type ListAnswerCaps struct { + AccountLimitMiB int64 `json:"account-limit-mib,omitempty"` + ServerLimitMiB int64 `json:"server-limit-mib,omitempty"` + SumMiB int64 `json:"sum-mib"` +} + // ListAnswer is what list answers. type ListAnswer struct { + // the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661) + Caps *ListAnswerCaps `json:"caps,omitempty"` // every entry Entries []Held `json:"entries"` } diff --git a/go/seats/meshbroker/contract_test.go b/go/seats/meshbroker/contract_test.go index dc86363..59c281f 100644 --- a/go/seats/meshbroker/contract_test.go +++ b/go/seats/meshbroker/contract_test.go @@ -45,6 +45,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ListAnswer; 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}, + {name: "list answers the sum of the caps and both limits (design 47 G 661)", subject: "", given: "{\"caps\":{\"account-limit-mib\":1024,\"server-limit-mib\":2048,\"sum-mib\":512},\"entries\":[]}", wire: "{\"caps\":{\"account-limit-mib\":1024,\"server-limit-mib\":2048,\"sum-mib\":512},\"entries\":[]}", + decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "list answers a sum with no limit, which is unlimited", subject: "", given: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}", wire: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}", + 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)) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go new file mode 100644 index 0000000..7c6a38a --- /dev/null +++ b/go/seats/meshrecovery/contract.go @@ -0,0 +1,391 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// Package meshrecovery is the contract of the seat "mesh-recovery", defined whole (seats/mesh-recovery/seat.json): Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event. +package meshrecovery + +import "time" + +// Seat is the seat's name. +const Seat = "mesh-recovery" + +const ( + VerbSnapshotKept = "snapshot-kept" + VerbRestoreKept = "restore-kept" + VerbKeptPoints = "kept-points" + VerbRestoreAside = "restore-aside" + VerbCancel = "cancel" +) + +const ( + EventEnded = "ended" + EventRestoreStarted = "restore-started" + EventRestored = "restored" + EventSetAside = "set-aside" + EventAsideDiscarded = "aside-discarded" + EventPointRemoved = "point-removed" + EventExpiryEnded = "expiry-ended" +) + +// Verbs is every verb the seat serves, in its definition's order: a new copy each call. +func Verbs() []string { + return []string{VerbSnapshotKept, VerbRestoreKept, VerbKeptPoints, VerbRestoreAside, VerbCancel} +} + +// Events is every event published on the seat's subject: a new copy each call. +func Events() []string { + return []string{EventEnded, EventRestoreStarted, EventRestored, EventSetAside, EventAsideDiscarded, EventPointRemoved, EventExpiryEnded} +} + +// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. +const ( + Family = "mesh-recovery.events" + FamilyMaxAgeDays = 7 +) + +// StreamEnded is the stream ended is kept in. +const StreamEnded = "SEAT_mesh-recovery_ended" + +// SubjectEnded is where ended is published, on mesh.seat.mesh-recovery.event.ended... +func SubjectEnded(module, kept string) string { + return "mesh.seat.mesh-recovery.event.ended." + module + "." + kept +} + +// SubjectEndedAll hears every ended. +const SubjectEndedAll = "mesh.seat.mesh-recovery.event.ended.*.*" + +// StreamRestoreStarted is the stream restore-started is kept in. +const StreamRestoreStarted = "SEAT_mesh-recovery_restore-started" + +// SubjectRestoreStarted is where restore-started is published, on mesh.seat.mesh-recovery.event.restore-started... +func SubjectRestoreStarted(module, kept string) string { + return "mesh.seat.mesh-recovery.event.restore-started." + module + "." + kept +} + +// SubjectRestoreStartedAll hears every restore-started. +const SubjectRestoreStartedAll = "mesh.seat.mesh-recovery.event.restore-started.*.*" + +// StreamRestored is the stream restored is kept in. +const StreamRestored = "SEAT_mesh-recovery_restored" + +// SubjectRestored is where restored is published, on mesh.seat.mesh-recovery.event.restored... +func SubjectRestored(module, kept string) string { + return "mesh.seat.mesh-recovery.event.restored." + module + "." + kept +} + +// SubjectRestoredAll hears every restored. +const SubjectRestoredAll = "mesh.seat.mesh-recovery.event.restored.*.*" + +// StreamSetAside is the stream set-aside is kept in. +const StreamSetAside = "SEAT_mesh-recovery_set-aside" + +// SubjectSetAside is where set-aside is published, on mesh.seat.mesh-recovery.event.set-aside... +func SubjectSetAside(module, kept string) string { + return "mesh.seat.mesh-recovery.event.set-aside." + module + "." + kept +} + +// SubjectSetAsideAll hears every set-aside. +const SubjectSetAsideAll = "mesh.seat.mesh-recovery.event.set-aside.*.*" + +// StreamAsideDiscarded is the stream aside-discarded is kept in. +const StreamAsideDiscarded = "SEAT_mesh-recovery_aside-discarded" + +// SubjectAsideDiscarded is where aside-discarded is published, on mesh.seat.mesh-recovery.event.aside-discarded... +func SubjectAsideDiscarded(module, kept string) string { + return "mesh.seat.mesh-recovery.event.aside-discarded." + module + "." + kept +} + +// SubjectAsideDiscardedAll hears every aside-discarded. +const SubjectAsideDiscardedAll = "mesh.seat.mesh-recovery.event.aside-discarded.*.*" + +// StreamPointRemoved is the stream point-removed is kept in. +const StreamPointRemoved = "SEAT_mesh-recovery_point-removed" + +// SubjectPointRemoved is where point-removed is published, on mesh.seat.mesh-recovery.event.point-removed... +func SubjectPointRemoved(module, kept string) string { + return "mesh.seat.mesh-recovery.event.point-removed." + module + "." + kept +} + +// SubjectPointRemovedAll hears every point-removed. +const SubjectPointRemovedAll = "mesh.seat.mesh-recovery.event.point-removed.*.*" + +// StreamExpiryEnded is the stream expiry-ended is kept in. +const StreamExpiryEnded = "SEAT_mesh-recovery_expiry-ended" + +// SubjectExpiryEnded is where expiry-ended is published. +const SubjectExpiryEnded = "mesh.seat.mesh-recovery.event.expiry-ended" + +// Aside is the live data set aside before a restore: a directory under aside/ in the recovery module's directory, nothing of it on the bus (design 47 G 516). +type Aside struct { + // the directory's name + ID string `json:"id"` + // the bus name it was live under + Name string `json:"name"` + // its bytes on disk + Size int64 `json:"size"` +} + +// CatchUp is the catch-up of the newer manifest: a tool and its arguments, never text (design 47 G 451, 516, 631). +type CatchUp struct { + Arguments map[string]any `json:"arguments,omitempty"` + Tool string `json:"tool"` +} + +// Consumer is one durable consumer of the kept data and the sequence it had acknowledged. +type Consumer struct { + Name string `json:"name"` + Sequence int64 `json:"sequence"` + Stream string `json:"stream"` +} + +// Digest is the digest of one object of a point's bytes. +type Digest struct { + Digest string `json:"digest"` + Name string `json:"name"` +} + +// Point is a restore point: the kept data whole and its consumers' positions, in the recovery module's points directory (design 47 G 516, 560). +type Point struct { + // when it was taken, RFC 3339 + At time.Time `json:"at"` + CatchUp *CatchUp `json:"catch-up,omitempty"` + Consumers []Consumer `json:"consumers,omitempty"` + // the digest of each object's bytes, checked before a restore (design 47 G 567) + Digests []Digest `json:"digests,omitempty"` + // the fingerprint it was 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 bytes + Size int64 `json:"size"` + // the point's name, also its directory's + Snapshot string `json:"snapshot"` +} + +// Running is the act that runs, since when and what it waits on (design 47 G 517, 554). +type Running struct { + Act string `json:"act"` + Since time.Time `json:"since"` + Step string `json:"step,omitempty"` + // what it waits on, when it waits + WaitsOn string `json:"waits-on,omitempty"` +} + +// SnapshotKeptInput is what snapshot-kept takes. +type SnapshotKeptInput struct { + CatchUp *CatchUp `json:"catch-up,omitempty"` + // the fingerprint the restore point is taken before, or reverted from + 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, which the hand-act log keeps + Why string `json:"why"` +} + +// SnapshotKeptAnswer is what snapshot-kept answers. +type SnapshotKeptAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// RestoreKeptInput is what restore-kept takes. +type RestoreKeptInput struct { + // the fingerprint the restore point is taken before, or reverted from + 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"` + // ask the backup holder for the points directory when the point is missing there (design 47 G 516) + FromBackup bool `json:"from-backup,omitempty"` + // 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 + Snapshot string `json:"snapshot,omitempty"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// RestoreKeptAnswer is what restore-kept answers. +type RestoreKeptAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// KeptPointsInput is what kept-points takes. +type KeptPointsInput struct { + // one kept data (optional) + Kept string `json:"kept,omitempty"` + // one module (optional) + Module string `json:"module,omitempty"` +} + +// KeptPointsAnswer is what kept-points answers. +type KeptPointsAnswer struct { + Asides []Aside `json:"asides"` + Points []Point `json:"points"` + Running *Running `json:"running,omitempty"` +} + +// RestoreAsideInput is what restore-aside takes. +type RestoreAsideInput struct { + // the aside's id + ID string `json:"id"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// RestoreAsideAnswer is what restore-aside answers. +type RestoreAsideAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// CancelInput is what cancel takes. +type CancelInput struct { + // the act's id + Act string `json:"act"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// CancelAnswer is what cancel answers. +type CancelAnswer struct { + // the act ended cancelled + Cancelled bool `json:"cancelled,omitempty"` + // why not, naming the step an act has begun; set alone + Error string `json:"error,omitempty"` +} + +// EndedEvent is the body of the event ended. +type EndedEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + CatchUp *CatchUp `json:"catch-up,omitempty"` + Consumers []Consumer `json:"consumers,omitempty"` + Digests []Digest `json:"digests,omitempty"` + // when failed + Error string `json:"error,omitempty"` + Fingerprint string `json:"fingerprint,omitempty"` + Form int64 `json:"form,omitempty"` + Kept string `json:"kept"` + Module string `json:"module"` + // how the act ended + Outcome string `json:"outcome"` + Size int64 `json:"size,omitempty"` + Snapshot string `json:"snapshot,omitempty"` +} + +// The values of EndedEvent's outcome. +const ( + EndedEventOutcomeDone = "done" + EndedEventOutcomeFailed = "failed" +) + +// RestoreStartedEvent is the body of the event restore-started. +type RestoreStartedEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + Fingerprint string `json:"fingerprint,omitempty"` + Form int64 `json:"form,omitempty"` + Kept string `json:"kept"` + Module string `json:"module"` + Snapshot string `json:"snapshot,omitempty"` +} + +// RestoredEvent is the body of the event restored. +type RestoredEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + Aside *Aside `json:"aside,omitempty"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + Error string `json:"error,omitempty"` + Fingerprint string `json:"fingerprint,omitempty"` + Form int64 `json:"form,omitempty"` + Kept string `json:"kept"` + // the point is not in the recovery module's directory + Missing bool `json:"missing,omitempty"` + Module string `json:"module"` + // how the act ended + Outcome string `json:"outcome"` + Snapshot string `json:"snapshot,omitempty"` +} + +// The values of RestoredEvent's outcome. +const ( + RestoredEventOutcomeDone = "done" + RestoredEventOutcomeFailed = "failed" +) + +// SetAsideEvent is the body of the event set-aside. +type SetAsideEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + ID string `json:"id"` + Name string `json:"name"` + Size int64 `json:"size"` +} + +// AsideDiscardedEvent is the body of the event aside-discarded. +type AsideDiscardedEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + ID string `json:"id"` + Name string `json:"name"` + Size int64 `json:"size"` +} + +// PointRemovedEvent is the body of the event point-removed. +type PointRemovedEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + Fingerprint string `json:"fingerprint,omitempty"` + Form int64 `json:"form,omitempty"` + Kept string `json:"kept"` + Module string `json:"module"` + Snapshot string `json:"snapshot,omitempty"` +} + +// ExpiryEndedEvent is the body of the event expiry-ended. +type ExpiryEndedEvent struct { + // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) + Act string `json:"act"` + // when it was said, RFC 3339 + At time.Time `json:"at"` + // the number of points the run removed, 0 included + Removed int64 `json:"removed"` +} diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go new file mode 100644 index 0000000..27e7065 --- /dev/null +++ b/go/seats/meshrecovery/contract_test.go @@ -0,0 +1,80 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +package meshrecovery + +import ( + "encoding/json" + "reflect" + "regexp" + "testing" +) + +// TestFixtures reads every fixture of seats/mesh-recovery/fixtures: each decodes into its type, a field the type does not +// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's. +func TestFixtures(t *testing.T) { + cases := []struct { + name, subject, given, wire string + decode func([]byte) (any, error) + subjectIs *regexp.Regexp + }{ + {name: "ended is said", subject: "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", given: "{\"act\":\"a-1\",\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"done\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}", wire: "{\"act\":\"a-1\",\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"done\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}", + decode: func(b []byte) (any, error) { var v EndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.ended\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "ended is said", subject: "mesh.seat.mesh-recovery.event.ended.mesh-knowledge.ledger", given: "{\"act\":\"a-2\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"stopped\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", wire: "{\"act\":\"a-2\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"stopped\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", + decode: func(b []byte) (any, error) { var v EndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.ended\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "restore-started is said", subject: "mesh.seat.mesh-recovery.event.restore-started.mesh-knowledge.ledger", given: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\"}", wire: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\"}", + decode: func(b []byte) (any, error) { var v RestoreStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restore-started\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "restored is said", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", wire: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", + decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "set-aside is said", subject: "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", + decode: func(b []byte) (any, error) { var v SetAsideEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.set-aside\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "aside-discarded is said", subject: "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", given: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", + decode: func(b []byte) (any, error) { var v AsideDiscardedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.aside-discarded\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "point-removed is said", subject: "mesh.seat.mesh-recovery.event.point-removed.mesh-knowledge.ledger", given: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}", wire: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}", + decode: func(b []byte) (any, error) { var v PointRemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.point-removed\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "expiry-ended says 0 when it removed nothing", subject: "mesh.seat.mesh-recovery.event.expiry-ended", given: "{\"act\":\"a-7\",\"at\":\"2026-11-11T10:00:00Z\",\"removed\":0}", wire: "{\"act\":\"a-7\",\"at\":\"2026-11-11T10:00:00Z\",\"removed\":0}", + decode: func(b []byte) (any, error) { var v ExpiryEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.expiry-ended$")}, + {name: "snapshot-kept takes the point of a kept data before its form changes", subject: "", given: "{\"catch-up\":{\"arguments\":{\"since\":\"0\"},\"tool\":\"knowledge_catch_up\"},\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"form change of mesh-knowledge's ledger to 0123456789ab\"}", wire: "{\"catch-up\":{\"arguments\":{\"since\":\"0\"},\"tool\":\"knowledge_catch_up\"},\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"form change of mesh-knowledge's ledger to 0123456789ab\"}", + decode: func(b []byte) (any, error) { var v SnapshotKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-kept answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v SnapshotKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore-kept answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore-kept takes a point and asks the backup for its directory", subject: "", given: "{\"fingerprint\":\"0123456789ab\",\"form\":2,\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"revert of mesh-knowledge's ledger from 0123456789ab\"}", wire: "{\"fingerprint\":\"0123456789ab\",\"form\":2,\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"revert of mesh-knowledge's ledger from 0123456789ab\"}", + decode: func(b []byte) (any, error) { var v RestoreKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore-kept answers an error naming why", subject: "", given: "{\"error\":\"aside-only is the operator's hand tool alone\"}", wire: "{\"error\":\"aside-only is the operator's hand tool alone\"}", + decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", + decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore-aside names the aside", subject: "", given: "{\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", + decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"why\":\"the dump waits too long\"}", + decode: func(b []byte) (any, error) { var v CancelInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "cancel answers an error naming the step an act has begun", subject: "", given: "{\"error\":\"the act has begun: step restoring\"}", wire: "{\"error\":\"the act has begun: step restoring\"}", + decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + } + for _, c := range cases { + v, err := c.decode([]byte(c.given)) + if err != nil { + t.Errorf("%s: does not decode: %v", c.name, err) + continue + } + back, err := json.Marshal(v) + if err != nil { + t.Errorf("%s: does not encode: %v", c.name, err) + continue + } + var got, want any + if err := json.Unmarshal(back, &got); err != nil { + t.Fatal(err) + } + if err := json.Unmarshal([]byte(c.wire), &want); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire) + } + if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) { + t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs) + } + } +} diff --git a/go/seats/meshrecovery/go.mod b/go/seats/meshrecovery/go.mod new file mode 100644 index 0000000..ba61b71 --- /dev/null +++ b/go/seats/meshrecovery/go.mod @@ -0,0 +1,3 @@ +module git.novox.be/novox/mesh-contracts/go/seats/meshrecovery + +go 1.26.0 diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 081ecee..96e1647 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -28,6 +28,8 @@ const ( VerbManifestReads = "manifest-reads" VerbSeatList = "seat-list" VerbSeatListAgain = "seat-list-again" + VerbFirstViews = "first-views" + VerbFirstViewAgain = "first-view-again" VerbProcessBuilds = "process-builds" ) @@ -38,17 +40,18 @@ const ( EventManifestReadsChanged = "manifest-reads-changed" EventComposed = "composed" EventRunning = "running" - EventCapabilitiesChanged = "capabilities-changed" + EventWaitHeld = "wait-held" + EventWaitEnded = "wait-ended" ) // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbProcessBuilds} + return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbFirstViews, VerbFirstViewAgain, VerbProcessBuilds} } // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged, EventComposed, EventRunning, EventCapabilitiesChanged} + return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged, EventComposed, EventRunning, EventWaitHeld, EventWaitEnded} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -88,13 +91,27 @@ func SubjectRunning(node, module string) string { // SubjectRunningAll hears every running. const SubjectRunningAll = "mesh.seat.node-engine.event.running.*.*" -// SubjectCapabilitiesChanged is where capabilities-changed is published, on mesh.seat.node-engine.event.capabilities-changed.. -func SubjectCapabilitiesChanged(node string) string { - return "mesh.seat.node-engine.event.capabilities-changed." + node +// StreamWaitHeld is the stream wait-held is kept in. +const StreamWaitHeld = "SEAT_node-engine_wait-held" + +// SubjectWaitHeld is where wait-held is published, on mesh.seat.node-engine.event.wait-held... +func SubjectWaitHeld(node, module string) string { + return "mesh.seat.node-engine.event.wait-held." + node + "." + module } -// SubjectCapabilitiesChangedAll hears every capabilities-changed. -const SubjectCapabilitiesChangedAll = "mesh.seat.node-engine.event.capabilities-changed.*" +// SubjectWaitHeldAll hears every wait-held. +const SubjectWaitHeldAll = "mesh.seat.node-engine.event.wait-held.*.*" + +// StreamWaitEnded is the stream wait-ended is kept in. +const StreamWaitEnded = "SEAT_node-engine_wait-ended" + +// SubjectWaitEnded is where wait-ended is published, on mesh.seat.node-engine.event.wait-ended... +func SubjectWaitEnded(node, module string) string { + return "mesh.seat.node-engine.event.wait-ended." + node + "." + module +} + +// SubjectWaitEndedAll hears every wait-ended. +const SubjectWaitEndedAll = "mesh.seat.node-engine.event.wait-ended.*.*" const ( StateHave = "have" @@ -552,18 +569,6 @@ type CandidateRefusal struct { Why string `json:"why"` } -// CapabilitiesChanged is a node's capabilities changed, which the assigner places by. -type CapabilitiesChanged struct { - // when, RFC 3339 - At time.Time `json:"at"` - // its capabilities now - Capabilities []string `json:"capabilities"` - // the node - Node string `json:"node"` - // the layout's version - V int64 `json:"v"` -} - // Composed is an entry composed on a node (design 47 *What each step says*). type Composed struct { // when, RFC 3339 @@ -885,19 +890,21 @@ type RootVerdict struct { Why string `json:"why"` } -// Running is a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit. +// Running is a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit. type Running struct { - // when it was seen running healthy, RFC 3339 + // when it was said, RFC 3339 At time.Time `json:"at"` // the fingerprint of the build it runs; none with stopped Fingerprint string `json:"fingerprint,omitempty"` + // the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat + Healthy *bool `json:"healthy,omitempty"` // the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half Manifest string `json:"manifest,omitempty"` // the module Module string `json:"module"` // the node Node string `json:"node"` - // true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there + // true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there Stopped bool `json:"stopped,omitempty"` // the layout's version V int64 `json:"v"` @@ -987,6 +994,37 @@ type UserListWritten struct { Wanted string `json:"wanted"` } +// Wait is a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560). +type Wait struct { + // in the have: the act the recovery module answered accepted with (design 47 G 560) + Act string `json:"act,omitempty"` + // in the have: the time of the first ask of the recovery module for this wait (design 47 G 560) + AskAt *time.Time `json:"ask-at,omitempty"` + // a duration such as 30m + Bound string `json:"bound,omitempty"` + // the time the bound counts from (design 47 G 266, 269, 498) + ClockFrom *time.Time `json:"clock-from,omitempty"` + // the node waited on: the build node for a kept build; the subject's is the node that says it + Node string `json:"node,omitempty"` + // what it waits on + On string `json:"on,omitempty"` + // the seat holding the wait: node-engine + Owner string `json:"owner,omitempty"` + // why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499) + Reason string `json:"reason,omitempty"` + Since time.Time `json:"since"` + // compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541) + Step string `json:"step"` + // the wait said in words + Words string `json:"words,omitempty"` +} + +// The values of Wait's step. +const ( + WaitStepCompose = "compose" + WaitStepKeptBuild = "kept-build" +) + // HandOverInput is what hand-over takes. type HandOverInput struct { // the directory's absolute path, as the engine states it @@ -1324,6 +1362,50 @@ type SeatListAgainInput struct { // SeatListAgainAnswer is what seat-list-again answers. type SeatListAgainAnswer = SeatList +// FirstViewsInput is what first-views takes. +type FirstViewsInput struct { +} + +// FirstViewsAnswer is what first-views answers. +type FirstViewsAnswer struct { + // one status per owner and state followed, as mesh-sdk's views runtime keeps it + FirstViews []map[string]any `json:"first-views"` +} + +// FirstViewAgainInput is what first-view-again takes. +type FirstViewAgainInput struct { + // the owner module, as first-views names it + Owner string `json:"owner"` + // the owner's state, as first-views names it + State string `json:"state"` + // why it is asked again, in plain words + Why string `json:"why"` +} + +// FirstViewAgainAnswerAsked is the hand ask written. +type FirstViewAgainAnswerAsked struct { + // when it was asked, RFC 3339 + At time.Time `json:"at"` + // the caller the runtime proved + By string `json:"by"` + // the owner module + Owner string `json:"owner"` + // the owner's state + State string `json:"state"` + // the layout's version + V int64 `json:"v"` + // why it was asked again + Why string `json:"why"` +} + +// FirstViewAgainAnswer is what first-view-again answers. +type FirstViewAgainAnswer struct { + // the hand ask written + Asked FirstViewAgainAnswerAsked `json:"asked"` + // the verb that reads the status, first-views + Read string `json:"read"` +} + // ProcessBuildsInput is what process-builds takes. type ProcessBuildsInput struct { // only this module's processes @@ -1351,8 +1433,11 @@ type ComposedEvent = Composed // RunningEvent is the body of the event running. type RunningEvent = Running -// CapabilitiesChangedEvent is the body of the event capabilities-changed. -type CapabilitiesChangedEvent = CapabilitiesChanged +// WaitHeldEvent is the body of the event wait-held. +type WaitHeldEvent = Wait + +// WaitEndedEvent is the body of the event wait-ended. +type WaitEndedEvent = Wait // HaveByNodeModuleValue is one value of the state have under the key .. type HaveByNodeModuleValue struct { @@ -1380,6 +1465,7 @@ type HaveByNodeModuleValue struct { SealedAt map[string]string `json:"sealed-at,omitempty"` UserList *UserListWritten `json:"user-list,omitempty"` V int64 `json:"v"` + Wait *Wait `json:"wait,omitempty"` // in phase waiting-yes, the digest of the composition that waits Waits string `json:"waits,omitempty"` } diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index e2ed2d8..7551025 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -39,14 +39,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ComposedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.composed\\.[^.*> ]+$")}, {name: "running is said, its node and module in its subject", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "running says the build that runs is healthy", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "running says the build that runs turned unhealthy, still running", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "running says a module stopped on the node, with no fingerprint", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "capabilities-changed is said", subject: "mesh.seat.node-engine.event.capabilities-changed.ace", given: "{\"at\":\"2026-11-09T20:02:00Z\",\"capabilities\":[\"build-go\",\"docker\"],\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:02:00Z\",\"capabilities\":[\"build-go\",\"docker\"],\"node\":\"ace\",\"v\":1}", - decode: func(b []byte) (any, error) { - var v CapabilitiesChangedEvent - err := json.Unmarshal(b, &v) - return v, err - }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.capabilities-changed\\.[^.*> ]+$")}, + {name: "a kept build's wait is held", subject: "mesh.seat.node-engine.event.wait-held.ace.postgres", given: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"ace\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on ace\"}", wire: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"ace\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on ace\"}", + decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-held\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "a hold of the composition ends", subject: "mesh.seat.node-engine.event.wait-ended.ace.postgres", given: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", wire: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", + decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-ended\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "the finding of a seat list unread, as the engine writes it", subject: "", given: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", wire: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a node's packages, present and absent (captured from ace, shortened)", subject: "", given: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}", wire: "{\"node\":\"ace\",\"packages\":[{\"absent\":false,\"modules\":[\"avahi\"],\"package\":\"avahi\"},{\"absent\":false,\"modules\":[\"mesh-build-go\",\"mesh-build-node\"],\"package\":\"bubblewrap\"},{\"absent\":true,\"modules\":[\"time-sync\"],\"package\":\"ntp\"}]}", @@ -89,6 +91,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v DataByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a node's health (typed from the engine's values)", subject: "", given: "{\"at\":\"2026-11-05T12:00:00Z\",\"contract\":3,\"network\":{\"parts\":[{\"part\":\"resolver\",\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"}],\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"},\"node\":\"ace\",\"peers\":[{\"addresses\":[\"198.51.100.1\"],\"key\":\"k\",\"seen\":true}],\"relogin\":[{\"account\":\"web\",\"reason\":\"password changed\",\"since\":\"2026-11-05T11:00:00Z\"}],\"units\":{\"failed\":[{\"result\":\"exit-code\",\"scope\":\"system\",\"since\":\"2026-11-05T11:00:00Z\",\"unit\":\"x.service\"}],\"state\":\"degraded\"},\"v\":1}", wire: "{\"at\":\"2026-11-05T12:00:00Z\",\"contract\":3,\"network\":{\"parts\":[{\"part\":\"resolver\",\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"}],\"since\":\"2026-11-05T10:00:00Z\",\"state\":\"running\"},\"node\":\"ace\",\"peers\":[{\"addresses\":[\"198.51.100.1\"],\"key\":\"k\",\"seen\":true}],\"relogin\":[{\"account\":\"web\",\"reason\":\"password changed\",\"since\":\"2026-11-05T11:00:00Z\"}],\"units\":{\"failed\":[{\"result\":\"exit-code\",\"scope\":\"system\",\"since\":\"2026-11-05T11:00:00Z\",\"unit\":\"x.service\"}],\"state\":\"degraded\"},\"v\":1}", decode: func(b []byte) (any, error) { var v HealthByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a have that waits for the recovery module, with its wait, ask-at and act (design 47 G 560, 629)", subject: "", given: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}", wire: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}", + decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "manifest-reads answers what the engine reads and when it stated it", subject: "", given: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}", wire: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}", decode: func(b []byte) (any, error) { var v ManifestReadsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "manifest-reads of an engine built before it said them is the baseline", subject: "", given: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}", wire: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}", @@ -109,6 +113,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "process-builds answers an error", subject: "", given: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", wire: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "first-view-again names the owner, its state and why", subject: "", given: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", wire: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", + decode: func(b []byte) (any, error) { var v FirstViewAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/health-and-repair/go/seats/meshconditions/contract.go b/health-and-repair/go/seats/meshconditions/contract.go index 73984b6..5962e98 100644 --- a/health-and-repair/go/seats/meshconditions/contract.go +++ b/health-and-repair/go/seats/meshconditions/contract.go @@ -95,26 +95,36 @@ func DecodeConditionsByKeyValue(raw []byte) (ConditionsByKeyValue, error) { return v, nil } -// FindingsByKeyKey is the key of one value of the state findings under the form "". -func FindingsByKeyKey(key string) string { return key } +// FindingsByScopeIDKindKey is the key of one value of the state findings under the form "..". +func FindingsByScopeIDKindKey(scope, id, kind string) string { return scope + "." + id + "." + kind } -// ParseFindingsByKeyKey reads the parts of a key of the form "", in the order of the form; the last result is false for a key of another form. -func ParseFindingsByKeyKey(key string) (string, bool) { +// ParseFindingsByScopeIDKindKey reads the parts of a key of the form "..", in the order of the form; the last result is false for a key of another form. +func ParseFindingsByScopeIDKindKey(key string) (string, string, string, bool) { rest := key - if rest == "" { - return "", false + v0, after0, found0 := strings.Cut(rest, ".") + if !found0 || v0 == "" { + return "", "", "", false } - v0 := rest + rest = after0 + v2, after2, found2 := strings.Cut(rest, ".") + if !found2 || v2 == "" { + return "", "", "", false + } + rest = after2 + if rest == "" { + return "", "", "", false + } + v4 := rest rest = "" if rest != "" { - return "", false + return "", "", "", false } - return v0, true + return v0, v2, v4, true } -// DecodeFindingsByKeyValue reads one value of the state findings under the form "", refusing a field FindingsByKeyValue does not know and any text after the value. -func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) { - var v FindingsByKeyValue +// DecodeFindingsByScopeIDKindValue reads one value of the state findings under the form "..", refusing a field FindingsByScopeIDKindValue does not know and any text after the value. +func DecodeFindingsByScopeIDKindValue(raw []byte) (FindingsByScopeIDKindValue, error) { + var v FindingsByScopeIDKindValue dec := json.NewDecoder(bytes.NewReader(raw)) dec.DisallowUnknownFields() if err := dec.Decode(&v); err != nil { @@ -290,7 +300,7 @@ type Finding struct { Needs string `json:"needs,omitempty"` // the module that wrote it Observer string `json:"observer"` - // the module the finding is about, when not the observer + // who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) Owner string `json:"owner,omitempty"` // the key's last part when it is not the kind Ref string `json:"ref,omitempty"` @@ -308,7 +318,7 @@ type Finding struct { Subject Subject `json:"subject"` // one line Summary string `json:"summary"` - // what it waits on: a person, a part or a call + // what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) WaitingOn string `json:"waiting-on,omitempty"` } @@ -344,6 +354,8 @@ type FindingsStated struct { Asked string `json:"asked,omitempty"` At time.Time `json:"at"` Findings []Finding `json:"findings"` + // the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580) + Kinds []string `json:"kinds,omitempty"` // the keys the observer cannot judge yet since its start, with their since and bound Pending []FindingsStatedPendingItem `json:"pending"` } @@ -477,46 +489,8 @@ const ( ConditionsByKeyValueSeverityWarning = "warning" ) -// FindingsByKeyValue is one value of the state findings under the key . -type FindingsByKeyValue struct { - Actions []Action `json:"actions,omitempty"` - At time.Time `json:"at"` - // newest first, at most 10 - Evidence []Evidence `json:"evidence,omitempty"` - Explanation string `json:"explanation,omitempty"` - Headline string `json:"headline,omitempty"` - // scope.id.token - Key string `json:"key"` - Kind string `json:"kind"` - Needs string `json:"needs,omitempty"` - // the module that wrote it - Observer string `json:"observer"` - // the module the finding is about, when not the observer - Owner string `json:"owner,omitempty"` - // the key's last part when it is not the kind - Ref string `json:"ref,omitempty"` - Resolved string `json:"resolved,omitempty"` - // self, operator, agent or healer: - Resolver string `json:"resolver,omitempty"` - // what of its own saw it last - Run string `json:"run,omitempty"` - Severity string `json:"severity"` - // the row, probe or event that saw it - Source string `json:"source"` - Subject Subject `json:"subject"` - // one line - Summary string `json:"summary"` - // layout version, 1 - V int64 `json:"v"` - // what it waits on: a person, a part or a call - WaitingOn string `json:"waiting-on,omitempty"` -} - -// The values of FindingsByKeyValue's severity. -const ( - FindingsByKeyValueSeverityUrgent = "urgent" - FindingsByKeyValueSeverityWarning = "warning" -) +// FindingsByScopeIDKindValue is one value of the state findings under the key ... +type FindingsByScopeIDKindValue = Finding // FindingsViewsByObserverNodeValueStated is the last findings-stated set. type FindingsViewsByObserverNodeValueStated struct { diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index 2a769d7..92f71e5 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -25,10 +25,30 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a finding of the bus scope with its zero time (captured from the watchman; empty fields left out)", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"key\":\"bus.EVENTS.controller.max-deliveries\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"severity\":\"warning\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\",\"v\":1}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"key\":\"bus.EVENTS.controller.max-deliveries\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"severity\":\"warning\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\",\"v\":1}", - decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a finding of the module scope with its machine (captured from the watchman; empty fields left out)", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\",\"v\":1}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\",\"v\":1}", - decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", + decode: func(b []byte) (any, error) { + var v FindingsByScopeIDKindValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, + {name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.ace\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.ace\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", + decode: func(b []byte) (any, error) { + var v FindingsByScopeIDKindValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, + {name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"jochen@shanks\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"jochen@shanks\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + decode: func(b []byte) (any, error) { + var v FindingsByScopeIDKindValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, + {name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:jochen\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:jochen\"}", + decode: func(b []byte) (any, error) { + var v FindingsByScopeIDKindValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/health-and-repair/go/seats/meshhealers/contract.go b/health-and-repair/go/seats/meshhealers/contract.go index 4733ebc..33b70ee 100644 --- a/health-and-repair/go/seats/meshhealers/contract.go +++ b/health-and-repair/go/seats/meshhealers/contract.go @@ -20,7 +20,8 @@ const ( ) const ( - EventHealerActed = "healer-acted" + EventHealerActed = "healer-acted" + EventAttemptChanged = "attempt-changed" ) // Verbs is every verb the seat serves, in its definition's order: a new copy each call. @@ -30,7 +31,7 @@ func Verbs() []string { // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventHealerActed} + return []string{EventHealerActed, EventAttemptChanged} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -42,6 +43,17 @@ const ( // SubjectHealerActed is where healer-acted is published. const SubjectHealerActed = "mesh.seat.mesh-healers.event.healer-acted" +// StreamAttemptChanged is the stream attempt-changed is kept in. +const StreamAttemptChanged = "SEAT_mesh-healers_attempt-changed" + +// SubjectAttemptChanged is where attempt-changed is published, on mesh.seat.mesh-healers.event.attempt-changed... +func SubjectAttemptChanged(condition, attempt string) string { + return "mesh.seat.mesh-healers.event.attempt-changed." + condition + "." + attempt +} + +// SubjectAttemptChangedAll hears every attempt-changed. +const SubjectAttemptChangedAll = "mesh.seat.mesh-healers.event.attempt-changed.*.*" + const ( StateAttempts = "attempts" StateWould = "would" @@ -165,6 +177,32 @@ const ( HealerActedEventOutcomeEscalated = "escalated" ) +// AttemptChangedEvent is the body of the event attempt-changed. +type AttemptChangedEvent struct { + Act string `json:"act,omitempty"` + Begun *time.Time `json:"begun,omitempty"` + // what the budget counts by: the condition's key unless the healer says another + BudgetKey string `json:"budget-key,omitempty"` + Condition string `json:"condition,omitempty"` + Finished *time.Time `json:"finished,omitempty"` + Healer string `json:"healer,omitempty"` + Kind string `json:"kind,omitempty"` + Outcome string `json:"outcome,omitempty"` + // true when the healer ends the attempt + Removed bool `json:"removed,omitempty"` + Said string `json:"said,omitempty"` + // the end of that key's lifetime, which the keeper drops the attempt at on its own clock + Until *time.Time `json:"until,omitempty"` +} + +// The values of AttemptChangedEvent's outcome. +const ( + AttemptChangedEventOutcomeActing = "acting" + AttemptChangedEventOutcomeActed = "acted" + AttemptChangedEventOutcomeFailed = "failed" + AttemptChangedEventOutcomeEscalated = "escalated" +) + // AttemptsByAttemptValue is one value of the state attempts under the key . type AttemptsByAttemptValue struct { Act string `json:"act"` diff --git a/health-and-repair/go/seats/meshhealers/contract_test.go b/health-and-repair/go/seats/meshhealers/contract_test.go index 957da9d..c0c3e4c 100644 --- a/health-and-repair/go/seats/meshhealers/contract_test.go +++ b/health-and-repair/go/seats/meshhealers/contract_test.go @@ -17,6 +17,10 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ + {name: "an attempt begun, said with its end (design 47 G 665)", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.ace.directory-used-as-found\",\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", wire: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.ace.directory-used-as-found\",\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", + decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "an attempt ended by its healer", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"removed\":true}", wire: "{\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"removed\":true}", + decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "an act a healer would have made, kept from the controller's time (captured)", subject: "", given: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}", wire: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}", decode: func(b []byte) (any, error) { var v WouldByWouldValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } diff --git a/health-and-repair/ts/seats/meshconditions/index.d.ts b/health-and-repair/ts/seats/meshconditions/index.d.ts index 3cebb90..f6e33fa 100644 --- a/health-and-repair/ts/seats/meshconditions/index.d.ts +++ b/health-and-repair/ts/seats/meshconditions/index.d.ts @@ -41,11 +41,11 @@ export declare function conditionsByKeyKey(key: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ export declare function parseConditionsByKeyKey(_key: string): { key: string } | undefined; -/** The key of one value of the state findings under the form "". */ -export declare function findingsByKeyKey(key: string): string; +/** The key of one value of the state findings under the form "..". */ +export declare function findingsByScopeIDKindKey(scope: string, id: string, kind: string): string; -/** The parts of a key of the form "", or undefined for a key of another form. */ -export declare function parseFindingsByKeyKey(_key: string): { key: string } | undefined; +/** The parts of a key of the form "..", or undefined for a key of another form. */ +export declare function parseFindingsByScopeIDKindKey(_key: string): { scope: string; id: string; kind: string } | undefined; /** The key of one value of the state findings-views under the form ".". */ export declare function findingsViewsByObserverNodeKey(observer: string, node: string): string; @@ -154,7 +154,7 @@ export interface Finding { "needs"?: string; /** the module that wrote it */ "observer": string; - /** the module the finding is about, when not the observer */ + /** who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ "owner"?: string; /** the key's last part when it is not the kind */ "ref"?: string; @@ -172,7 +172,7 @@ export interface Finding { "subject": Subject; /** one line */ "summary": string; - /** what it waits on: a person, a part or a call */ + /** what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ "waiting-on"?: string; } @@ -200,6 +200,8 @@ export interface FindingsStated { "asked"?: string; "at": string; "findings": Finding[]; + /** the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580) */ + "kinds"?: string[]; /** the keys the observer cannot judge yet since its start, with their since and bound */ "pending": FindingsStatedPendingItem[]; } @@ -318,40 +320,8 @@ export interface ConditionsByKeyValue { "tried"?: ConditionsByKeyValueTriedItem[]; } -/** is one value of the state findings under the key . */ -export interface FindingsByKeyValue { - "actions"?: Action[]; - "at": string; - /** newest first, at most 10 */ - "evidence"?: Evidence[]; - "explanation"?: string; - "headline"?: string; - /** scope.id.token */ - "key": string; - "kind": string; - "needs"?: string; - /** the module that wrote it */ - "observer": string; - /** the module the finding is about, when not the observer */ - "owner"?: string; - /** the key's last part when it is not the kind */ - "ref"?: string; - "resolved"?: string; - /** self, operator, agent or healer: */ - "resolver"?: string; - /** what of its own saw it last */ - "run"?: string; - "severity": "urgent" | "warning"; - /** the row, probe or event that saw it */ - "source": string; - "subject": Subject; - /** one line */ - "summary": string; - /** layout version, 1 */ - "v": number; - /** what it waits on: a person, a part or a call */ - "waiting-on"?: string; -} +/** is one value of the state findings under the key ... */ +export type FindingsByScopeIDKindValue = Finding; /** the last findings-stated set */ export interface FindingsViewsByObserverNodeValueStated { diff --git a/health-and-repair/ts/seats/meshconditions/index.js b/health-and-repair/ts/seats/meshconditions/index.js index 115101a..27bb6d0 100644 --- a/health-and-repair/ts/seats/meshconditions/index.js +++ b/health-and-repair/ts/seats/meshconditions/index.js @@ -50,19 +50,27 @@ export function parseConditionsByKeyKey(_key) { return { key }; } -/** The key of one value of the state findings under the form "". */ -export function findingsByKeyKey(key) { - return key; +/** The key of one value of the state findings under the form "..". */ +export function findingsByScopeIDKindKey(scope, id, kind) { + return scope + "." + id + "." + kind; } -/** The parts of a key of the form "", or undefined for a key of another form. */ -export function parseFindingsByKeyKey(_key) { +/** The parts of a key of the form "..", or undefined for a key of another form. */ +export function parseFindingsByScopeIDKindKey(_key) { let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const scope = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + const _at2 = _rest.indexOf("."); + if (_at2 <= 0) return undefined; + const id = _rest.slice(0, _at2); + _rest = _rest.slice(_at2 + 1); if (_rest === "") return undefined; - const key = _rest; + const kind = _rest; _rest = ""; if (_rest !== "") return undefined; - return { key }; + return { scope, id, kind }; } /** The key of one value of the state findings-views under the form ".". */ diff --git a/health-and-repair/ts/seats/meshhealers/index.d.ts b/health-and-repair/ts/seats/meshhealers/index.d.ts index 392573b..25f8e11 100644 --- a/health-and-repair/ts/seats/meshhealers/index.d.ts +++ b/health-and-repair/ts/seats/meshhealers/index.d.ts @@ -12,12 +12,19 @@ export declare const verbs: { export declare const events: { readonly healerActed: "healer-acted"; + readonly attemptChanged: "attempt-changed"; }; export declare const family: { readonly name: "mesh-healers.events"; readonly maxAgeDays: 7 }; export declare const healerActedSubject: "mesh.seat.mesh-healers.event.healer-acted"; +export declare const attemptChangedStream: "SEAT_mesh-healers_attempt-changed"; + +export declare function attemptChangedSubject(condition: string, attempt: string): string; + +export declare const attemptChangedSubjectAll: "mesh.seat.mesh-healers.event.attempt-changed.*.*"; + export declare const states: { readonly attempts: "attempts"; readonly would: "would"; @@ -83,6 +90,24 @@ export interface HealerActedEvent { "show"?: string; } +/** is the body of the event attempt-changed. */ +export interface AttemptChangedEvent { + "act"?: string; + "begun"?: string; + /** what the budget counts by: the condition's key unless the healer says another */ + "budget-key"?: string; + "condition"?: string; + "finished"?: string; + "healer"?: string; + "kind"?: string; + "outcome"?: "acting" | "acted" | "failed" | "escalated"; + /** true when the healer ends the attempt */ + "removed"?: boolean; + "said"?: string; + /** the end of that key's lifetime, which the keeper drops the attempt at on its own clock */ + "until"?: string; +} + /** is one value of the state attempts under the key . */ export interface AttemptsByAttemptValue { "act": string; diff --git a/health-and-repair/ts/seats/meshhealers/index.js b/health-and-repair/ts/seats/meshhealers/index.js index 05659bd..6ed9b42 100644 --- a/health-and-repair/ts/seats/meshhealers/index.js +++ b/health-and-repair/ts/seats/meshhealers/index.js @@ -12,12 +12,21 @@ export const verbs = { export const events = { healerActed: "healer-acted", + attemptChanged: "attempt-changed", }; export const family = { name: "mesh-healers.events", maxAgeDays: 7 }; export const healerActedSubject = "mesh.seat.mesh-healers.event.healer-acted"; +export const attemptChangedStream = "SEAT_mesh-healers_attempt-changed"; + +export function attemptChangedSubject(condition, attempt) { + return "mesh.seat.mesh-healers.event.attempt-changed." + condition + "." + attempt; +} + +export const attemptChangedSubjectAll = "mesh.seat.mesh-healers.event.attempt-changed.*.*"; + export const states = { attempts: "attempts", would: "would", diff --git a/operator-and-conversation/go/seats/operatorchannel/contract.go b/operator-and-conversation/go/seats/operatorchannel/contract.go index 4fd1a6d..c27e0c9 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract.go @@ -389,6 +389,8 @@ type HistoryAnswer = map[string]any type NotifyInput struct { // it is over Clear bool `json:"clear,omitempty"` + // send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514) + EveryChannel bool `json:"every-channel,omitempty"` // one or two plain sentences Explanation string `json:"explanation,omitempty"` // plain words @@ -524,6 +526,8 @@ type AsksByAskerIDValue struct { Asker string `json:"asker"` // its asker has been told how it ended AskerTold bool `json:"asker_told,omitempty"` + // when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638) + At string `json:"at,omitempty"` // when it ends unanswered, RFC 3339 Expires string `json:"expires"` // its headline diff --git a/operator-and-conversation/go/seats/operatorchannel/contract_test.go b/operator-and-conversation/go/seats/operatorchannel/contract_test.go index aa1bd95..c389b3e 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract_test.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract_test.go @@ -37,6 +37,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a fourth ask, the asker's oldest held back behind newer ones", subject: "", given: "{\"asker\":\"mesh-delivery-teller\",\"expires\":\"2026-11-11T10:00:00Z\",\"headline\":\"Check failed - merge into main\",\"held-since\":\"2026-11-10T10:30:00Z\",\"key\":\"mesh-delivery-teller.b-1\",\"opened\":\"2026-11-10T10:00:00Z\",\"state\":\"held-back\"}", wire: "{\"asker\":\"mesh-delivery-teller\",\"expires\":\"2026-11-11T10:00:00Z\",\"headline\":\"Check failed - merge into main\",\"held-since\":\"2026-11-10T10:30:00Z\",\"key\":\"mesh-delivery-teller.b-1\",\"opened\":\"2026-11-10T10:00:00Z\",\"state\":\"held-back\"}", decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "an ask the router refused at take-in, closed (design 47 G 570)", subject: "", given: "{\"answer\":\"refused: its expiry passes the bound of its highest option level\",\"asker\":\"nats\",\"asker_told\":true,\"at\":\"2026-11-11T10:00:01Z\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Recreate a bus entry\",\"key\":\"nats.r-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"refused\"}", wire: "{\"answer\":\"refused: its expiry passes the bound of its highest option level\",\"asker\":\"nats\",\"asker_told\":true,\"at\":\"2026-11-11T10:00:01Z\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Recreate a bus entry\",\"key\":\"nats.r-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"refused\"}", + decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "notify asks the message sent on every channel", subject: "", given: "{\"every-channel\":true,\"key\":\"widens.mesh-delivery\",\"severity\":\"warning\",\"subject\":\"mesh-delivery\",\"summary\":\"a change widens what a module may do\"}", wire: "{\"every-channel\":true,\"key\":\"widens.mesh-delivery\",\"severity\":\"warning\",\"subject\":\"mesh-delivery\",\"summary\":\"a change widens what a module may do\"}", + decode: func(b []byte) (any, error) { var v NotifyInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/operator-and-conversation/ts/seats/operatorchannel/index.d.ts b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts index 43690c4..3f91344 100644 --- a/operator-and-conversation/ts/seats/operatorchannel/index.d.ts +++ b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts @@ -305,6 +305,8 @@ export type HistoryAnswer = Record; export interface NotifyInput { /** it is over */ "clear"?: boolean; + /** send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514) */ + "every-channel"?: boolean; /** one or two plain sentences */ "explanation"?: string; /** plain words */ @@ -424,6 +426,8 @@ export interface AsksByAskerIDValue { "asker": string; /** its asker has been told how it ended */ "asker_told"?: boolean; + /** when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638) */ + "at"?: string; /** when it ends unanswered, RFC 3339 */ "expires": string; /** its headline */ diff --git a/ts/seats/meshbroker/index.d.ts b/ts/seats/meshbroker/index.d.ts index f577e50..68e5e83 100644 --- a/ts/seats/meshbroker/index.d.ts +++ b/ts/seats/meshbroker/index.d.ts @@ -183,8 +183,17 @@ export interface ListInput { "module"?: string; } +/** the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661) */ +export interface ListAnswerCaps { + "account-limit-mib"?: number; + "server-limit-mib"?: number; + "sum-mib": number; +} + /** is what list answers. */ export interface ListAnswer { + /** the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661) */ + "caps"?: ListAnswerCaps; /** every entry */ "entries": Held[]; } diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts new file mode 100644 index 0000000..5d98c89 --- /dev/null +++ b/ts/seats/meshrecovery/index.d.ts @@ -0,0 +1,330 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-recovery", defined whole (seats/mesh-recovery/seat.json): Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event. + +export declare const seat: "mesh-recovery"; + +export declare const verbs: { + readonly snapshotKept: "snapshot-kept"; + readonly restoreKept: "restore-kept"; + readonly keptPoints: "kept-points"; + readonly restoreAside: "restore-aside"; + readonly cancel: "cancel"; +}; + +export declare const events: { + readonly ended: "ended"; + readonly restoreStarted: "restore-started"; + readonly restored: "restored"; + readonly setAside: "set-aside"; + readonly asideDiscarded: "aside-discarded"; + readonly pointRemoved: "point-removed"; + readonly expiryEnded: "expiry-ended"; +}; + +export declare const family: { readonly name: "mesh-recovery.events"; readonly maxAgeDays: 7 }; + +export declare const endedStream: "SEAT_mesh-recovery_ended"; + +export declare function endedSubject(module: string, kept: string): string; + +export declare const endedSubjectAll: "mesh.seat.mesh-recovery.event.ended.*.*"; + +export declare const restoreStartedStream: "SEAT_mesh-recovery_restore-started"; + +export declare function restoreStartedSubject(module: string, kept: string): string; + +export declare const restoreStartedSubjectAll: "mesh.seat.mesh-recovery.event.restore-started.*.*"; + +export declare const restoredStream: "SEAT_mesh-recovery_restored"; + +export declare function restoredSubject(module: string, kept: string): string; + +export declare const restoredSubjectAll: "mesh.seat.mesh-recovery.event.restored.*.*"; + +export declare const setAsideStream: "SEAT_mesh-recovery_set-aside"; + +export declare function setAsideSubject(module: string, kept: string): string; + +export declare const setAsideSubjectAll: "mesh.seat.mesh-recovery.event.set-aside.*.*"; + +export declare const asideDiscardedStream: "SEAT_mesh-recovery_aside-discarded"; + +export declare function asideDiscardedSubject(module: string, kept: string): string; + +export declare const asideDiscardedSubjectAll: "mesh.seat.mesh-recovery.event.aside-discarded.*.*"; + +export declare const pointRemovedStream: "SEAT_mesh-recovery_point-removed"; + +export declare function pointRemovedSubject(module: string, kept: string): string; + +export declare const pointRemovedSubjectAll: "mesh.seat.mesh-recovery.event.point-removed.*.*"; + +export declare const expiryEndedStream: "SEAT_mesh-recovery_expiry-ended"; + +export declare const expiryEndedSubject: "mesh.seat.mesh-recovery.event.expiry-ended"; + +/** the live data set aside before a restore: a directory under aside/ in the recovery module's directory, nothing of it on the bus (design 47 G 516) */ +export interface Aside { + /** the directory's name */ + "id": string; + /** the bus name it was live under */ + "name": string; + /** its bytes on disk */ + "size": number; +} + +/** the catch-up of the newer manifest: a tool and its arguments, never text (design 47 G 451, 516, 631) */ +export interface CatchUp { + "arguments"?: Record; + "tool": string; +} + +/** one durable consumer of the kept data and the sequence it had acknowledged */ +export interface Consumer { + "name": string; + "sequence": number; + "stream": string; +} + +/** the digest of one object of a point's bytes */ +export interface Digest { + "digest": string; + "name": string; +} + +/** a restore point: the kept data whole and its consumers' positions, in the recovery module's points directory (design 47 G 516, 560) */ +export interface Point { + /** when it was taken, RFC 3339 */ + "at": string; + "catch-up"?: CatchUp; + "consumers"?: Consumer[]; + /** the digest of each object's bytes, checked before a restore (design 47 G 567) */ + "digests"?: Digest[]; + /** the fingerprint it was 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 bytes */ + "size": number; + /** the point's name, also its directory's */ + "snapshot": string; +} + +/** the act that runs, since when and what it waits on (design 47 G 517, 554) */ +export interface Running { + "act": string; + "since": string; + "step"?: string; + /** what it waits on, when it waits */ + "waits-on"?: string; +} + +/** is what snapshot-kept takes. */ +export interface SnapshotKeptInput { + "catch-up"?: CatchUp; + /** the fingerprint the restore point is taken before, or reverted from */ + "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, which the hand-act log keeps */ + "why": string; +} + +/** is what snapshot-kept answers. */ +export interface SnapshotKeptAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what restore-kept takes. */ +export interface RestoreKeptInput { + /** the fingerprint the restore point is taken before, or reverted from */ + "fingerprint": string; + /** its form, the number the holder raises when it changes how it writes it (0 when undeclared) */ + "form": number; + /** ask the backup holder for the points directory when the point is missing there (design 47 G 516) */ + "from-backup"?: boolean; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** the restore point's name */ + "snapshot"?: string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what restore-kept answers. */ +export interface RestoreKeptAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what kept-points takes. */ +export interface KeptPointsInput { + /** one kept data (optional) */ + "kept"?: string; + /** one module (optional) */ + "module"?: string; +} + +/** is what kept-points answers. */ +export interface KeptPointsAnswer { + "asides": Aside[]; + "points": Point[]; + "running"?: Running; +} + +/** is what restore-aside takes. */ +export interface RestoreAsideInput { + /** the aside's id */ + "id": string; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what restore-aside answers. */ +export interface RestoreAsideAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what cancel takes. */ +export interface CancelInput { + /** the act's id */ + "act": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what cancel answers. */ +export interface CancelAnswer { + /** the act ended cancelled */ + "cancelled"?: boolean; + /** why not, naming the step an act has begun; set alone */ + "error"?: string; +} + +/** is the body of the event ended. */ +export interface EndedEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + "catch-up"?: CatchUp; + "consumers"?: Consumer[]; + "digests"?: Digest[]; + /** when failed */ + "error"?: string; + "fingerprint"?: string; + "form"?: number; + "kept": string; + "module": string; + /** how the act ended */ + "outcome": "done" | "failed"; + "size"?: number; + "snapshot"?: string; +} + +/** is the body of the event restore-started. */ +export interface RestoreStartedEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + "fingerprint"?: string; + "form"?: number; + "kept": string; + "module": string; + "snapshot"?: string; +} + +/** is the body of the event restored. */ +export interface RestoredEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + "aside"?: Aside; + /** when it was said, RFC 3339 */ + "at": string; + "error"?: string; + "fingerprint"?: string; + "form"?: number; + "kept": string; + /** the point is not in the recovery module's directory */ + "missing"?: boolean; + "module": string; + /** how the act ended */ + "outcome": "done" | "failed"; + "snapshot"?: string; +} + +/** is the body of the event set-aside. */ +export interface SetAsideEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + "id": string; + "name": string; + "size": number; +} + +/** is the body of the event aside-discarded. */ +export interface AsideDiscardedEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + "id": string; + "name": string; + "size": number; +} + +/** is the body of the event point-removed. */ +export interface PointRemovedEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + "fingerprint"?: string; + "form"?: number; + "kept": string; + "module": string; + "snapshot"?: string; +} + +/** is the body of the event expiry-ended. */ +export interface ExpiryEndedEvent { + /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ + "act": string; + /** when it was said, RFC 3339 */ + "at": string; + /** the number of points the run removed, 0 included */ + "removed": number; +} + diff --git a/ts/seats/meshrecovery/index.js b/ts/seats/meshrecovery/index.js new file mode 100644 index 0000000..2ceb51f --- /dev/null +++ b/ts/seats/meshrecovery/index.js @@ -0,0 +1,78 @@ +// Code generated by seatgen from the seat definitions; DO NOT EDIT. + +// The contract of the seat "mesh-recovery", defined whole (seats/mesh-recovery/seat.json): Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event. + +export const seat = "mesh-recovery"; + +export const verbs = { + snapshotKept: "snapshot-kept", + restoreKept: "restore-kept", + keptPoints: "kept-points", + restoreAside: "restore-aside", + cancel: "cancel", +}; + +export const events = { + ended: "ended", + restoreStarted: "restore-started", + restored: "restored", + setAside: "set-aside", + asideDiscarded: "aside-discarded", + pointRemoved: "point-removed", + expiryEnded: "expiry-ended", +}; + +export const family = { name: "mesh-recovery.events", maxAgeDays: 7 }; + +export const endedStream = "SEAT_mesh-recovery_ended"; + +export function endedSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.ended." + module + "." + kept; +} + +export const endedSubjectAll = "mesh.seat.mesh-recovery.event.ended.*.*"; + +export const restoreStartedStream = "SEAT_mesh-recovery_restore-started"; + +export function restoreStartedSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.restore-started." + module + "." + kept; +} + +export const restoreStartedSubjectAll = "mesh.seat.mesh-recovery.event.restore-started.*.*"; + +export const restoredStream = "SEAT_mesh-recovery_restored"; + +export function restoredSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.restored." + module + "." + kept; +} + +export const restoredSubjectAll = "mesh.seat.mesh-recovery.event.restored.*.*"; + +export const setAsideStream = "SEAT_mesh-recovery_set-aside"; + +export function setAsideSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.set-aside." + module + "." + kept; +} + +export const setAsideSubjectAll = "mesh.seat.mesh-recovery.event.set-aside.*.*"; + +export const asideDiscardedStream = "SEAT_mesh-recovery_aside-discarded"; + +export function asideDiscardedSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.aside-discarded." + module + "." + kept; +} + +export const asideDiscardedSubjectAll = "mesh.seat.mesh-recovery.event.aside-discarded.*.*"; + +export const pointRemovedStream = "SEAT_mesh-recovery_point-removed"; + +export function pointRemovedSubject(module, kept) { + return "mesh.seat.mesh-recovery.event.point-removed." + module + "." + kept; +} + +export const pointRemovedSubjectAll = "mesh.seat.mesh-recovery.event.point-removed.*.*"; + +export const expiryEndedStream = "SEAT_mesh-recovery_expiry-ended"; + +export const expiryEndedSubject = "mesh.seat.mesh-recovery.event.expiry-ended"; + diff --git a/ts/seats/meshrecovery/package-lock.json b/ts/seats/meshrecovery/package-lock.json new file mode 100644 index 0000000..f8e5dbc --- /dev/null +++ b/ts/seats/meshrecovery/package-lock.json @@ -0,0 +1,12 @@ +{ + "lockfileVersion": 3, + "name": "@novox/mesh-contracts-mesh-recovery", + "packages": { + "": { + "name": "@novox/mesh-contracts-mesh-recovery", + "version": "0.1.0" + } + }, + "requires": true, + "version": "0.1.0" +} diff --git a/ts/seats/meshrecovery/package.json b/ts/seats/meshrecovery/package.json new file mode 100644 index 0000000..7978a6c --- /dev/null +++ b/ts/seats/meshrecovery/package.json @@ -0,0 +1,18 @@ +{ + "description": "The contract of the seat mesh-recovery, generated from its definition.", + "exports": { + ".": { + "default": "./index.js", + "types": "./index.d.ts" + } + }, + "files": [ + "index.js", + "index.d.ts", + "parts" + ], + "name": "@novox/mesh-contracts-mesh-recovery", + "type": "module", + "types": "./index.d.ts", + "version": "0.1.0" +} diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index 78d31e4..61262b3 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -18,6 +18,8 @@ export declare const verbs: { readonly manifestReads: "manifest-reads"; readonly seatList: "seat-list"; readonly seatListAgain: "seat-list-again"; + readonly firstViews: "first-views"; + readonly firstViewAgain: "first-view-again"; readonly processBuilds: "process-builds"; }; @@ -28,7 +30,8 @@ export declare const events: { readonly manifestReadsChanged: "manifest-reads-changed"; readonly composed: "composed"; readonly running: "running"; - readonly capabilitiesChanged: "capabilities-changed"; + readonly waitHeld: "wait-held"; + readonly waitEnded: "wait-ended"; }; export declare const family: { readonly name: "node-engine.events"; readonly maxAgeDays: 7 }; @@ -51,9 +54,17 @@ export declare function runningSubject(node: string, module: string): string; export declare const runningSubjectAll: "mesh.seat.node-engine.event.running.*.*"; -export declare function capabilitiesChangedSubject(node: string): string; +export declare const waitHeldStream: "SEAT_node-engine_wait-held"; -export declare const capabilitiesChangedSubjectAll: "mesh.seat.node-engine.event.capabilities-changed.*"; +export declare function waitHeldSubject(node: string, module: string): string; + +export declare const waitHeldSubjectAll: "mesh.seat.node-engine.event.wait-held.*.*"; + +export declare const waitEndedStream: "SEAT_node-engine_wait-ended"; + +export declare function waitEndedSubject(node: string, module: string): string; + +export declare const waitEndedSubjectAll: "mesh.seat.node-engine.event.wait-ended.*.*"; export declare const states: { readonly have: "have"; @@ -267,18 +278,6 @@ export interface CandidateRefusal { "why": string; } -/** a node's capabilities changed, which the assigner places by */ -export interface CapabilitiesChanged { - /** when, RFC 3339 */ - "at": string; - /** its capabilities now */ - "capabilities": string[]; - /** the node */ - "node": string; - /** the layout's version */ - "v": number; -} - /** an entry composed on a node (design 47 *What each step says*) */ export interface Composed { /** when, RFC 3339 */ @@ -575,19 +574,21 @@ export interface RootVerdict { "why": string; } -/** a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit */ +/** a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit */ export interface Running { - /** when it was seen running healthy, RFC 3339 */ + /** when it was said, RFC 3339 */ "at": string; /** the fingerprint of the build it runs; none with stopped */ "fingerprint"?: string; + /** the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat */ + "healthy"?: boolean | null; /** the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half */ "manifest"?: string; /** the module */ "module": string; /** the node */ "node": string; - /** true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there */ + /** true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there */ "stopped"?: boolean; /** the layout's version */ "v": number; @@ -669,6 +670,31 @@ export interface UserListWritten { "wanted": string; } +/** a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560) */ +export interface Wait { + /** in the have: the act the recovery module answered accepted with (design 47 G 560) */ + "act"?: string; + /** in the have: the time of the first ask of the recovery module for this wait (design 47 G 560) */ + "ask-at"?: string; + /** a duration such as 30m */ + "bound"?: string; + /** the time the bound counts from (design 47 G 266, 269, 498) */ + "clock-from"?: string; + /** the node waited on: the build node for a kept build; the subject's is the node that says it */ + "node"?: string; + /** what it waits on */ + "on"?: string; + /** the seat holding the wait: node-engine */ + "owner"?: string; + /** why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499) */ + "reason"?: string; + "since": string; + /** compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541) */ + "step": "compose" | "kept-build"; + /** the wait said in words */ + "words"?: string; +} + /** is what hand-over takes. */ export interface HandOverInput { /** the directory's absolute path, as the engine states it */ @@ -991,6 +1017,50 @@ export interface SeatListAgainInput { /** is what seat-list-again answers. */ export type SeatListAgainAnswer = SeatList; +/** is what first-views takes. */ +export interface FirstViewsInput { +} + +/** is what first-views answers. */ +export interface FirstViewsAnswer { + /** one status per owner and state followed, as mesh-sdk's views runtime keeps it */ + "first-views": Record[]; +} + +/** is what first-view-again takes. */ +export interface FirstViewAgainInput { + /** the owner module, as first-views names it */ + "owner": string; + /** the owner's state, as first-views names it */ + "state": string; + /** why it is asked again, in plain words */ + "why": string; +} + +/** the hand ask written */ +export interface FirstViewAgainAnswerAsked { + /** when it was asked, RFC 3339 */ + "at": string; + /** the caller the runtime proved */ + "by": string; + /** the owner module */ + "owner": string; + /** the owner's state */ + "state": string; + /** the layout's version */ + "v": number; + /** why it was asked again */ + "why": string; +} + +/** is what first-view-again answers. */ +export interface FirstViewAgainAnswer { + /** the hand ask written */ + "asked": FirstViewAgainAnswerAsked; + /** the verb that reads the status, first-views */ + "read": string; +} + /** is what process-builds takes. */ export interface ProcessBuildsInput { /** only this module's processes */ @@ -1018,8 +1088,11 @@ export type ComposedEvent = Composed; /** is the body of the event running. */ export type RunningEvent = Running; -/** is the body of the event capabilities-changed. */ -export type CapabilitiesChangedEvent = CapabilitiesChanged; +/** is the body of the event wait-held. */ +export type WaitHeldEvent = Wait; + +/** is the body of the event wait-ended. */ +export type WaitEndedEvent = Wait; /** is one value of the state have under the key .. */ export interface HaveByNodeModuleValue { @@ -1047,6 +1120,7 @@ export interface HaveByNodeModuleValue { "sealed-at"?: Record; "user-list"?: UserListWritten; "v": number; + "wait"?: Wait; /** in phase waiting-yes, the digest of the composition that waits */ "waits"?: string; } diff --git a/ts/seats/nodeengine/index.js b/ts/seats/nodeengine/index.js index 1cb7831..ce9c2e2 100644 --- a/ts/seats/nodeengine/index.js +++ b/ts/seats/nodeengine/index.js @@ -18,6 +18,8 @@ export const verbs = { manifestReads: "manifest-reads", seatList: "seat-list", seatListAgain: "seat-list-again", + firstViews: "first-views", + firstViewAgain: "first-view-again", processBuilds: "process-builds", }; @@ -28,7 +30,8 @@ export const events = { manifestReadsChanged: "manifest-reads-changed", composed: "composed", running: "running", - capabilitiesChanged: "capabilities-changed", + waitHeld: "wait-held", + waitEnded: "wait-ended", }; export const family = { name: "node-engine.events", maxAgeDays: 7 }; @@ -63,11 +66,21 @@ export function runningSubject(node, module) { export const runningSubjectAll = "mesh.seat.node-engine.event.running.*.*"; -export function capabilitiesChangedSubject(node) { - return "mesh.seat.node-engine.event.capabilities-changed." + node; +export const waitHeldStream = "SEAT_node-engine_wait-held"; + +export function waitHeldSubject(node, module) { + return "mesh.seat.node-engine.event.wait-held." + node + "." + module; } -export const capabilitiesChangedSubjectAll = "mesh.seat.node-engine.event.capabilities-changed.*"; +export const waitHeldSubjectAll = "mesh.seat.node-engine.event.wait-held.*.*"; + +export const waitEndedStream = "SEAT_node-engine_wait-ended"; + +export function waitEndedSubject(node, module) { + return "mesh.seat.node-engine.event.wait-ended." + node + "." + module; +} + +export const waitEndedSubjectAll = "mesh.seat.node-engine.event.wait-ended.*.*"; export const states = { have: "have", From b2cc72b4a3e3123715b0b9824fa72e8d4633ad9b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:43:22 +0100 Subject: [PATCH 38/62] K22 (finding helpers gone): meshconditionsclient keeps what concerns conditions, and heard builds the seat's generated finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The helpers CheckFinding, FindingFor, FindingWriter, FindingState, FindingVersion, Observation, EncodeFinding, DecodeFinding, Says, FindingBucket, FindingsBucket, Raise, Clear and CallUnanswered go; mesh-sdk's writer is the one writer and checks. Importers outside this repository move in G's change (named in the line). Builds: design 47 G §689 (§461, §503, §640, §660) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../meshconditionsclient/callunanswered.go | 11 ++ .../go/clients/meshconditionsclient/client.go | 78 +------- .../meshconditionsclient/client_test.go | 153 +--------------- .../meshconditionsclient/heard/heard.go | 18 +- .../meshconditionsclient/heard/heard_test.go | 7 + .../meshconditionsclient/observation.go | 168 ------------------ .../testdata/finding_full.json | 1 - .../testdata/finding_minimal.json | 1 - 8 files changed, 31 insertions(+), 406 deletions(-) create mode 100644 health-and-repair/go/clients/meshconditionsclient/callunanswered.go delete mode 100644 health-and-repair/go/clients/meshconditionsclient/observation.go delete mode 100644 health-and-repair/go/clients/meshconditionsclient/testdata/finding_full.json delete mode 100644 health-and-repair/go/clients/meshconditionsclient/testdata/finding_minimal.json diff --git a/health-and-repair/go/clients/meshconditionsclient/callunanswered.go b/health-and-repair/go/clients/meshconditionsclient/callunanswered.go new file mode 100644 index 0000000..e3520c1 --- /dev/null +++ b/health-and-repair/go/clients/meshconditionsclient/callunanswered.go @@ -0,0 +1,11 @@ +package meshconditionsclient + +import "time" + +// KindCallUnanswered is the kind of a kept call still unanswered past CallUnansweredAfter (novox/hq ADR 0668 §3, issue +// 1966): a call whose answer the caller keeps, asked again through every transport fault, that no answer has ended. The +// caller writes it into its own findings, keeps the wait, and clears it when the call is answered. +const KindCallUnanswered = "call-unanswered" + +// CallUnansweredAfter is how long a kept call stays unanswered before it is a finding (ADR 0668 §3; ADR 0564 §2's bound). +const CallUnansweredAfter = 5 * time.Minute diff --git a/health-and-repair/go/clients/meshconditionsclient/client.go b/health-and-repair/go/clients/meshconditionsclient/client.go index 2931dc8..c2fbc08 100644 --- a/health-and-repair/go/clients/meshconditionsclient/client.go +++ b/health-and-repair/go/clients/meshconditionsclient/client.go @@ -1,17 +1,15 @@ // Package meshconditionsclient is the logic every observer, healer and reader of conditions shares over the seat -// mesh-conditions (novox/hq ADR 0564, ADR 0634 §4): how a finding's key is made and checked, the scopes and the bounds, +// mesh-conditions (novox/hq ADR 0564, ADR 0634 §4): how a finding's key is made, the scopes and the bounds, // the order a person reads conditions in, and the answers a notification offers. The layouts are the seat's contract's. package meshconditionsclient import ( - "fmt" "regexp" "sort" "strings" "time" seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions" - "git.novox.be/novox/mesh-sdk/go/views" ) // The two severities, how soon the operator is needed. @@ -111,39 +109,6 @@ func SilenceAction(key string) seat.Action { Arguments: map[string]string{"key": key, "for": "7d", "why": "", "cause": CauseOperatorAnswer}} } -// CheckFinding refuses a finding the keeper could not make a condition of, naming why. -func CheckFinding(f seat.FindingsByKeyValue) error { - known := false - for _, s := range Scopes { - known = known || s == f.Subject.Scope - } - token := f.Ref - if token == "" { - token = f.Kind - } - switch { - case !known: - return fmt.Errorf("health: a finding's scope is one of %s, not %q", strings.Join(Scopes, ", "), f.Subject.Scope) - case strings.TrimSpace(f.Subject.ID) == "": - return fmt.Errorf("health: a %s finding names what it is about", f.Subject.Scope) - case strings.TrimSpace(f.Kind) == "": - return fmt.Errorf("health: the finding %s has no kind", f.Key) - case f.Key != Key(f.Subject.Scope, f.Subject.ID, token): - return fmt.Errorf("health: the finding's key %q is not %q, its scope, id and kind", f.Key, Key(f.Subject.Scope, f.Subject.ID, token)) - case f.Severity != Urgent && f.Severity != Warning: - return fmt.Errorf("health: the finding %s is urgent or a warning, not %q", f.Key, f.Severity) - case strings.TrimSpace(f.Summary) == "": - return fmt.Errorf("health: the finding %s says nothing", f.Key) - case strings.TrimSpace(f.Source) == "": - return fmt.Errorf("health: the finding %s does not say what saw it", f.Key) - case strings.TrimSpace(f.Observer) == "": - return fmt.Errorf("health: the finding %s does not name its observer", f.Key) - case len(f.Evidence) > KeptEvidence: - return fmt.Errorf("health: the finding %s keeps %d observations, at most %d", f.Key, len(f.Evidence), KeptEvidence) - } - return nil -} - // Order sorts conditions as a person reads them: urgent first, then oldest raised, then by key. func Order(list []seat.ConditionsByKeyValue) { raised := func(c seat.ConditionsByKeyValue) time.Time { return c.Raised } @@ -171,44 +136,3 @@ func SilencedAt(c seat.ConditionsByKeyValue, now time.Time) bool { func Escalated(c seat.ConditionsByKeyValue) bool { return c.Resolver == ResolverOperator && len(c.Tried) > 0 } - -// FindingVersion is the layout version of a finding's value. -const FindingVersion = 1 - -// FindingState is a part's own state `findings`, where the condition keeper reads what a part saw: the runtime's kept -// state (mesh-sdk's KeptState) satisfies it. -type FindingState interface { - Put(key string, value any) (uint64, error) - Delete(key string) error -} - -// FindingWriter writes and clears a part's findings of a module in its own state `findings`, in this seat's layout; it -// is mesh-sdk's views.FindingWriter. A finding is a warning about the module its ID names, and is checked -// (CheckFinding) before it is written. -type FindingWriter struct{ State FindingState } - -var _ views.FindingWriter = FindingWriter{} - -// FindingFor is the value and key of the seat's finding for f. -func FindingFor(f views.Finding) seat.FindingsByKeyValue { - at := f.At.UTC() - return seat.FindingsByKeyValue{V: FindingVersion, Key: Key(ScopeModule, f.ID, f.Kind), Kind: f.Kind, - Subject: seat.Subject{Scope: ScopeModule, ID: f.ID}, Severity: Warning, Summary: f.Summary, Headline: f.Headline, - Explanation: f.Explanation, Evidence: []seat.Evidence{{At: at, Said: f.Summary}}, Source: f.Observer + "." + f.Kind, - Observer: f.Observer, At: at} -} - -// Put writes the finding. -func (w FindingWriter) Put(f views.Finding) error { - v := FindingFor(f) - if err := CheckFinding(v); err != nil { - return err - } - _, err := w.State.Put(v.Key, v) - return err -} - -// Delete clears the finding. -func (w FindingWriter) Delete(f views.Finding) error { - return w.State.Delete(Key(ScopeModule, f.ID, f.Kind)) -} diff --git a/health-and-repair/go/clients/meshconditionsclient/client_test.go b/health-and-repair/go/clients/meshconditionsclient/client_test.go index f351fd2..f377f6d 100644 --- a/health-and-repair/go/clients/meshconditionsclient/client_test.go +++ b/health-and-repair/go/clients/meshconditionsclient/client_test.go @@ -1,14 +1,10 @@ package meshconditionsclient import ( - "os" - "reflect" - "strings" "testing" "time" seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions" - "git.novox.be/novox/mesh-sdk/go/views" ) // ADR 0564 clause 3: the key rule, the checks of a finding, the order and the silence a person reads conditions by. @@ -19,33 +15,8 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) { if k := Key("call", "a b", ""); k != "call.a_b._" { t.Errorf("an unsafe part and an empty token: %s", k) } - // Issue 1966, ADR 0668 §3: a kept call unanswered is a finding the keeper can make a condition of, keyed by what waits. - o := CallUnanswered("ace", "seat:node-engine.manifest-reads", "ace", "no responders", "enginereads", time.Unix(0, 0)) - if f := o.Finding("mesh-delivery-assigner", "r1", time.Unix(300, 0)); o.Key() != "call.ace.call-unanswered" || CheckFinding(f) != nil { - t.Errorf("a call unanswered: key %s, %v", o.Key(), CheckFinding(f)) - } - good := seat.FindingsByKeyValue{Key: "machine.g14.silent", Kind: "silent", Severity: Warning, Summary: "x", Source: "S1", - Observer: "mesh-delivery-watchman", Subject: seat.Subject{Scope: ScopeMachine, ID: "g14"}} - for _, c := range []struct { - name string - change func(*seat.FindingsByKeyValue) - refuse string - }{ - {"a good finding", func(*seat.FindingsByKeyValue) {}, ""}, - {"an unknown scope", func(f *seat.FindingsByKeyValue) { f.Subject.Scope = "moon" }, "scope is one of"}, - {"a key that is not its subject's", func(f *seat.FindingsByKeyValue) { f.Key = "machine.g14.other" }, "is not"}, - {"a reference as the key's last part", func(f *seat.FindingsByKeyValue) { f.Ref = "gone"; f.Key = "machine.g14.gone" }, ""}, - {"no summary", func(f *seat.FindingsByKeyValue) { f.Summary = " " }, "says nothing"}, - {"no observer", func(f *seat.FindingsByKeyValue) { f.Observer = "" }, "observer"}, - {"a severity of neither kind", func(f *seat.FindingsByKeyValue) { f.Severity = "info" }, "urgent or a warning"}, - {"too much evidence", func(f *seat.FindingsByKeyValue) { f.Evidence = make([]seat.Evidence, KeptEvidence+1) }, "keeps 11"}, - } { - f := good - c.change(&f) - err := CheckFinding(f) - if (c.refuse == "") != (err == nil) || (err != nil && !strings.Contains(err.Error(), c.refuse)) { - t.Errorf("%s: %v", c.name, err) - } + if KindCallUnanswered != "call-unanswered" || CallUnansweredAfter != 5*time.Minute { + t.Error("the kept call's finding kind and bound") } list := []seat.ConditionsByKeyValue{ {Key: "b", Severity: Warning, Raised: when("2026-11-01T10:00:00Z")}, @@ -69,44 +40,6 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) { } } -type fakeFindings struct { - put map[string]any - deleted []string -} - -func (f *fakeFindings) Put(key string, value any) (uint64, error) { - if f.put == nil { - f.put = map[string]any{} - } - f.put[key] = value - return 1, nil -} -func (f *fakeFindings) Delete(key string) error { f.deleted = append(f.deleted, key); return nil } - -func TestTheFindingWriterWritesAndClearsAModulesFindingInTheSeatsLayout(t *testing.T) { - state := &fakeFindings{} - var w views.FindingWriter = FindingWriter{State: state} - f := views.Finding{Observer: "mesh-config", Kind: "unanswered", ID: "mesh-config.mesh-vault.secrets", Summary: "no first view", - Headline: "waits", Explanation: "look", At: time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC)} - if err := w.Put(f); err != nil { - t.Fatal(err) - } - key := "module.mesh-config.mesh-vault.secrets.unanswered" - v, ok := state.put[key].(seat.FindingsByKeyValue) - if !ok || v.Key != key || v.Severity != Warning || v.Source != "mesh-config.unanswered" || v.Subject.Scope != ScopeModule || len(v.Evidence) != 1 { - t.Fatalf("written %#v", state.put) - } - if err := CheckFinding(v); err != nil { - t.Error(err) - } - if err := w.Delete(f); err != nil || len(state.deleted) != 1 || state.deleted[0] != key { - t.Errorf("deleted %v: %v", state.deleted, err) - } - if err := w.Put(views.Finding{Observer: "x", Kind: "k", ID: "i"}); err == nil { - t.Error("a finding that says nothing was written") - } -} - func when(s string) time.Time { t, err := time.Parse(time.RFC3339Nano, s) if err != nil { @@ -116,85 +49,3 @@ func when(s string) time.Time { } func ptr(t time.Time) *time.Time { return &t } - -type fakeBucket struct { - kept map[string][]byte - puts, dels int -} - -func (b *fakeBucket) Get(key string) ([]byte, bool, error) { v, ok := b.kept[key]; return v, ok, nil } -func (b *fakeBucket) Put(key string, v []byte) error { - if b.kept == nil { - b.kept = map[string][]byte{} - } - b.kept[key] = v - b.puts++ - return nil -} -func (b *fakeBucket) Delete(key string) error { delete(b.kept, key); b.dels++; return nil } - -// The goldens are what mesh-sdk's go/health EncodeFinding wrote for the same findings: the helpers write the same -// values, read by the seat's strict decoder. -func TestAnObservationIsWrittenAsMeshSDKsHealthWroteItsFinding(t *testing.T) { - at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC) - for _, c := range []struct { - golden string - o Observation - run string - }{ - {"finding_full.json", Observation{Scope: ScopeMachine, ID: "g14", Kind: "silent-kind", Ref: "silent", Machine: "g14", Also: []string{"ace"}, - Severity: Urgent, Summary: "g14 is silent", Said: "no pulse", Headline: "g14 is silent", Explanation: "It said nothing.", - Resolved: "It speaks.", Needs: "look", Source: "S1", Resolver: "operator"}, "r1"}, - {"finding_minimal.json", Observation{Scope: ScopeModule, ID: "nats.g14", Kind: "build-failed", Summary: "failed", - Source: "builder.build-failed"}, ""}, - } { - raw, err := os.ReadFile("testdata/" + c.golden) - if err != nil { - t.Fatal(err) - } - want, err := seat.DecodeFindingsByKeyValue(raw) - if err != nil { - t.Fatalf("%s: %v", c.golden, err) - } - observer := want.Observer - got, err := EncodeFinding(c.o.Finding(observer, c.run, at)) - if err != nil { - t.Fatalf("%s: %v", c.golden, err) - } - have, err := seat.DecodeFindingsByKeyValue(got) - if err != nil || !reflect.DeepEqual(have, want) { - t.Errorf("%s: wrote %s, want %s (%v)", c.golden, got, raw, err) - } - if back, err := DecodeFinding(raw); err != nil || !reflect.DeepEqual(back, want) { - t.Errorf("%s: read back %v", c.golden, err) - } - } -} - -func TestRaiseWritesWhenTheWordsChangeAndClearDeletesWhatIsThere(t *testing.T) { - b := &fakeBucket{} - o := Observation{Scope: ScopeModule, ID: "m", Kind: "k", Summary: "one", Source: "x.k"} - at := when("2026-11-05T12:00:00Z") - if w, err := Raise(b, "obs", "", o, at); err != nil || !w { - t.Fatalf("first: %v %v", w, err) - } - if w, err := Raise(b, "obs", "r2", o, at.Add(time.Hour)); err != nil || w || b.puts != 1 { - t.Fatalf("the same words later: wrote %v, %d puts, %v", w, b.puts, err) - } - o.Summary = "two" - if w, err := Raise(b, "obs", "", o, at); err != nil || !w || b.puts != 2 { - t.Fatalf("changed: %v %d %v", w, b.puts, err) - } - if _, err := Raise(b, "obs", "", Observation{Scope: "moon", ID: "m", Kind: "k"}, at); err == nil || b.puts != 2 { - t.Errorf("a finding the keeper cannot use was written: %v", err) - } - if c, err := Clear(b, ScopeModule, "m", "k"); err != nil || !c || b.dels != 1 { - t.Fatalf("clear: %v %v %d", c, err, b.dels) - } - if c, err := Clear(b, ScopeModule, "m", "k"); err != nil || c || b.dels != 1 { - t.Errorf("clearing what is not there: %v %v %d", c, err, b.dels) - } - if FindingsBucket("obs") != "obs_findings" { - t.Error(FindingsBucket("obs")) - } -} diff --git a/health-and-repair/go/clients/meshconditionsclient/heard/heard.go b/health-and-repair/go/clients/meshconditionsclient/heard/heard.go index e00d535..da9fbca 100644 --- a/health-and-repair/go/clients/meshconditionsclient/heard/heard.go +++ b/health-and-repair/go/clients/meshconditionsclient/heard/heard.go @@ -13,7 +13,7 @@ import ( "time" "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient" - "git.novox.be/novox/mesh-sdk/go/views" + seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions" ) // Kind is the finding's kind. @@ -43,16 +43,18 @@ func Words(observer, family, consequence string, why error) (summary, headline, return summary, headline, explanation } -// Finding is observer's finding that it does not hear family, in the layout of the seat mesh-conditions' state findings. +// Finding is observer's finding that it does not hear family, as the seat mesh-conditions' generated type +// (design 47 G 689): its key and its value. The check of its rules is mesh-sdk's writer's, which refuses a finding +// breaking them before it writes. func Finding(observer, family, consequence string, why error, at time.Time) (string, []byte, error) { summary, headline, explanation := Words(observer, family, consequence, why) - v := meshconditionsclient.FindingFor(views.Finding{Observer: observer, Kind: Kind, ID: ID(observer, family), Summary: summary, - Headline: headline, Explanation: explanation, At: at}) - if err := meshconditionsclient.CheckFinding(v); err != nil { - return v.Key, nil, err - } + at = at.UTC() + v := seat.Finding{Scope: meshconditionsclient.ScopeModule, ID: ID(observer, family), Kind: Kind, + Subject: seat.Subject{Scope: meshconditionsclient.ScopeModule, ID: ID(observer, family)}, + Severity: meshconditionsclient.Warning, Summary: summary, Headline: headline, Explanation: explanation, + Evidence: []seat.Evidence{{At: at, Said: summary}}, Source: observer + "." + Kind, Observer: observer, At: at, Since: at} value, err := json.Marshal(v) - return v.Key, value, err + return Key(observer, family), value, err } // Writer writes and deletes the finding in the observer's findings state. Put or Delete nil writes nothing, said in the diff --git a/health-and-repair/go/clients/meshconditionsclient/heard/heard_test.go b/health-and-repair/go/clients/meshconditionsclient/heard/heard_test.go index cc9b69a..9beb0e9 100644 --- a/health-and-repair/go/clients/meshconditionsclient/heard/heard_test.go +++ b/health-and-repair/go/clients/meshconditionsclient/heard/heard_test.go @@ -5,6 +5,8 @@ import ( "strings" "testing" "time" + + seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions" ) // A consumer that does not bind writes the finding, with why, under the observer's findings key; the one that binds @@ -22,6 +24,11 @@ func TestBindWritesTheFindingUntilTheConsumerBinds(t *testing.T) { if err := w.Bind("placement", "the first view is the only picture", func() error { return errors.New("no consumer") }); err == nil { t.Fatal("a failed bind was not answered") } + // Design 47 G 689: the value is the seat's generated finding, read by its strict decoder, key and subject by the rule. + if f, err := seat.DecodeFindingsByScopeIDKindValue(puts[key]); err != nil || f.Observer != "mesh-x" || f.Kind != Kind || + f.Scope != "module" || f.ID != "mesh-x.placement" || f.Subject.ID != f.ID || f.Severity != "warning" || f.Source == "" { + t.Errorf("the finding is not the seat's generated one: %+v (%v)", f, err) + } if v := string(puts[key]); !strings.Contains(v, "no consumer") || !strings.Contains(v, "mesh-x does not hear placement") { t.Errorf("the finding is %q", v) } diff --git a/health-and-repair/go/clients/meshconditionsclient/observation.go b/health-and-repair/go/clients/meshconditionsclient/observation.go deleted file mode 100644 index 9af47d6..0000000 --- a/health-and-repair/go/clients/meshconditionsclient/observation.go +++ /dev/null @@ -1,168 +0,0 @@ -package meshconditionsclient - -import ( - "encoding/json" - "fmt" - "time" - - seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions" -) - -// What an observer says it sees wrong, raised and cleared as a finding in its own state `findings` (novox/hq ADR 0564 -// clause 2, ADR 0634 §4): one write shared by every observer (the self-check, the healers, the watchman, the builder, -// the indexer, the node-engine), in this seat's layout. The condition keeper raises and clears the conditions from them. - -// FindingsState is the name of an observer's state of findings. -const FindingsState = "findings" - -// FindingsBucket is the bucket of an observer's findings, `_findings`. -func FindingsBucket(observer string) string { return observer + "_" + FindingsState } - -// Observation is one thing an observer sees wrong now: what it is about (Scope, ID, Machine, Also), which kind of fault -// (Kind; Ref when the key's last part is not the kind), and its words. -type Observation struct { - Scope, ID, Kind, Ref, Machine string - Also []string - // Severity is Urgent or Warning; Warning when empty. - Severity string - // Summary is one line; Said the one observation kept as evidence (the summary when empty). - Summary, Said string - Headline, Explanation, Resolved, Needs string - // Source is the row, probe or event that saw it. - Source string - // Resolver is who resolves it, self when empty. - Resolver string - Actions []seat.Action - // Since is when the finding is stamped; the zero value leaves it to the caller's moment. - Since time.Time -} - -// Key is the finding's key: `..`, the token Ref or else Kind. -func (o Observation) Key() string { - token := o.Ref - if token == "" { - token = o.Kind - } - return Key(o.Scope, o.ID, token) -} - -// Finding is the observation as the seat's finding written by observer in run, at the moment at. -func (o Observation) Finding(observer, run string, at time.Time) seat.FindingsByKeyValue { - at = at.UTC() - said := o.Said - if said == "" { - said = o.Summary - } - sev := o.Severity - if sev == "" { - sev = Warning - } - f := seat.FindingsByKeyValue{V: FindingVersion, Key: o.Key(), Kind: o.Kind, - Subject: seat.Subject{Scope: o.Scope, ID: o.ID, Machine: o.Machine, Also: o.Also}, - Severity: sev, Summary: o.Summary, Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved, - Needs: o.Needs, Actions: o.Actions, Evidence: []seat.Evidence{{At: at, Said: said}}, Source: o.Source, - Resolver: o.Resolver, Observer: observer, Run: run, At: at} - if o.Ref != "" && o.Ref != o.Kind { - f.Ref = o.Ref - } - return f -} - -// EncodeFinding is f as JSON at FindingVersion; it refuses what CheckFinding refuses. -func EncodeFinding(f seat.FindingsByKeyValue) ([]byte, error) { - f.V = FindingVersion - if f.Evidence == nil { - f.Evidence = []seat.Evidence{} - } - if err := CheckFinding(f); err != nil { - return nil, err - } - return json.Marshal(f) -} - -// DecodeFinding reads a finding's value; it refuses another version and what CheckFinding refuses. A finding written -// before the field was named `ref` (novox/hq issue 1952) is read by its old name, `token`. -func DecodeFinding(data []byte) (seat.FindingsByKeyValue, error) { - f, err := seat.DecodeFindingsByKeyValue(data) - if err != nil { - return seat.FindingsByKeyValue{}, fmt.Errorf("health: a finding is not readable: %w", err) - } - if f.V != FindingVersion { - return seat.FindingsByKeyValue{}, fmt.Errorf("health: a finding of version %d, and this reads %d", f.V, FindingVersion) - } - if err := CheckFinding(f); err != nil { - return seat.FindingsByKeyValue{}, err - } - return f, nil -} - -// Says is what a finding says, the moments and the run that wrote it aside: two findings that say the same are one -// write (novox/hq ADR 0289 §1), so the condition moves only when the words do. -func Says(f seat.FindingsByKeyValue) string { - f.At, f.Run, f.V = time.Time{}, "", 0 - ev := make([]seat.Evidence, len(f.Evidence)) - for i, e := range f.Evidence { - ev[i] = seat.Evidence{Said: e.Said} - } - f.Evidence = ev - raw, _ := json.Marshal(f) - return string(raw) -} - -// FindingBucket is the part of an observer's state `findings` that Raise and Clear use. -type FindingBucket interface { - // Get answers the value at key; found is false when there is none. - Get(key string) (value []byte, found bool, err error) - Put(key string, value []byte) error - Delete(key string) error -} - -// Raise writes the observation as observer's finding in run at at, only when what it says differs from the finding kept -// (so the keeper's condition moves only then); wrote says whether it wrote. A finding the keeper could not make a -// condition of is refused, nothing written. -func Raise(b FindingBucket, observer, run string, o Observation, at time.Time) (wrote bool, err error) { - f := o.Finding(observer, run, at) - value, err := EncodeFinding(f) - if err != nil { - return false, err - } - if kept, found, err := b.Get(f.Key); err != nil { - return false, err - } else if found { - if old, err := DecodeFinding(kept); err == nil && Says(old) == Says(f) { - return false, nil - } - } - return true, b.Put(f.Key, value) -} - -// Clear deletes the finding about scope and id of kind (its token); one not there is nothing to clear, and cleared says -// whether one was. -func Clear(b FindingBucket, scope, id, token string) (cleared bool, err error) { - key := Key(scope, id, token) - if _, found, err := b.Get(key); err != nil || !found { - return false, err - } - return true, b.Delete(key) -} - -// KindCallUnanswered is the kind of a kept call still unanswered past CallUnansweredAfter (novox/hq ADR 0668 §3, issue -// 1966): a call whose answer the caller keeps, asked again through every transport fault, that no answer has ended. The -// caller writes it into its own findings, keeps the wait, and clears it when the call is answered. -const KindCallUnanswered = "call-unanswered" - -// CallUnansweredAfter is how long a kept call stays unanswered before it is a finding (ADR 0668 §3; ADR 0564 §2's bound). -const CallUnansweredAfter = 5 * time.Minute - -// CallUnanswered is the observation of a kept call to callee (a seat verb's or a tool's key, as process.Conn.Call names -// it) about id (what the caller waits on: a node, a merge, a key), unanswered since since, its last fault said. Its key -// is `call..call-unanswered`, cleared by Clear(b, ScopeCall, id, KindCallUnanswered). -func CallUnanswered(id, callee, machine, fault, source string, since time.Time) Observation { - return Observation{Scope: ScopeCall, ID: id, Kind: KindCallUnanswered, Machine: machine, Severity: Warning, - Summary: fmt.Sprintf("the call %s about %s is unanswered since %s", callee, id, since.UTC().Format(time.RFC3339)), - Said: fault, - Headline: "A call whose answer is kept is not answered", - Explanation: fmt.Sprintf("The call %s is made again on every transport fault and on the callee's event; it has "+ - "not been answered since %s. Its last fault: %s.", callee, since.UTC().Format(time.RFC3339), fault), - Resolved: "the call is answered", Source: source} -} diff --git a/health-and-repair/go/clients/meshconditionsclient/testdata/finding_full.json b/health-and-repair/go/clients/meshconditionsclient/testdata/finding_full.json deleted file mode 100644 index 54bf2f8..0000000 --- a/health-and-repair/go/clients/meshconditionsclient/testdata/finding_full.json +++ /dev/null @@ -1 +0,0 @@ -{"v":1,"key":"machine.g14.silent","kind":"silent-kind","ref":"silent","subject":{"scope":"machine","id":"g14","machine":"g14","also":["ace"]},"severity":"urgent","summary":"g14 is silent","headline":"g14 is silent","explanation":"It said nothing.","resolved":"It speaks.","needs":"look","evidence":[{"at":"2026-11-05T12:00:00Z","said":"no pulse"}],"source":"S1","resolver":"operator","observer":"mesh-delivery-watchman","run":"r1","at":"2026-11-05T12:00:00Z"} diff --git a/health-and-repair/go/clients/meshconditionsclient/testdata/finding_minimal.json b/health-and-repair/go/clients/meshconditionsclient/testdata/finding_minimal.json deleted file mode 100644 index e0fef12..0000000 --- a/health-and-repair/go/clients/meshconditionsclient/testdata/finding_minimal.json +++ /dev/null @@ -1 +0,0 @@ -{"v":1,"key":"module.nats.g14.build-failed","kind":"build-failed","subject":{"scope":"module","id":"nats.g14"},"severity":"warning","summary":"failed","headline":"","explanation":"","resolved":"","evidence":[{"at":"2026-11-05T12:00:00Z","said":"failed"}],"source":"builder.build-failed","observer":"mesh-delivery-builder","at":"2026-11-05T12:00:00Z"} From bd038b15a3566b410abcf2875dd2ecf7a8168a23 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:44:03 +0100 Subject: [PATCH 39/62] K23 (owner and waiting-on of a condition): the seat mesh-conditions' condition and its events carry them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §685 (§451, §540, §678) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../go/seats/meshconditions/contract.go | 20 ++++-- .../go/seats/meshconditions/contract_test.go | 6 ++ .../mesh-conditions/fixtures/events.json | 23 +++++++ .../mesh-conditions/fixtures/states.json | 66 +++++++++++++++++++ .../seats/mesh-conditions/seat.json | 20 ++++++ .../ts/seats/meshconditions/index.d.ts | 8 +++ 6 files changed, 137 insertions(+), 6 deletions(-) diff --git a/health-and-repair/go/seats/meshconditions/contract.go b/health-and-repair/go/seats/meshconditions/contract.go index 5962e98..f07e37f 100644 --- a/health-and-repair/go/seats/meshconditions/contract.go +++ b/health-and-repair/go/seats/meshconditions/contract.go @@ -232,8 +232,10 @@ type ConditionEvent struct { LooksUnread string `json:"looks-unread,omitempty"` Needs string `json:"needs,omitempty"` Observations int64 `json:"observations,omitempty"` - Raised *time.Time `json:"raised,omitempty"` - Resolved string `json:"resolved,omitempty"` + // who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) + Owner string `json:"owner,omitempty"` + Raised *time.Time `json:"raised,omitempty"` + Resolved string `json:"resolved,omitempty"` // self, operator, agent or healer: Resolver string `json:"resolver,omitempty"` Severity string `json:"severity,omitempty"` @@ -246,8 +248,10 @@ type ConditionEvent struct { // one line Summary string `json:"summary,omitempty"` Tried []ConditionEventTriedItem `json:"tried,omitempty"` - Was string `json:"was,omitempty"` - Why string `json:"why,omitempty"` + // what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) + WaitingOn string `json:"waiting-on,omitempty"` + Was string `json:"was,omitempty"` + Why string `json:"why,omitempty"` } // The values of ConditionEvent's change. @@ -469,8 +473,10 @@ type ConditionsByKeyValue struct { LooksUnread string `json:"looks-unread,omitempty"` Needs string `json:"needs,omitempty"` Observations int64 `json:"observations,omitempty"` - Raised time.Time `json:"raised"` - Resolved string `json:"resolved,omitempty"` + // who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) + Owner string `json:"owner,omitempty"` + Raised time.Time `json:"raised"` + Resolved string `json:"resolved,omitempty"` // self, operator, agent or healer: Resolver string `json:"resolver,omitempty"` Severity string `json:"severity"` @@ -481,6 +487,8 @@ type ConditionsByKeyValue struct { // one line Summary string `json:"summary,omitempty"` Tried []ConditionsByKeyValueTriedItem `json:"tried,omitempty"` + // what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) + WaitingOn string `json:"waiting-on,omitempty"` } // The values of ConditionsByKeyValue's severity. diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index 92f71e5..ea0fedb 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -21,10 +21,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, {name: "the keeper asks every observer", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", wire: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, + {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")}, {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"jochen@shanks\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"jochen@shanks\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", + decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:jochen\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:jochen\"}", + decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue diff --git a/health-and-repair/seats/mesh-conditions/fixtures/events.json b/health-and-repair/seats/mesh-conditions/fixtures/events.json index dde417e..eebbd31 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/events.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/events.json @@ -19,5 +19,28 @@ "at": "2026-11-11T10:01:00Z", "by": "mesh-conditions" } + }, + { + "name": "a condition raised with its owner and what it waits on (design 47 G 685)", + "of": "event:condition-raised", + "subject": "mesh.seat.mesh-conditions.event.condition-raised", + "given": { + "key": "module.mesh-host.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "subject": { + "scope": "module", + "id": "mesh-host.ace", + "machine": "ace" + }, + "severity": "warning", + "summary": "a directory waits for a hand", + "source": "health-report", + "resolver": "self", + "owner": "forge:jochen", + "waiting-on": "node-engine", + "event": "condition-raised", + "at": "2026-11-11T10:00:00Z", + "change": "raised" + } } ] diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index 6b421c1..1b66c9e 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -60,6 +60,72 @@ "summary": "The backup of postgres failed on ace" } }, + { + "name": "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", + "of": "state:conditions/", + "given": { + "count": 1, + "evidence": [ + { + "at": "2026-10-26T20:19:41.474823121Z", + "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + } + ], + "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", + "headline": "mesh-build-node waits for a directory on ace", + "key": "module.mesh-build-node.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "last-observed": "2026-10-26T20:19:41.474823121Z", + "needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.", + "observations": 1, + "raised": "2026-10-31T08:19:57.076843727Z", + "resolved": "mesh-build-node's directory on ace is the mesh's", + "resolver": "self", + "severity": "warning", + "source": "health-report", + "subject": { + "id": "mesh-build-node.ace", + "machine": "ace", + "scope": "module" + }, + "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", + "owner": "jochen@shanks", + "waiting-on": "node-engine" + } + }, + { + "name": "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", + "of": "state:conditions/", + "given": { + "count": 1, + "evidence": [ + { + "at": "2026-10-26T20:19:41.474823121Z", + "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + } + ], + "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", + "headline": "mesh-build-node waits for a directory on ace", + "key": "module.mesh-build-node.ace.directory-used-as-found", + "kind": "directory-used-as-found", + "last-observed": "2026-10-26T20:19:41.474823121Z", + "needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.", + "observations": 1, + "raised": "2026-10-31T08:19:57.076843727Z", + "resolved": "mesh-build-node's directory on ace is the mesh's", + "resolver": "self", + "severity": "warning", + "source": "health-report", + "subject": { + "id": "mesh-build-node.ace", + "machine": "ace", + "scope": "module" + }, + "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", + "owner": "operator-channel", + "waiting-on": "forge:jochen" + } + }, { "name": "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", "of": "state:findings/..", diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index 14be042..ceec115 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -229,6 +229,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -538,6 +548,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" diff --git a/health-and-repair/ts/seats/meshconditions/index.d.ts b/health-and-repair/ts/seats/meshconditions/index.d.ts index f6e33fa..22c4ea8 100644 --- a/health-and-repair/ts/seats/meshconditions/index.d.ts +++ b/health-and-repair/ts/seats/meshconditions/index.d.ts @@ -104,6 +104,8 @@ export interface ConditionEvent { "looks-unread"?: string; "needs"?: string; "observations"?: number; + /** who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ + "owner"?: string; "raised"?: string; "resolved"?: string; /** self, operator, agent or healer: */ @@ -118,6 +120,8 @@ export interface ConditionEvent { /** one line */ "summary"?: string; "tried"?: ConditionEventTriedItem[]; + /** what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ + "waiting-on"?: string; "was"?: string; "why"?: string; } @@ -306,6 +310,8 @@ export interface ConditionsByKeyValue { "looks-unread"?: string; "needs"?: string; "observations"?: number; + /** who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ + "owner"?: string; "raised": string; "resolved"?: string; /** self, operator, agent or healer: */ @@ -318,6 +324,8 @@ export interface ConditionsByKeyValue { /** one line */ "summary"?: string; "tried"?: ConditionsByKeyValueTriedItem[]; + /** what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678) */ + "waiting-on"?: string; } /** is one value of the state findings under the key ... */ From 0ccac1d42aa06075482dc6e392374ebbc7fd540f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:45:23 +0100 Subject: [PATCH 40/62] K11 (no named callers): no seat definition names a callers, and the verbs that had one keep their class MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every verb takes its class's default (read: invokers, persons, sessions; act and warrant: operator, sessions, invokers); resync and retire, which named a caller beside the operator or a seat, are of class act. Builds: design 47 G §610 (§391, §392, §394, §405, §555, §554, §659, §681, §393, §422, §579) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- format/seat-definition.schema.json | 20 +--------------- .../seats/mesh-conditions/seat.json | 6 +---- .../seats/mesh-vault/seat.json | 6 ++--- .../seats/operator-channel/seat.json | 4 ---- seats/mesh-broker/seat.json | 24 ------------------- seats/mesh-config/seat.json | 3 --- seats/node-engine/seat.json | 23 ------------------ 7 files changed, 4 insertions(+), 82 deletions(-) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index dfba914..d162c07 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -339,22 +339,13 @@ "type": "object", "description": "a JSON Schema" }, - "callers": { - "type": "array", - "minItems": 1, - "items": { - "type": "string", - "pattern": "^(operator|healers|persons|sessions|invokers|seat:[a-z][a-z0-9-]*|module:[a-z][a-z0-9-]*|holder:[a-z][a-z0-9-]*@same-node)$" - }, - "description": "who may call: a list of operator, healers, persons (any person the tool runner proves), sessions (an agent session it proves), invokers (every module whose manifest declares the verb in invokes), seat: (a holder role), module:, or holder:@same-node (the holder of that seat on the node of the verb's holder); the grants part reads it as its one source of caller limits (design 47 G, 336 and 392). A verb naming none takes the default of its class (391)" - }, "class": { "enum": [ "read", "act", "warrant" ], - "description": "read: invokers, persons and sessions; act: operator and sessions; warrant: operator alone, with needs-approval (design 47 G 391). A verb that names no class is a read, whether it is on main or design 47 G adds it, and nothing refuses a verb for naming none (design 47 G 456)" + "description": "read: invokers, persons and sessions; act and warrant: operator, sessions and invokers (design 47 G 610); no verb names its callers, and a definition naming a `callers` is refused. A verb that names no class is a read, whether it is on main or design 47 G adds it, and nothing refuses a verb for naming none (design 47 G 456)" }, "needs-approval": { "type": "boolean", @@ -390,15 +381,6 @@ }, "by-caller": { "type": "boolean" - }, - "callers": { - "type": "array", - "minItems": 1, - "items": { - "type": "string", - "pattern": "^(operator|healers|persons|sessions|invokers|seat:[a-z][a-z0-9-]*|module:[a-z][a-z0-9-]*|holder:[a-z][a-z0-9-]*@same-node)$" - }, - "description": "who may call: a list of operator, healers, persons (any person the tool runner proves), sessions (an agent session it proves), invokers (every module whose manifest declares the verb in invokes), seat: (a holder role), module:, or holder:@same-node (the holder of that seat on the node of the verb's holder); the grants part reads it as its one source of caller limits (design 47 G, 336 and 392). A verb naming none takes the default of its class (391)" } } }, diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index ceec115..e5d45a8 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -99,11 +99,7 @@ "type": "object", "description": "what was raised and cleared again" }, - "callers": [ - "operator", - "healers", - "sessions" - ] + "class": "act" } ], "events": [ diff --git a/identity-and-access/seats/mesh-vault/seat.json b/identity-and-access/seats/mesh-vault/seat.json index 749f148..84c7260 100644 --- a/identity-and-access/seats/mesh-vault/seat.json +++ b/identity-and-access/seats/mesh-vault/seat.json @@ -597,9 +597,6 @@ "name": "retire", "optional": true, "description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.", - "callers": [ - "seat:mesh-config" - ], "input": { "type": "object", "properties": { @@ -643,7 +640,8 @@ "required": [ "retired" ] - } + }, + "class": "act" } ], "description": "The mesh's secrets. accept and move-asks, which no holder served and nothing called, are left out (ADR 0620 §3). The vault's own events stay under its own subjects (ADR 0620 §2).", diff --git a/operator-and-conversation/seats/operator-channel/seat.json b/operator-and-conversation/seats/operator-channel/seat.json index 38d9ad2..31f7db8 100644 --- a/operator-and-conversation/seats/operator-channel/seat.json +++ b/operator-and-conversation/seats/operator-channel/seat.json @@ -189,10 +189,6 @@ "name": "ask-again", "description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).", "class": "act", - "callers": [ - "operator", - "healers" - ], "input": { "type": "object", "properties": { diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index 69c0849..fc42bdf 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -11,9 +11,6 @@ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -64,9 +61,6 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": [ - "invokers" - ], "input": { "$ref": "#/defs/Named" }, @@ -78,9 +72,6 @@ { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -136,9 +127,6 @@ { "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.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": {}, @@ -164,9 +152,6 @@ { "name": "create", "description": "Create one entry now.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Entry" }, @@ -179,9 +164,6 @@ { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Named" }, @@ -194,9 +176,6 @@ { "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.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -209,9 +188,6 @@ { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, diff --git a/seats/mesh-config/seat.json b/seats/mesh-config/seat.json index a92bc0a..9054314 100644 --- a/seats/mesh-config/seat.json +++ b/seats/mesh-config/seat.json @@ -64,9 +64,6 @@ } } }, - "callers": [ - "invokers" - ], "answer": { "type": "object", "properties": { diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 3156047..ddab4d6 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -694,11 +694,6 @@ { "name": "seat-list", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -710,11 +705,6 @@ { "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -727,10 +717,6 @@ "name": "first-views", "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", "class": "read", - "callers": [ - "persons", - "healers" - ], "input": { "type": "object", "properties": {} @@ -755,10 +741,6 @@ "name": "first-view-again", "description": "Ask the node-engine's first view of an owner's state again now, by hand (design 47 G 422, 204): a hand act, its caller and why kept in the status first-views reads; served by mesh-sdk's runtime as the view's again tool.", "class": "act", - "callers": [ - "operator", - "healers" - ], "input": { "type": "object", "required": [ @@ -837,11 +819,6 @@ { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": { From b76e52d30a98a43e07e28c6f7c5b2f9a754cbfbb Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 20:45:56 +0100 Subject: [PATCH 41/62] K24 (mesh-recovery's hand verbs): take, restore, retry, aside, discard-aside and expire-points, asker and why on every hand verb, one answer form with cancel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §682, §691 (§516, §554, §566, §656, §681) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/seats/meshrecovery/contract.go | 156 ++++++++++- go/seats/meshrecovery/contract_test.go | 34 ++- seats/mesh-recovery/fixtures/verbs.json | 134 ++++++++- seats/mesh-recovery/seat.json | 351 +++++++++++++++++++++++- ts/seats/meshrecovery/index.d.ts | 154 ++++++++++- ts/seats/meshrecovery/index.js | 6 + 6 files changed, 823 insertions(+), 12 deletions(-) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go index 7c6a38a..4f1846e 100644 --- a/go/seats/meshrecovery/contract.go +++ b/go/seats/meshrecovery/contract.go @@ -14,6 +14,12 @@ const ( VerbKeptPoints = "kept-points" VerbRestoreAside = "restore-aside" VerbCancel = "cancel" + VerbTake = "take" + VerbRestore = "restore" + VerbRetry = "retry" + VerbAside = "aside" + VerbDiscardAside = "discard-aside" + VerbExpirePoints = "expire-points" ) const ( @@ -28,7 +34,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbSnapshotKept, VerbRestoreKept, VerbKeptPoints, VerbRestoreAside, VerbCancel} + return []string{VerbSnapshotKept, VerbRestoreKept, VerbKeptPoints, VerbRestoreAside, VerbCancel, VerbTake, VerbRestore, VerbRetry, VerbAside, VerbDiscardAside, VerbExpirePoints} } // Events is every event published on the seat's subject: a new copy each call. @@ -244,6 +250,8 @@ type KeptPointsAnswer struct { // RestoreAsideInput is what restore-aside takes. type RestoreAsideInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` // the aside's id ID string `json:"id"` // the kept data, its local name in the module's manifest @@ -268,18 +276,160 @@ type RestoreAsideAnswer struct { type CancelInput struct { // the act's id Act string `json:"act"` + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` // why, which the hand-act log keeps Why string `json:"why"` } // CancelAnswer is what cancel answers. type CancelAnswer struct { - // the act ended cancelled - Cancelled bool `json:"cancelled,omitempty"` + // accepted: the id of the act it cancelled, whose ending event follows under that id + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` // why not, naming the step an act has begun; set alone Error string `json:"error,omitempty"` } +// TakeInput is what take takes. +type TakeInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // the fingerprint whose form the point is taken at + Fingerprint string `json:"fingerprint"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// TakeAnswer is what take answers. +type TakeAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// RestoreInput is what restore takes. +type RestoreInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // ask the backup holder for the points directory when the point is missing there; only with snapshot + FromBackup bool `json:"from-backup,omitempty"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // a keeper's snapshot by its request (design 47 G 681) + Request string `json:"request,omitempty"` + // a restore point's name + Snapshot string `json:"snapshot,omitempty"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// RestoreAnswer is what restore answers. +type RestoreAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// RetryInput is what retry takes. +type RetryInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// RetryAnswer is what retry answers. +type RetryAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// AsideInput is what aside takes. +type AsideInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// AsideAnswer is what aside answers. +type AsideAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// DiscardAsideInput is what discard-aside takes. +type DiscardAsideInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // the aside's id + ID string `json:"id"` + // the kept data, its local name in the module's manifest + Kept string `json:"kept"` + // the module + Module string `json:"module"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// DiscardAsideAnswer is what discard-aside answers. +type DiscardAsideAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + +// ExpirePointsInput is what expire-points takes. +type ExpirePointsInput struct { + // who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) + Asker string `json:"asker,omitempty"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// ExpirePointsAnswer is what expire-points answers. +type ExpirePointsAnswer struct { + // accepted: the act's id, which the ending event carries + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event + Busy string `json:"busy,omitempty"` + // why it was not taken; set alone + Error string `json:"error,omitempty"` +} + // EndedEvent is the body of the event ended. type EndedEvent struct { // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 27e7065..8d7277d 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -45,12 +45,42 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "restore-aside names the aside", subject: "", given: "{\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", + {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"why\":\"the dump waits too long\"}", + {name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"asker\":\"jochen@shanks\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"asker\":\"jochen@shanks\",\"why\":\"the dump waits too long\"}", decode: func(b []byte) (any, error) { var v CancelInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "take names the fingerprint whose form the point is taken at", subject: "", given: "{\"asker\":\"jochen@shanks\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + decode: func(b []byte) (any, error) { var v TakeInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "take answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v TakeAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore takes a point by its name", subject: "", given: "{\"asker\":\"jochen@shanks\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", + decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore takes a keeper's snapshot by its request", subject: "", given: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", + decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "restore answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v RestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "retry names the module and its kept data", subject: "", given: "{\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"a failed take\"}", wire: "{\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"a failed take\"}", + decode: func(b []byte) (any, error) { var v RetryInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "retry answers an error when nothing failed", subject: "", given: "{\"error\":\"nothing to retry\"}", wire: "{\"error\":\"nothing to retry\"}", + decode: func(b []byte) (any, error) { var v RetryAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "aside sets the live kept data aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + decode: func(b []byte) (any, error) { var v AsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "aside answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v AsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "discard-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + decode: func(b []byte) (any, error) { var v DiscardAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "discard-aside answers an error", subject: "", given: "{\"error\":\"no such aside\"}", wire: "{\"error\":\"no such aside\"}", + decode: func(b []byte) (any, error) { var v DiscardAsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "expire-points has no field of its own", subject: "", given: "{\"asker\":\"operator\",\"why\":\"the points past 90 days\"}", wire: "{\"asker\":\"operator\",\"why\":\"the points past 90 days\"}", + decode: func(b []byte) (any, error) { var v ExpirePointsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "expire-points answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v ExpirePointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "cancel answers accepted with the act it cancelled", subject: "", given: "{\"accepted\":\"a-1\"}", wire: "{\"accepted\":\"a-1\"}", + decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "cancel answers an error naming the step an act has begun", subject: "", given: "{\"error\":\"the act has begun: step restoring\"}", wire: "{\"error\":\"the act has begun: step restoring\"}", decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "cancel answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v CancelAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json index 71fbe83..65f5c8b 100644 --- a/seats/mesh-recovery/fixtures/verbs.json +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -103,7 +103,8 @@ "module": "mesh-knowledge", "kept": "ledger", "id": "20261111T121200Z", - "why": "an aside left at removed" + "why": "an aside left at removed", + "asker": "jochen@shanks" } }, { @@ -111,7 +112,129 @@ "of": "verb:cancel.input", "given": { "act": "a-1", - "why": "the dump waits too long" + "why": "the dump waits too long", + "asker": "jochen@shanks" + } + }, + { + "name": "take names the fingerprint whose form the point is taken at", + "of": "verb:take.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "the operator's hand act", + "asker": "jochen@shanks", + "fingerprint": "0123456789ab" + } + }, + { + "name": "take answers accepted with the act", + "of": "verb:take.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "restore takes a point by its name", + "of": "verb:restore.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "the operator's hand act", + "asker": "jochen@shanks", + "snapshot": "2-0123456789ab", + "from-backup": true + } + }, + { + "name": "restore takes a keeper's snapshot by its request", + "of": "verb:restore.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "the operator's hand act", + "asker": "jochen@shanks", + "request": "r-20261111t100000" + } + }, + { + "name": "restore answers busy with the act that runs", + "of": "verb:restore.answer", + "given": { + "busy": "a-20261111t100000" + } + }, + { + "name": "retry names the module and its kept data", + "of": "verb:retry.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "a failed take" + } + }, + { + "name": "retry answers an error when nothing failed", + "of": "verb:retry.answer", + "given": { + "error": "nothing to retry" + } + }, + { + "name": "aside sets the live kept data aside", + "of": "verb:aside.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "the operator's hand act", + "asker": "jochen@shanks" + } + }, + { + "name": "aside answers accepted with the act", + "of": "verb:aside.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "discard-aside names the aside", + "of": "verb:discard-aside.input", + "given": { + "module": "mesh-knowledge", + "kept": "ledger", + "why": "the operator's hand act", + "asker": "jochen@shanks", + "id": "20261111T121200Z" + } + }, + { + "name": "discard-aside answers an error", + "of": "verb:discard-aside.answer", + "given": { + "error": "no such aside" + } + }, + { + "name": "expire-points has no field of its own", + "of": "verb:expire-points.input", + "given": { + "why": "the points past 90 days", + "asker": "operator" + } + }, + { + "name": "expire-points answers accepted with the act", + "of": "verb:expire-points.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "cancel answers accepted with the act it cancelled", + "of": "verb:cancel.answer", + "given": { + "accepted": "a-1" } }, { @@ -120,5 +243,12 @@ "given": { "error": "the act has begun: step restoring" } + }, + { + "name": "cancel answers busy with the act that runs", + "of": "verb:cancel.answer", + "given": { + "busy": "a-20261111t100000" + } } ] diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json index 92ca793..31fff7a 100644 --- a/seats/mesh-recovery/seat.json +++ b/seats/mesh-recovery/seat.json @@ -208,6 +208,10 @@ "why": { "type": "string", "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" } }, "required": [ @@ -253,6 +257,10 @@ "why": { "type": "string", "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" } }, "required": [ @@ -263,10 +271,15 @@ }, "answer": { "type": "object", + "description": "the act cancelled, or busy, or the error; one of the three is set (design 47 G 682, 691)", "properties": { - "cancelled": { - "type": "boolean", - "description": "the act ended cancelled" + "accepted": { + "type": "string", + "description": "accepted: the id of the act it cancelled, whose ending event follows under that id" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" }, "error": { "type": "string", @@ -274,6 +287,338 @@ } } } + }, + { + "name": "take", + "description": "Hand act: take a point of one module's kept data at that fingerprint's form, as snapshot-kept does with no catch-up. Answers accepted, busy or error at once; the point comes on the event ended (design 47 G 682, 554).", + "by-caller": true, + "class": "act", + "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 + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint whose form the point is taken at", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "restore", + "description": "Hand act: restore one module's kept data as restore-kept does, from a point by its name or from a keeper's snapshot by its request; exactly one of snapshot and request, and from-backup only with snapshot (design 47 G 682, 681). Answers accepted, busy or error at once; the result comes on the event restored.", + "by-caller": true, + "class": "act", + "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 + }, + "snapshot": { + "type": "string", + "description": "a restore point's name", + "minLength": 1 + }, + "request": { + "type": "string", + "description": "a keeper's snapshot by its request (design 47 G 681)", + "minLength": 1 + }, + "from-backup": { + "type": "boolean", + "description": "ask the backup holder for the points directory when the point is missing there; only with snapshot" + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "retry", + "description": "Hand act: ask again the last failed act of that module and kept data, with its fields; the error nothing to retry when its last act did not fail. The result comes on that act's ending event (design 47 G 682).", + "by-caller": true, + "class": "act", + "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 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "aside", + "description": "Hand act: set the live kept data aside without restoring (design 47 G 516, 682). Answers accepted, busy or error at once; the result comes on the event set-aside.", + "by-caller": true, + "class": "act", + "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 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "discard-aside", + "description": "Hand act: remove one aside's directory (design 47 G 682). Answers accepted, busy or error at once; the result comes on the event aside-discarded.", + "by-caller": true, + "class": "act", + "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 + }, + "id": { + "type": "string", + "description": "the aside's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "id", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "expire-points", + "description": "Hand act: remove the points past their 90 days now, as the module does by itself (design 47 G 551, 682). Answers accepted, busy or error at once; the result comes on the event expiry-ended.", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } } ], "events": [ diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts index 5d98c89..fda42f1 100644 --- a/ts/seats/meshrecovery/index.d.ts +++ b/ts/seats/meshrecovery/index.d.ts @@ -10,6 +10,12 @@ export declare const verbs: { readonly keptPoints: "kept-points"; readonly restoreAside: "restore-aside"; readonly cancel: "cancel"; + readonly take: "take"; + readonly restore: "restore"; + readonly retry: "retry"; + readonly aside: "aside"; + readonly discardAside: "discard-aside"; + readonly expirePoints: "expire-points"; }; export declare const events: { @@ -194,6 +200,8 @@ export interface KeptPointsAnswer { /** is what restore-aside takes. */ export interface RestoreAsideInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; /** the aside's id */ "id": string; /** the kept data, its local name in the module's manifest */ @@ -218,18 +226,160 @@ export interface RestoreAsideAnswer { export interface CancelInput { /** the act's id */ "act": string; + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; /** why, which the hand-act log keeps */ "why": string; } /** is what cancel answers. */ export interface CancelAnswer { - /** the act ended cancelled */ - "cancelled"?: boolean; + /** accepted: the id of the act it cancelled, whose ending event follows under that id */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; /** why not, naming the step an act has begun; set alone */ "error"?: string; } +/** is what take takes. */ +export interface TakeInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** the fingerprint whose form the point is taken at */ + "fingerprint": string; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what take answers. */ +export interface TakeAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what restore takes. */ +export interface RestoreInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** ask the backup holder for the points directory when the point is missing there; only with snapshot */ + "from-backup"?: boolean; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** a keeper's snapshot by its request (design 47 G 681) */ + "request"?: string; + /** a restore point's name */ + "snapshot"?: string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what restore answers. */ +export interface RestoreAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what retry takes. */ +export interface RetryInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what retry answers. */ +export interface RetryAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what aside takes. */ +export interface AsideInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what aside answers. */ +export interface AsideAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what discard-aside takes. */ +export interface DiscardAsideInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** the aside's id */ + "id": string; + /** the kept data, its local name in the module's manifest */ + "kept": string; + /** the module */ + "module": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what discard-aside answers. */ +export interface DiscardAsideAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + +/** is what expire-points takes. */ +export interface ExpirePointsInput { + /** who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682) */ + "asker"?: string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what expire-points answers. */ +export interface ExpirePointsAnswer { + /** accepted: the act's id, which the ending event carries */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event */ + "busy"?: string; + /** why it was not taken; set alone */ + "error"?: string; +} + /** is the body of the event ended. */ export interface EndedEvent { /** the id the act was answered accepted with, or a hand act's own id (design 47 G 560) */ diff --git a/ts/seats/meshrecovery/index.js b/ts/seats/meshrecovery/index.js index 2ceb51f..dac40f3 100644 --- a/ts/seats/meshrecovery/index.js +++ b/ts/seats/meshrecovery/index.js @@ -10,6 +10,12 @@ export const verbs = { keptPoints: "kept-points", restoreAside: "restore-aside", cancel: "cancel", + take: "take", + restore: "restore", + retry: "retry", + aside: "aside", + discardAside: "discard-aside", + expirePoints: "expire-points", }; export const events = { From 78e61c94371d364984579f8a85a618a62a8f9f31 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:36:34 +0100 Subject: [PATCH 42/62] K25 (D-33): the node-engine's first-views answers entries and wants, and the seat gains entry-again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §698 (§683, §422) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/seats/nodeengine/contract.go | 64 +++++++++++- go/seats/nodeengine/contract_test.go | 6 ++ seats/node-engine/fixtures/verbs.json | 53 ++++++++++ seats/node-engine/seat.json | 134 +++++++++++++++++++++++++- ts/seats/nodeengine/index.d.ts | 53 ++++++++++ ts/seats/nodeengine/index.js | 1 + 6 files changed, 308 insertions(+), 3 deletions(-) diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 96e1647..79347cb 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -30,6 +30,7 @@ const ( VerbSeatListAgain = "seat-list-again" VerbFirstViews = "first-views" VerbFirstViewAgain = "first-view-again" + VerbEntryAgain = "entry-again" VerbProcessBuilds = "process-builds" ) @@ -46,7 +47,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbFirstViews, VerbFirstViewAgain, VerbProcessBuilds} + return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain, VerbFirstViews, VerbFirstViewAgain, VerbEntryAgain, VerbProcessBuilds} } // Events is every event published on the seat's subject: a new copy each call. @@ -1366,10 +1367,41 @@ type SeatListAgainAnswer = SeatList type FirstViewsInput struct { } +// FirstViewsAnswerEntriesItem is a type of the contract. +type FirstViewsAnswerEntriesItem struct { + // the build's fingerprint + Fingerprint string `json:"fingerprint"` + // since when it stands in that state, RFC 3339 + Since time.Time `json:"since"` + // asked of the indexer, answered, or not found by it + State string `json:"state"` +} + +// The values of FirstViewsAnswerEntriesItem's state. +const ( + FirstViewsAnswerEntriesItemStateAsked = "asked" + FirstViewsAnswerEntriesItemStateAnswered = "answered" + FirstViewsAnswerEntriesItemStateNotFound = "not-found" +) + +// FirstViewsAnswerWantsItem is a type of the contract. +type FirstViewsAnswerWantsItem struct { + // the fingerprint wanted + Fingerprint string `json:"fingerprint"` + // since when the want is kept, RFC 3339 + KeptSince time.Time `json:"kept-since"` + // the module the want is of + Module string `json:"module"` +} + // FirstViewsAnswer is what first-views answers. type FirstViewsAnswer struct { + // one row per entry the node-engine keeps of a module's build by its fingerprint: when it asked the indexer's entry and where that stands (design 47 G 698) + Entries []FirstViewsAnswerEntriesItem `json:"entries"` // one status per owner and state followed, as mesh-sdk's views runtime keeps it FirstViews []map[string]any `json:"first-views"` + // the wants the node-engine keeps (design 47 G 683, 698) + Wants []FirstViewsAnswerWantsItem `json:"wants"` } // FirstViewAgainInput is what first-view-again takes. @@ -1406,6 +1438,36 @@ type FirstViewAgainAnswer struct { Read string `json:"read"` } +// EntryAgainInput is what entry-again takes. +type EntryAgainInput struct { + // the build's fingerprint, as first-views' entries name it + Fingerprint string `json:"fingerprint"` + // why it is asked again, in plain words + Why string `json:"why"` +} + +// EntryAgainAnswerAsked is the hand ask written. +type EntryAgainAnswerAsked struct { + // when it was asked, RFC 3339 + At time.Time `json:"at"` + // the caller the runtime proved + By string `json:"by"` + // the build's fingerprint + Fingerprint string `json:"fingerprint"` + // the layout's version + V int64 `json:"v"` + // why it was asked again + Why string `json:"why"` +} + +// EntryAgainAnswer is what entry-again answers. +type EntryAgainAnswer struct { + // the hand ask written + Asked EntryAgainAnswerAsked `json:"asked"` + // the verb that reads the status, first-views + Read string `json:"read"` +} + // ProcessBuildsInput is what process-builds takes. type ProcessBuildsInput struct { // only this module's processes diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index 7551025..b3285b5 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -115,6 +115,12 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "first-view-again names the owner, its state and why", subject: "", given: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", wire: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", decode: func(b []byte) (any, error) { var v FirstViewAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "first-views answers its entries and its kept wants", subject: "", given: "{\"entries\":[{\"fingerprint\":\"b3f1c9\",\"since\":\"2026-11-11T08:00:00Z\",\"state\":\"asked\"},{\"fingerprint\":\"a77d02\",\"since\":\"2026-11-11T08:01:00Z\",\"state\":\"answered\"},{\"fingerprint\":\"0c1e55\",\"since\":\"2026-11-11T08:02:00Z\",\"state\":\"not-found\"}],\"first-views\":[],\"wants\":[{\"fingerprint\":\"b3f1c9\",\"kept-since\":\"2026-11-11T07:00:00Z\",\"module\":\"mesh-delivery-indexer\"}]}", wire: "{\"entries\":[{\"fingerprint\":\"b3f1c9\",\"since\":\"2026-11-11T08:00:00Z\",\"state\":\"asked\"},{\"fingerprint\":\"a77d02\",\"since\":\"2026-11-11T08:01:00Z\",\"state\":\"answered\"},{\"fingerprint\":\"0c1e55\",\"since\":\"2026-11-11T08:02:00Z\",\"state\":\"not-found\"}],\"first-views\":[],\"wants\":[{\"fingerprint\":\"b3f1c9\",\"kept-since\":\"2026-11-11T07:00:00Z\",\"module\":\"mesh-delivery-indexer\"}]}", + decode: func(b []byte) (any, error) { var v FirstViewsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "entry-again names the fingerprint and why", subject: "", given: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}", wire: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}", + decode: func(b []byte) (any, error) { var v EntryAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "entry-again answers what was asked and where it is read", subject: "", given: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", wire: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", + decode: func(b []byte) (any, error) { var v EntryAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index a1488ee..2e3cc3f 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -165,5 +165,58 @@ "state": "manifests", "why": "the picture lags the indexer by hand" } + }, + { + "name": "first-views answers its entries and its kept wants", + "of": "verb:first-views.answer", + "given": { + "first-views": [], + "entries": [ + { + "fingerprint": "b3f1c9", + "state": "asked", + "since": "2026-11-11T08:00:00Z" + }, + { + "fingerprint": "a77d02", + "state": "answered", + "since": "2026-11-11T08:01:00Z" + }, + { + "fingerprint": "0c1e55", + "state": "not-found", + "since": "2026-11-11T08:02:00Z" + } + ], + "wants": [ + { + "module": "mesh-delivery-indexer", + "fingerprint": "b3f1c9", + "kept-since": "2026-11-11T07:00:00Z" + } + ] + } + }, + { + "name": "entry-again names the fingerprint and why", + "of": "verb:entry-again.input", + "given": { + "fingerprint": "b3f1c9", + "why": "the entry could not be read" + } + }, + { + "name": "entry-again answers what was asked and where it is read", + "of": "verb:entry-again.answer", + "given": { + "asked": { + "v": 1, + "fingerprint": "b3f1c9", + "why": "the entry could not be read", + "by": "operator@shanks", + "at": "2026-11-11T08:00:00Z" + }, + "read": "first-views" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index ddab4d6..19a8dd5 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -715,7 +715,7 @@ }, { "name": "first-views", - "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", + "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool; its entries and its kept wants beside (design 47 G 698).", "class": "read", "input": { "type": "object", @@ -724,7 +724,9 @@ "answer": { "type": "object", "required": [ - "first-views" + "first-views", + "entries", + "wants" ], "properties": { "first-views": { @@ -733,6 +735,65 @@ "type": "object" }, "description": "one status per owner and state followed, as mesh-sdk's views runtime keeps it" + }, + "entries": { + "type": "array", + "description": "one row per entry the node-engine keeps of a module's build by its fingerprint: when it asked the indexer's entry and where that stands (design 47 G 698)", + "items": { + "type": "object", + "required": [ + "fingerprint", + "state", + "since" + ], + "properties": { + "fingerprint": { + "type": "string", + "description": "the build's fingerprint" + }, + "state": { + "type": "string", + "enum": [ + "asked", + "answered", + "not-found" + ], + "description": "asked of the indexer, answered, or not found by it" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "since when it stands in that state, RFC 3339" + } + } + } + }, + "wants": { + "type": "array", + "description": "the wants the node-engine keeps (design 47 G 683, 698)", + "items": { + "type": "object", + "required": [ + "module", + "fingerprint", + "kept-since" + ], + "properties": { + "module": { + "type": "string", + "description": "the module the want is of" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint wanted" + }, + "kept-since": { + "type": "string", + "format": "date-time", + "description": "since when the want is kept, RFC 3339" + } + } + } } } } @@ -816,6 +877,75 @@ } } }, + { + "name": "entry-again", + "description": "Ask the indexer's entry of a build again now, by hand (design 47 G 683, 698): a hand act, its caller and why kept; the answer says what was asked and the verb that reads it.", + "class": "act", + "input": { + "type": "object", + "required": [ + "fingerprint", + "why" + ], + "properties": { + "fingerprint": { + "type": "string", + "description": "the build's fingerprint, as first-views' entries name it" + }, + "why": { + "type": "string", + "description": "why it is asked again, in plain words" + } + } + }, + "answer": { + "type": "object", + "required": [ + "asked", + "read" + ], + "properties": { + "asked": { + "type": "object", + "description": "the hand ask written", + "required": [ + "v", + "fingerprint", + "why", + "by", + "at" + ], + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "fingerprint": { + "type": "string", + "description": "the build's fingerprint" + }, + "why": { + "type": "string", + "description": "why it was asked again" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was asked, RFC 3339" + } + } + }, + "read": { + "type": "string", + "description": "the verb that reads the status, first-views" + } + } + } + }, { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index 61262b3..c34cace 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -20,6 +20,7 @@ export declare const verbs: { readonly seatListAgain: "seat-list-again"; readonly firstViews: "first-views"; readonly firstViewAgain: "first-view-again"; + readonly entryAgain: "entry-again"; readonly processBuilds: "process-builds"; }; @@ -1021,10 +1022,32 @@ export type SeatListAgainAnswer = SeatList; export interface FirstViewsInput { } +export interface FirstViewsAnswerEntriesItem { + /** the build's fingerprint */ + "fingerprint": string; + /** since when it stands in that state, RFC 3339 */ + "since": string; + /** asked of the indexer, answered, or not found by it */ + "state": "asked" | "answered" | "not-found"; +} + +export interface FirstViewsAnswerWantsItem { + /** the fingerprint wanted */ + "fingerprint": string; + /** since when the want is kept, RFC 3339 */ + "kept-since": string; + /** the module the want is of */ + "module": string; +} + /** is what first-views answers. */ export interface FirstViewsAnswer { + /** one row per entry the node-engine keeps of a module's build by its fingerprint: when it asked the indexer's entry and where that stands (design 47 G 698) */ + "entries": FirstViewsAnswerEntriesItem[]; /** one status per owner and state followed, as mesh-sdk's views runtime keeps it */ "first-views": Record[]; + /** the wants the node-engine keeps (design 47 G 683, 698) */ + "wants": FirstViewsAnswerWantsItem[]; } /** is what first-view-again takes. */ @@ -1061,6 +1084,36 @@ export interface FirstViewAgainAnswer { "read": string; } +/** is what entry-again takes. */ +export interface EntryAgainInput { + /** the build's fingerprint, as first-views' entries name it */ + "fingerprint": string; + /** why it is asked again, in plain words */ + "why": string; +} + +/** the hand ask written */ +export interface EntryAgainAnswerAsked { + /** when it was asked, RFC 3339 */ + "at": string; + /** the caller the runtime proved */ + "by": string; + /** the build's fingerprint */ + "fingerprint": string; + /** the layout's version */ + "v": number; + /** why it was asked again */ + "why": string; +} + +/** is what entry-again answers. */ +export interface EntryAgainAnswer { + /** the hand ask written */ + "asked": EntryAgainAnswerAsked; + /** the verb that reads the status, first-views */ + "read": string; +} + /** is what process-builds takes. */ export interface ProcessBuildsInput { /** only this module's processes */ diff --git a/ts/seats/nodeengine/index.js b/ts/seats/nodeengine/index.js index ce9c2e2..2c527bf 100644 --- a/ts/seats/nodeengine/index.js +++ b/ts/seats/nodeengine/index.js @@ -20,6 +20,7 @@ export const verbs = { seatListAgain: "seat-list-again", firstViews: "first-views", firstViewAgain: "first-view-again", + entryAgain: "entry-again", processBuilds: "process-builds", }; From 3658ceb1b68c21e6a3b4a8eca2e35a6e7d82b53b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:36:41 +0100 Subject: [PATCH 43/62] K26 (D-34): the definition format takes a state's view field, and the assigner's assignments and seat-holders carry it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §699 (§616; ADR 0571 §6) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- format/seat-definition.schema.json | 5 +++++ seats/mesh-module-assigner/seat.json | 2 ++ 2 files changed, 7 insertions(+) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index d162c07..504c2d5 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -525,6 +525,11 @@ }, "description": { "type": "string" + }, + "view": { + "type": "boolean", + "const": true, + "description": "true when the seat offers the state as a view for a module to follow by `consumes` (design 47 G 699; ADR 0571 §6); the manifest validator refuses a seat-named view of a state without it" } } }, diff --git a/seats/mesh-module-assigner/seat.json b/seats/mesh-module-assigner/seat.json index cd483f5..247f86b 100644 --- a/seats/mesh-module-assigner/seat.json +++ b/seats/mesh-module-assigner/seat.json @@ -190,6 +190,7 @@ { "name": "assignments", "template": "state", + "view": true, "key-forms": [ { "key": ".node", @@ -364,6 +365,7 @@ { "name": "seat-holders", "template": "state", + "view": true, "key-forms": [ { "key": "", From cf5590c7599d3ee3b61c3aa66c88a939ecb41130 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 22:37:57 +0100 Subject: [PATCH 44/62] =?UTF-8?q?bus5=20K27=20(=C2=A7681):=20mesh-broker's?= =?UTF-8?q?=20snapshot-get,=20snapshot-restore,=20snapshot-restore-cancel,?= =?UTF-8?q?=20snapshot-remove=20and=20snapshot-restored;=20the=20format's?= =?UTF-8?q?=20verb=20word=20chunks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §681, §691, A-44 --- format/seat-definition.schema.json | 4 + go/seats/meshbroker/contract.go | 156 ++++++++++++++-- go/seats/meshbroker/contract_test.go | 34 ++++ seats/mesh-broker/fixtures/events.json | 11 ++ seats/mesh-broker/fixtures/verbs.json | 97 ++++++++++ seats/mesh-broker/seat.json | 244 +++++++++++++++++++++++++ ts/seats/meshbroker/index.d.ts | 105 +++++++++++ ts/seats/meshbroker/index.js | 13 ++ 8 files changed, 645 insertions(+), 19 deletions(-) diff --git a/format/seat-definition.schema.json b/format/seat-definition.schema.json index 504c2d5..cc9aa31 100644 --- a/format/seat-definition.schema.json +++ b/format/seat-definition.schema.json @@ -354,6 +354,10 @@ "by-caller": { "type": "boolean", "description": "the holder's process answers the verb itself and tells callers apart by the account the bus proved (ADR 0259 3; design 47 G 554, 621, 656)" + }, + "chunks": { + "type": "boolean", + "description": "the holder's process sends the answer's file in chunks on mesh.seat..chunk..., each acknowledged by the caller on mesh.seat..ack...; only with by-caller (design 47 G 681)" } } }, diff --git a/go/seats/meshbroker/contract.go b/go/seats/meshbroker/contract.go index 50f6366..6dc0efb 100644 --- a/go/seats/meshbroker/contract.go +++ b/go/seats/meshbroker/contract.go @@ -3,40 +3,47 @@ // 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" + VerbList = "list" + VerbShow = "show" + VerbCheck = "check" + VerbOrphans = "orphans" + VerbCreate = "create" + VerbApply = "apply" + VerbRecreate = "recreate" + VerbDrop = "drop" + VerbSnapshotGet = "snapshot-get" + VerbSnapshotRestore = "snapshot-restore" + VerbSnapshotRestoreCancel = "snapshot-restore-cancel" + VerbSnapshotRemove = "snapshot-remove" ) const ( - EventCreated = "created" - EventRefused = "refused" - EventDrifted = "drifted" - EventDriftCleared = "drift-cleared" - EventFull = "full" - EventFullCleared = "full-cleared" - EventOrphaned = "orphaned" - EventRecreated = "recreated" - EventDropped = "dropped" + EventCreated = "created" + EventRefused = "refused" + EventDrifted = "drifted" + EventDriftCleared = "drift-cleared" + EventFull = "full" + EventFullCleared = "full-cleared" + EventOrphaned = "orphaned" + EventRecreated = "recreated" + EventDropped = "dropped" + EventSnapshotRestored = "snapshot-restored" ) // 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} + return []string{VerbList, VerbShow, VerbCheck, VerbOrphans, VerbCreate, VerbApply, VerbRecreate, VerbDrop, VerbSnapshotGet, VerbSnapshotRestore, VerbSnapshotRestoreCancel, VerbSnapshotRemove} } // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventCreated, EventRefused, EventDrifted, EventDriftCleared, EventFull, EventFullCleared, EventOrphaned, EventRecreated, EventDropped} + return []string{EventCreated, EventRefused, EventDrifted, EventDriftCleared, EventFull, EventFullCleared, EventOrphaned, EventRecreated, EventDropped, EventSnapshotRestored} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -72,6 +79,17 @@ const SubjectRecreated = "mesh.seat.mesh-broker.event.recreated" // SubjectDropped is where dropped is published. const SubjectDropped = "mesh.seat.mesh-broker.event.dropped" +// StreamSnapshotRestored is the stream snapshot-restored is kept in. +const StreamSnapshotRestored = "SEAT_mesh-broker_snapshot-restored" + +// SubjectSnapshotRestored is where snapshot-restored is published, on mesh.seat.mesh-broker.event.snapshot-restored... +func SubjectSnapshotRestored(request, act string) string { + return "mesh.seat.mesh-broker.event.snapshot-restored." + request + "." + act +} + +// SubjectSnapshotRestoredAll hears every snapshot-restored. +const SubjectSnapshotRestoredAll = "mesh.seat.mesh-broker.event.snapshot-restored.*.*" + // 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 { // a key-value bucket's name @@ -364,6 +382,91 @@ type DropAnswer struct { Snapshot string `json:"snapshot,omitempty"` } +// SnapshotGetInput is what snapshot-get takes. +type SnapshotGetInput struct { + // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements + Call string `json:"call"` + // the snapshot's request: the id of the request the keeper took it for, in its state requests + Request string `json:"request"` +} + +// SnapshotGetAnswer is what snapshot-get answers. +type SnapshotGetAnswer struct { + // when the snapshot was taken, RFC 3339 + At *time.Time `json:"at,omitempty"` + // how many chunks are sent; 0 when the caller is granted no chunk subjects + Chunks int64 `json:"chunks,omitempty"` + // sha256: of the file's bytes + Digest string `json:"digest,omitempty"` + // why not: snapshot damaged, snapshot missing, snapshot protected or snapshot taken before milestone G; set alone + Error string `json:"error,omitempty"` + // the entry's local name + Local string `json:"local,omitempty"` + Module string `json:"module,omitempty"` + Request string `json:"request,omitempty"` + Size int64 `json:"size,omitempty"` + // the stream's name on the bus + Stream string `json:"stream,omitempty"` +} + +// SnapshotRestoreInput is what snapshot-restore takes. +type SnapshotRestoreInput struct { + // the snapshot's request: the id of the request the keeper took it for, in its state requests + Request string `json:"request"` + // check the file against its digest and restore nothing + Verify bool `json:"verify,omitempty"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// SnapshotRestoreAnswer is what snapshot-restore answers. +type SnapshotRestoreAnswer struct { + // accepted: the act's id + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue + Busy string `json:"busy,omitempty"` + // why not; set alone + Error string `json:"error,omitempty"` +} + +// SnapshotRestoreCancelInput is what snapshot-restore-cancel takes. +type SnapshotRestoreCancelInput struct { + // the restore's act id + Act string `json:"act"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// SnapshotRestoreCancelAnswer is what snapshot-restore-cancel answers. +type SnapshotRestoreCancelAnswer struct { + // accepted: the act's id + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue + Busy string `json:"busy,omitempty"` + // why not; set alone + Error string `json:"error,omitempty"` +} + +// SnapshotRemoveInput is what snapshot-remove takes. +type SnapshotRemoveInput struct { + // true: every snapshot past snapshot-keep-days + Expired bool `json:"expired,omitempty"` + // the snapshot's request; or expired true, not both + Request string `json:"request,omitempty"` + // why, which the hand-act log keeps + Why string `json:"why"` +} + +// SnapshotRemoveAnswer is what snapshot-remove answers. +type SnapshotRemoveAnswer struct { + // accepted: the act's id + Accepted string `json:"accepted,omitempty"` + // busy: the id of the act that runs; it keeps no queue + Busy string `json:"busy,omitempty"` + // why not; set alone + Error string `json:"error,omitempty"` +} + // CreatedEvent is the body of the event created. type CreatedEvent = Said @@ -391,5 +494,20 @@ type RecreatedEvent = Said // DroppedEvent is the body of the event dropped. type DroppedEvent = Said +// SnapshotRestoredEvent is the body of the event snapshot-restored. +type SnapshotRestoredEvent struct { + Act string `json:"act"` + // when failed + Error string `json:"error,omitempty"` + Outcome string `json:"outcome"` + Request string `json:"request"` +} + +// The values of SnapshotRestoredEvent's outcome. +const ( + SnapshotRestoredEventOutcomeDone = "done" + SnapshotRestoredEventOutcomeFailed = "failed" +) + // BusStateForm is the form of the provision bus-state. type BusStateForm = Binding diff --git a/go/seats/meshbroker/contract_test.go b/go/seats/meshbroker/contract_test.go index 59c281f..c181a58 100644 --- a/go/seats/meshbroker/contract_test.go +++ b/go/seats/meshbroker/contract_test.go @@ -37,6 +37,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RecreatedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.recreated$")}, {name: "dropped on the seat's subject", subject: "mesh.seat.mesh-broker.event.dropped", 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 DroppedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.dropped$")}, + {name: "snapshot-restored is said under its request and act", subject: "mesh.seat.mesh-broker.event.snapshot-restored.r-1.a-20261111t100000", given: "{\"act\":\"a-20261111t100000\",\"error\":\"names live\",\"outcome\":\"failed\",\"request\":\"r-1\"}", wire: "{\"act\":\"a-20261111t100000\",\"error\":\"names live\",\"outcome\":\"failed\",\"request\":\"r-1\"}", + decode: func(b []byte) (any, error) { var v SnapshotRestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-broker\\.event\\.snapshot-restored\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "create one entry", subject: "", given: "{\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}", wire: "{\"local-name\":\"ledger\",\"module\":\"mesh-knowledge\",\"options\":{\"max-mib\":64},\"storage-type\":\"ledger\",\"template\":\"ledger\"}", decode: func(b []byte) (any, error) { var v CreateInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "drop on the operator's warrant", subject: "", given: "{\"local-name\":\"old\",\"module\":\"mesh-knowledge\",\"warrant\":\"w-1\",\"why\":\"the operator approved the drop\"}", wire: "{\"local-name\":\"old\",\"module\":\"mesh-knowledge\",\"warrant\":\"w-1\",\"why\":\"the operator approved the drop\"}", @@ -49,6 +51,38 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "list answers a sum with no limit, which is unlimited", subject: "", given: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}", wire: "{\"caps\":{\"sum-mib\":64},\"entries\":[]}", decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-get asks a snapshot by its request", subject: "", given: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"request\":\"r-1\"}", wire: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"request\":\"r-1\"}", + decode: func(b []byte) (any, error) { var v SnapshotGetInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-get answers the fields and the chunks", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"chunks\":2,\"digest\":\"sha256:00\",\"local\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-1\",\"size\":1048576,\"stream\":\"mesh-knowledge_ledger\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"chunks\":2,\"digest\":\"sha256:00\",\"local\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-1\",\"size\":1048576,\"stream\":\"mesh-knowledge_ledger\"}", + decode: func(b []byte) (any, error) { var v SnapshotGetAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-get answers a protected snapshot refused", subject: "", given: "{\"error\":\"snapshot protected\"}", wire: "{\"error\":\"snapshot protected\"}", + decode: func(b []byte) (any, error) { var v SnapshotGetAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-restore asks a verify", subject: "", given: "{\"request\":\"r-1\",\"verify\":true,\"why\":\"the file is read before the live data is set aside\"}", wire: "{\"request\":\"r-1\",\"verify\":true,\"why\":\"the file is read before the live data is set aside\"}", + decode: func(b []byte) (any, error) { var v SnapshotRestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-restore answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-restore answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t095900\"}", wire: "{\"busy\":\"a-20261111t095900\"}", + decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-restore answers names live", subject: "", given: "{\"error\":\"names live\"}", wire: "{\"error\":\"names live\"}", + decode: func(b []byte) (any, error) { var v SnapshotRestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-restore-cancel names the act", subject: "", given: "{\"act\":\"a-20261111t100000\",\"why\":\"the restore passed its bound\"}", wire: "{\"act\":\"a-20261111t100000\",\"why\":\"the restore passed its bound\"}", + decode: func(b []byte) (any, error) { + var v SnapshotRestoreCancelInput + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, + {name: "snapshot-restore-cancel answers accepted", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { + var v SnapshotRestoreCancelAnswer + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, + {name: "snapshot-remove names one snapshot", subject: "", given: "{\"request\":\"r-1\",\"why\":\"the data is restored\"}", wire: "{\"request\":\"r-1\",\"why\":\"the data is restored\"}", + decode: func(b []byte) (any, error) { var v SnapshotRemoveInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-remove names every expired one", subject: "", given: "{\"expired\":true,\"why\":\"the days are past\"}", wire: "{\"expired\":true,\"why\":\"the days are past\"}", + decode: func(b []byte) (any, error) { var v SnapshotRemoveInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "snapshot-remove answers accepted", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", + decode: func(b []byte) (any, error) { var v SnapshotRemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/seats/mesh-broker/fixtures/events.json b/seats/mesh-broker/fixtures/events.json index b9f6a8f..652e2d6 100644 --- a/seats/mesh-broker/fixtures/events.json +++ b/seats/mesh-broker/fixtures/events.json @@ -265,5 +265,16 @@ }, "why": "the bus refused it" } + }, + { + "name": "snapshot-restored is said under its request and act", + "of": "event:snapshot-restored", + "subject": "mesh.seat.mesh-broker.event.snapshot-restored.r-1.a-20261111t100000", + "given": { + "request": "r-1", + "act": "a-20261111t100000", + "outcome": "failed", + "error": "names live" + } } ] diff --git a/seats/mesh-broker/fixtures/verbs.json b/seats/mesh-broker/fixtures/verbs.json index 5cf98ac..6e8f330 100644 --- a/seats/mesh-broker/fixtures/verbs.json +++ b/seats/mesh-broker/fixtures/verbs.json @@ -136,5 +136,102 @@ "sum-mib": 64 } } + }, + { + "name": "snapshot-get asks a snapshot by its request", + "of": "verb:snapshot-get.input", + "given": { + "request": "r-1", + "call": "0123456789abcdef0123456789abcdef" + } + }, + { + "name": "snapshot-get answers the fields and the chunks", + "of": "verb:snapshot-get.answer", + "given": { + "request": "r-1", + "module": "mesh-knowledge", + "local": "ledger", + "stream": "mesh-knowledge_ledger", + "size": 1048576, + "digest": "sha256:00", + "at": "2026-11-11T10:00:00Z", + "chunks": 2 + } + }, + { + "name": "snapshot-get answers a protected snapshot refused", + "of": "verb:snapshot-get.answer", + "given": { + "error": "snapshot protected" + } + }, + { + "name": "snapshot-restore asks a verify", + "of": "verb:snapshot-restore.input", + "given": { + "request": "r-1", + "verify": true, + "why": "the file is read before the live data is set aside" + } + }, + { + "name": "snapshot-restore answers accepted with the act", + "of": "verb:snapshot-restore.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "snapshot-restore answers busy with the act that runs", + "of": "verb:snapshot-restore.answer", + "given": { + "busy": "a-20261111t095900" + } + }, + { + "name": "snapshot-restore answers names live", + "of": "verb:snapshot-restore.answer", + "given": { + "error": "names live" + } + }, + { + "name": "snapshot-restore-cancel names the act", + "of": "verb:snapshot-restore-cancel.input", + "given": { + "act": "a-20261111t100000", + "why": "the restore passed its bound" + } + }, + { + "name": "snapshot-restore-cancel answers accepted", + "of": "verb:snapshot-restore-cancel.answer", + "given": { + "accepted": "a-20261111t100000" + } + }, + { + "name": "snapshot-remove names one snapshot", + "of": "verb:snapshot-remove.input", + "given": { + "request": "r-1", + "why": "the data is restored" + } + }, + { + "name": "snapshot-remove names every expired one", + "of": "verb:snapshot-remove.input", + "given": { + "expired": true, + "why": "the days are past" + } + }, + { + "name": "snapshot-remove answers accepted", + "of": "verb:snapshot-remove.answer", + "given": { + "accepted": "a-20261111t100000" + } } ] diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index fc42bdf..4fab316 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.json @@ -209,6 +209,214 @@ }, "optional": true, "class": "warrant" + }, + { + "name": "snapshot-get", + "description": "Send the stream snapshot the bus module took before a drop or recreate: its fields, then the file in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A caller granted no chunk subjects is answered the fields alone, with chunks 0. Refuses snapshot damaged, snapshot missing, snapshot protected and snapshot taken before milestone G (design 47 G 681).", + "by-caller": true, + "chunks": true, + "class": "read", + "input": { + "type": "object", + "properties": { + "request": { + "type": "string", + "description": "the snapshot's request: the id of the request the keeper took it for, in its state requests", + "minLength": 1 + }, + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "request", + "call" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "request": { + "type": "string" + }, + "module": { + "type": "string" + }, + "local": { + "type": "string", + "description": "the entry's local name" + }, + "stream": { + "type": "string", + "description": "the stream's name on the bus" + }, + "size": { + "type": "integer", + "minimum": 0 + }, + "digest": { + "type": "string", + "description": "sha256: of the file's bytes" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when the snapshot was taken, RFC 3339" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent; 0 when the caller is granted no chunk subjects" + }, + "error": { + "type": "string", + "description": "why not: snapshot damaged, snapshot missing, snapshot protected or snapshot taken before milestone G; set alone" + } + } + }, + "optional": true + }, + { + "name": "snapshot-restore", + "description": "Restore in place the snapshot of a protected stream the bus module took before a drop or recreate, under the stream's own name: with verify true it only checks the file against its recorded digest and restores nothing; it refuses names live while a live object of the stream's name exists. Answers accepted, busy or error at once; the outcome comes on the event snapshot-restored (design 47 G 681).", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "request": { + "type": "string", + "description": "the snapshot's request: the id of the request the keeper took it for, in its state requests", + "minLength": 1 + }, + "verify": { + "type": "boolean", + "description": "check the file against its digest and restore nothing" + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + } + }, + "required": [ + "request", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; exactly one of the three is set (design 47 G 681, 691, A-44)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue" + }, + "error": { + "type": "string", + "description": "why not; set alone" + } + } + }, + "optional": true + }, + { + "name": "snapshot-restore-cancel", + "description": "Cancel a running restore: it removes the keeper's own partial stream, says snapshot-restored with outcome failed under that act and answers accepted, or answers error when that act has ended (design 47 G 681).", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "act": { + "type": "string", + "description": "the restore's act id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + } + }, + "required": [ + "act", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act cancelled, or busy with the act that runs, or the error; exactly one of the three is set (design 47 G 681, 691, A-44)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue" + }, + "error": { + "type": "string", + "description": "why not; set alone" + } + } + }, + "optional": true + }, + { + "name": "snapshot-remove", + "description": "Remove one snapshot and its record now, or every expired one, written in the hand-act log first; a snapshot of before milestone G only by request. Answers accepted, busy or error (design 47 G 681), A-44.", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "request": { + "type": "string", + "description": "the snapshot's request; or expired true, not both", + "minLength": 1 + }, + "expired": { + "type": "boolean", + "description": "true: every snapshot past snapshot-keep-days" + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + } + }, + "required": [ + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; exactly one of the three is set (design 47 G 681, 691, A-44)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue" + }, + "error": { + "type": "string", + "description": "why not; set alone" + } + } + }, + "optional": true } ], "events": [ @@ -265,6 +473,42 @@ "body": { "$ref": "#/defs/Said" } + }, + { + "name": "snapshot-restored", + "subject": "snapshot-restored..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "how one restore in place of a protected snapshot ended, under the act it was answered accepted with, so a retried restore is told apart from an earlier one (design 47 G 681)", + "properties": { + "request": { + "type": "string" + }, + "act": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string", + "description": "when failed" + } + }, + "required": [ + "request", + "act", + "outcome" + ] + } } ], "family": { diff --git a/ts/seats/meshbroker/index.d.ts b/ts/seats/meshbroker/index.d.ts index 68e5e83..5edf309 100644 --- a/ts/seats/meshbroker/index.d.ts +++ b/ts/seats/meshbroker/index.d.ts @@ -13,6 +13,10 @@ export declare const verbs: { readonly apply: "apply"; readonly recreate: "recreate"; readonly drop: "drop"; + readonly snapshotGet: "snapshot-get"; + readonly snapshotRestore: "snapshot-restore"; + readonly snapshotRestoreCancel: "snapshot-restore-cancel"; + readonly snapshotRemove: "snapshot-remove"; }; export declare const events: { @@ -25,6 +29,7 @@ export declare const events: { readonly orphaned: "orphaned"; readonly recreated: "recreated"; readonly dropped: "dropped"; + readonly snapshotRestored: "snapshot-restored"; }; export declare const family: { readonly name: "mesh-broker.events"; readonly maxAgeDays: 7 }; @@ -47,6 +52,12 @@ export declare const recreatedSubject: "mesh.seat.mesh-broker.event.recreated"; export declare const droppedSubject: "mesh.seat.mesh-broker.event.dropped"; +export declare const snapshotRestoredStream: "SEAT_mesh-broker_snapshot-restored"; + +export declare function snapshotRestoredSubject(request: string, act: string): string; + +export declare const snapshotRestoredSubjectAll: "mesh.seat.mesh-broker.event.snapshot-restored.*.*"; + /** 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 { /** a key-value bucket's name */ @@ -268,6 +279,91 @@ export interface DropAnswer { "snapshot"?: string; } +/** is what snapshot-get takes. */ +export interface SnapshotGetInput { + /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ + "call": string; + /** the snapshot's request: the id of the request the keeper took it for, in its state requests */ + "request": string; +} + +/** is what snapshot-get answers. */ +export interface SnapshotGetAnswer { + /** when the snapshot was taken, RFC 3339 */ + "at"?: string; + /** how many chunks are sent; 0 when the caller is granted no chunk subjects */ + "chunks"?: number; + /** sha256: of the file's bytes */ + "digest"?: string; + /** why not: snapshot damaged, snapshot missing, snapshot protected or snapshot taken before milestone G; set alone */ + "error"?: string; + /** the entry's local name */ + "local"?: string; + "module"?: string; + "request"?: string; + "size"?: number; + /** the stream's name on the bus */ + "stream"?: string; +} + +/** is what snapshot-restore takes. */ +export interface SnapshotRestoreInput { + /** the snapshot's request: the id of the request the keeper took it for, in its state requests */ + "request": string; + /** check the file against its digest and restore nothing */ + "verify"?: boolean; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what snapshot-restore answers. */ +export interface SnapshotRestoreAnswer { + /** accepted: the act's id */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue */ + "busy"?: string; + /** why not; set alone */ + "error"?: string; +} + +/** is what snapshot-restore-cancel takes. */ +export interface SnapshotRestoreCancelInput { + /** the restore's act id */ + "act": string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what snapshot-restore-cancel answers. */ +export interface SnapshotRestoreCancelAnswer { + /** accepted: the act's id */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue */ + "busy"?: string; + /** why not; set alone */ + "error"?: string; +} + +/** is what snapshot-remove takes. */ +export interface SnapshotRemoveInput { + /** true: every snapshot past snapshot-keep-days */ + "expired"?: boolean; + /** the snapshot's request; or expired true, not both */ + "request"?: string; + /** why, which the hand-act log keeps */ + "why": string; +} + +/** is what snapshot-remove answers. */ +export interface SnapshotRemoveAnswer { + /** accepted: the act's id */ + "accepted"?: string; + /** busy: the id of the act that runs; it keeps no queue */ + "busy"?: string; + /** why not; set alone */ + "error"?: string; +} + /** is the body of the event created. */ export type CreatedEvent = Said; @@ -295,6 +391,15 @@ export type RecreatedEvent = Said; /** is the body of the event dropped. */ export type DroppedEvent = Said; +/** is the body of the event snapshot-restored. */ +export interface SnapshotRestoredEvent { + "act": string; + /** when failed */ + "error"?: string; + "outcome": "done" | "failed"; + "request": string; +} + /** is the form of the provision bus-state. */ export type BusStateForm = Binding; diff --git a/ts/seats/meshbroker/index.js b/ts/seats/meshbroker/index.js index 89d30fb..db58b3e 100644 --- a/ts/seats/meshbroker/index.js +++ b/ts/seats/meshbroker/index.js @@ -13,6 +13,10 @@ export const verbs = { apply: "apply", recreate: "recreate", drop: "drop", + snapshotGet: "snapshot-get", + snapshotRestore: "snapshot-restore", + snapshotRestoreCancel: "snapshot-restore-cancel", + snapshotRemove: "snapshot-remove", }; export const events = { @@ -25,6 +29,7 @@ export const events = { orphaned: "orphaned", recreated: "recreated", dropped: "dropped", + snapshotRestored: "snapshot-restored", }; export const family = { name: "mesh-broker.events", maxAgeDays: 7 }; @@ -47,3 +52,11 @@ export const recreatedSubject = "mesh.seat.mesh-broker.event.recreated"; export const droppedSubject = "mesh.seat.mesh-broker.event.dropped"; +export const snapshotRestoredStream = "SEAT_mesh-broker_snapshot-restored"; + +export function snapshotRestoredSubject(request, act) { + return "mesh.seat.mesh-broker.event.snapshot-restored." + request + "." + act; +} + +export const snapshotRestoredSubjectAll = "mesh.seat.mesh-broker.event.snapshot-restored.*.*"; + From c5cf0126f99907f014a68c0cc4fa4f8075c6e7a1 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 22:46:44 +0100 Subject: [PATCH 45/62] K27 (owner change): the seat mesh-conditions' condition-changed gains the change value owner MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §540, §685, A-58 (findings-stated's kinds, §580, and attempt-changed, §541/§665, were built by K13 and K12; seatgen -check clean) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../go/clients/meshconditionsclient/client.go | 1 + .../meshconditionsclient/client_test.go | 3 ++- .../go/seats/meshconditions/contract.go | 1 + .../go/seats/meshconditions/contract_test.go | 2 ++ .../mesh-conditions/fixtures/events.json | 24 +++++++++++++++++++ .../seats/mesh-conditions/seat.json | 3 ++- .../ts/seats/meshconditions/index.d.ts | 2 +- 7 files changed, 33 insertions(+), 3 deletions(-) diff --git a/health-and-repair/go/clients/meshconditionsclient/client.go b/health-and-repair/go/clients/meshconditionsclient/client.go index c2fbc08..cf309d5 100644 --- a/health-and-repair/go/clients/meshconditionsclient/client.go +++ b/health-and-repair/go/clients/meshconditionsclient/client.go @@ -72,6 +72,7 @@ const ( ChangeUnsilenced = "silence-ended" ChangeCleared = "cleared" ChangeWords = "words" + ChangeOwner = "owner" ) var unsafeKey = regexp.MustCompile(`[^A-Za-z0-9_=/-]`) diff --git a/health-and-repair/go/clients/meshconditionsclient/client_test.go b/health-and-repair/go/clients/meshconditionsclient/client_test.go index f377f6d..768d24b 100644 --- a/health-and-repair/go/clients/meshconditionsclient/client_test.go +++ b/health-and-repair/go/clients/meshconditionsclient/client_test.go @@ -32,7 +32,8 @@ func TestAFindingsKeyAndTheOrderOfConditions(t *testing.T) { t.Error("silence is until its end") } if EventFor(ChangeReopened) != seat.EventConditionRaised || EventFor(ChangeSilenced) != seat.EventConditionChanged || - EventFor(ChangeCleared) != seat.EventConditionCleared { + EventFor(ChangeCleared) != seat.EventConditionCleared || EventFor(ChangeOwner) != seat.EventConditionChanged || + ChangeOwner != seat.ConditionEventChangeOwner { t.Error("a change is said as its event") } if a := SilenceAction("k"); a.Verb != "mesh-conditions.silence" || ShowKeeper("k") != "mesh-conditions.conditions key=k" { diff --git a/health-and-repair/go/seats/meshconditions/contract.go b/health-and-repair/go/seats/meshconditions/contract.go index f07e37f..4772056 100644 --- a/health-and-repair/go/seats/meshconditions/contract.go +++ b/health-and-repair/go/seats/meshconditions/contract.go @@ -264,6 +264,7 @@ const ( ConditionEventChangeSilenceEnded = "silence-ended" ConditionEventChangeCleared = "cleared" ConditionEventChangeWords = "words" + ConditionEventChangeOwner = "owner" ) // The values of ConditionEvent's severity. diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index ea0fedb..59c5275 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -23,6 +23,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")}, + {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:jochen\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:jochen\"}", + decode: func(b []byte) (any, error) { var v ConditionChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-changed$")}, {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", diff --git a/health-and-repair/seats/mesh-conditions/fixtures/events.json b/health-and-repair/seats/mesh-conditions/fixtures/events.json index eebbd31..e6fbff3 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/events.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/events.json @@ -42,5 +42,29 @@ "at": "2026-11-11T10:00:00Z", "change": "raised" } + }, + { + "name": "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", + "of": "event:condition-changed", + "subject": "mesh.seat.mesh-conditions.event.condition-changed", + "given": { + "key": "module.mesh-delivery.ace.pipeline-failed", + "kind": "pipeline-failed", + "subject": { + "scope": "module", + "id": "mesh-delivery.ace", + "machine": "ace" + }, + "severity": "warning", + "summary": "a head failed its pipeline", + "source": "runner", + "resolver": "self", + "owner": "operator-channel", + "waiting-on": "operator-channel", + "event": "condition-changed", + "at": "2026-11-11T12:00:00Z", + "change": "owner", + "was": "forge:jochen" + } } ] diff --git a/health-and-repair/seats/mesh-conditions/seat.json b/health-and-repair/seats/mesh-conditions/seat.json index e5d45a8..256519b 100644 --- a/health-and-repair/seats/mesh-conditions/seat.json +++ b/health-and-repair/seats/mesh-conditions/seat.json @@ -651,7 +651,8 @@ "silenced", "silence-ended", "cleared", - "words" + "words", + "owner" ] }, "was": { diff --git a/health-and-repair/ts/seats/meshconditions/index.d.ts b/health-and-repair/ts/seats/meshconditions/index.d.ts index 22c4ea8..3deca6b 100644 --- a/health-and-repair/ts/seats/meshconditions/index.d.ts +++ b/health-and-repair/ts/seats/meshconditions/index.d.ts @@ -86,7 +86,7 @@ export interface ConditionEventTriedItem { export interface ConditionEvent { "actions"?: Action[]; "at": string; - "change": "raised" | "reopened" | "severity" | "resolver" | "silenced" | "silence-ended" | "cleared" | "words"; + "change": "raised" | "reopened" | "severity" | "resolver" | "silenced" | "silence-ended" | "cleared" | "words" | "owner"; "cleared"?: string; "count"?: number; "epoch"?: number; From b0be30c267667ee401b7e77d6866e5845b1827e0 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 22:58:13 +0100 Subject: [PATCH 46/62] Contract: the seat mesh-module-assigner gains the read verb placement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G A-62 (§704, §402) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshmoduleassigner/contract.go | 21 +++++++++- seats/mesh-module-assigner/seat.json | 52 +++++++++++++++++++++++++ ts/seats/meshmoduleassigner/index.d.ts | 19 +++++++++ ts/seats/meshmoduleassigner/index.js | 1 + 4 files changed, 92 insertions(+), 1 deletion(-) diff --git a/go/seats/meshmoduleassigner/contract.go b/go/seats/meshmoduleassigner/contract.go index 2451180..e8a5beb 100644 --- a/go/seats/meshmoduleassigner/contract.go +++ b/go/seats/meshmoduleassigner/contract.go @@ -20,6 +20,7 @@ const ( VerbPropose = "propose" VerbWithdraw = "withdraw" VerbAgain = "again" + VerbPlacement = "placement" ) const ( @@ -31,7 +32,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbAssignments, VerbProposals, VerbPropose, VerbWithdraw, VerbAgain} + return []string{VerbAssignments, VerbProposals, VerbPropose, VerbWithdraw, VerbAgain, VerbPlacement} } // Events is every event published on the seat's subject: a new copy each call. @@ -401,6 +402,12 @@ type Holding struct { Site string `json:"site,omitempty"` } +// ModulePlacement is the nodes that run a module from one watched branch. +type ModulePlacement struct { + Branch string `json:"branch"` + Nodes []string `json:"nodes"` +} + // NodeDecided is what a person decides of a node; no secret and no key material. type NodeDecided struct { Account string `json:"account,omitempty"` @@ -624,6 +631,18 @@ type AgainInput struct { // AgainAnswer is what again answers. type AgainAnswer = map[string]any +// PlacementInput is what placement takes. +type PlacementInput struct { + // the module + Module string `json:"module"` +} + +// PlacementAnswer is what placement answers. +type PlacementAnswer struct { + // one per branch, the nodes that run the module from it + Placements []ModulePlacement `json:"placements"` +} + // AssignmentsProposedEvent is the body of the event assignments-proposed. type AssignmentsProposedEvent = AssignmentsEvent diff --git a/seats/mesh-module-assigner/seat.json b/seats/mesh-module-assigner/seat.json index 247f86b..09eb93b 100644 --- a/seats/mesh-module-assigner/seat.json +++ b/seats/mesh-module-assigner/seat.json @@ -154,6 +154,39 @@ "type": "object", "description": "what was judged or asked again" } + }, + { + "name": "placement", + "description": "Read the placements of one module as the assignments rows hold them: for each watched branch a node runs it from, the nodes that run it from there.", + "optional": true, + "input": { + "properties": { + "module": { + "description": "the module", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + }, + "answer": { + "properties": { + "placements": { + "type": "array", + "items": { + "$ref": "#/defs/ModulePlacement" + }, + "description": "one per branch, the nodes that run the module from it" + } + }, + "required": [ + "placements" + ], + "type": "object" + }, + "class": "read" } ], "events": [ @@ -1009,6 +1042,25 @@ "scope", "holders" ] + }, + "ModulePlacement": { + "type": "object", + "description": "the nodes that run a module from one watched branch", + "properties": { + "branch": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "branch", + "nodes" + ] } } } diff --git a/ts/seats/meshmoduleassigner/index.d.ts b/ts/seats/meshmoduleassigner/index.d.ts index b0f6280..44beeef 100644 --- a/ts/seats/meshmoduleassigner/index.d.ts +++ b/ts/seats/meshmoduleassigner/index.d.ts @@ -10,6 +10,7 @@ export declare const verbs: { readonly propose: "propose"; readonly withdraw: "withdraw"; readonly again: "again"; + readonly placement: "placement"; }; export declare const events: { @@ -143,6 +144,12 @@ export interface Holding { "site"?: string; } +/** the nodes that run a module from one watched branch */ +export interface ModulePlacement { + "branch": string; + "nodes": string[]; +} + /** what a person decides of a node; no secret and no key material */ export interface NodeDecided { "account"?: string; @@ -353,6 +360,18 @@ export interface AgainInput { /** is what again answers. */ export type AgainAnswer = Record; +/** is what placement takes. */ +export interface PlacementInput { + /** the module */ + "module": string; +} + +/** is what placement answers. */ +export interface PlacementAnswer { + /** one per branch, the nodes that run the module from it */ + "placements": ModulePlacement[]; +} + /** is the body of the event assignments-proposed. */ export type AssignmentsProposedEvent = AssignmentsEvent; diff --git a/ts/seats/meshmoduleassigner/index.js b/ts/seats/meshmoduleassigner/index.js index 654af67..32f20bf 100644 --- a/ts/seats/meshmoduleassigner/index.js +++ b/ts/seats/meshmoduleassigner/index.js @@ -10,6 +10,7 @@ export const verbs = { propose: "propose", withdraw: "withdraw", again: "again", + placement: "placement", }; export const events = { From e5b3a894303a259be8ba9f58a40325aba1827c2c Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 23:27:19 +0100 Subject: [PATCH 47/62] A-91: the operator-channel contract's asks value carries the ask's warrant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §700, A-91; the router's record carries its warrant Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../clients/operatorchannelclient/client.go | 5 +---- .../operatorchannelclient/client_test.go | 13 ++++++++++++ .../go/seats/operatorchannel/contract.go | 3 ++- .../go/seats/operatorchannel/contract_test.go | 2 ++ .../operator-channel/fixtures/states.json | 21 +++++++++++++++++++ .../seats/operator-channel/seat.json | 3 +++ .../ts/seats/operatorchannel/index.d.ts | 1 + 7 files changed, 43 insertions(+), 5 deletions(-) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client.go b/operator-and-conversation/go/clients/operatorchannelclient/client.go index 4acd445..01f974e 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client.go @@ -106,10 +106,7 @@ func (c *Client) Where(id string) (state string, w *seat.Warrant, err error) { if err != nil || e == nil { return "", nil, err } - var rec struct { - State string `json:"state"` - Warrant *seat.Warrant `json:"warrant"` - } + var rec seat.AsksByAskerIDValue if err := json.Unmarshal(e.Value, &rec); err != nil { return "", nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err) } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 2007142..02d6bb0 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -175,3 +175,16 @@ func TestAKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere(t *t } } } + +// Design 47 G §700, A-91: Where reads the router's record as the contract's typed value, its warrant included. +func TestWhereReadsTheRecordsWarrantTyped(t *testing.T) { + c, _ := client() + rec := seat.AsksByAskerIDValue{Key: "an-asker.d-1", Asker: "an-asker", State: "chosen", + Warrant: &seat.Warrant{Ask: "d-1", Asker: "an-asker", Outcome: seat.WarrantOutcomeChosen, Option: "ok"}} + raw, _ := json.Marshal(rec) + c.Record = func(string) (*stdio.StateEntry, error) { return &stdio.StateEntry{Value: raw}, nil } + state, w, err := c.Where("d-1") + if err != nil || state != "chosen" || w == nil || w.Option != "ok" { + t.Fatalf("Where = %q, %+v, %v; want chosen and the record's warrant", state, w, err) + } +} diff --git a/operator-and-conversation/go/seats/operatorchannel/contract.go b/operator-and-conversation/go/seats/operatorchannel/contract.go index c27e0c9..f936017 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract.go @@ -541,5 +541,6 @@ type AsksByAskerIDValue struct { // when it was opened, RFC 3339 Opened string `json:"opened"` // how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused - State string `json:"state"` + State string `json:"state"` + Warrant *Warrant `json:"warrant,omitempty"` } diff --git a/operator-and-conversation/go/seats/operatorchannel/contract_test.go b/operator-and-conversation/go/seats/operatorchannel/contract_test.go index c389b3e..7a2e7bd 100644 --- a/operator-and-conversation/go/seats/operatorchannel/contract_test.go +++ b/operator-and-conversation/go/seats/operatorchannel/contract_test.go @@ -39,6 +39,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "an ask the router refused at take-in, closed (design 47 G 570)", subject: "", given: "{\"answer\":\"refused: its expiry passes the bound of its highest option level\",\"asker\":\"nats\",\"asker_told\":true,\"at\":\"2026-11-11T10:00:01Z\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Recreate a bus entry\",\"key\":\"nats.r-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"refused\"}", wire: "{\"answer\":\"refused: its expiry passes the bound of its highest option level\",\"asker\":\"nats\",\"asker_told\":true,\"at\":\"2026-11-11T10:00:01Z\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Recreate a bus entry\",\"key\":\"nats.r-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"refused\"}", decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "an ask chosen, with its warrant in the router's record (design 47 G 700, A-91)", subject: "", given: "{\"asker\":\"mesh-delivery-pipeline\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Deliver a module?\",\"key\":\"mesh-delivery-pipeline.approval-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"chosen\",\"warrant\":{\"about\":\"mod.main\",\"ask\":\"approval-1\",\"ask-digest\":\"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-11T10:05:00Z\",\"option\":\"approve\",\"outcome\":\"chosen\"}}", wire: "{\"asker\":\"mesh-delivery-pipeline\",\"expires\":\"2026-11-12T10:00:00Z\",\"headline\":\"Deliver a module?\",\"key\":\"mesh-delivery-pipeline.approval-1\",\"opened\":\"2026-11-11T10:00:00Z\",\"state\":\"chosen\",\"warrant\":{\"about\":\"mod.main\",\"ask\":\"approval-1\",\"ask-digest\":\"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-11T10:05:00Z\",\"option\":\"approve\",\"outcome\":\"chosen\"}}", + decode: func(b []byte) (any, error) { var v AsksByAskerIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "notify asks the message sent on every channel", subject: "", given: "{\"every-channel\":true,\"key\":\"widens.mesh-delivery\",\"severity\":\"warning\",\"subject\":\"mesh-delivery\",\"summary\":\"a change widens what a module may do\"}", wire: "{\"every-channel\":true,\"key\":\"widens.mesh-delivery\",\"severity\":\"warning\",\"subject\":\"mesh-delivery\",\"summary\":\"a change widens what a module may do\"}", decode: func(b []byte) (any, error) { var v NotifyInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } diff --git a/operator-and-conversation/seats/operator-channel/fixtures/states.json b/operator-and-conversation/seats/operator-channel/fixtures/states.json index 36e8ba0..f9c9f15 100644 --- a/operator-and-conversation/seats/operator-channel/fixtures/states.json +++ b/operator-and-conversation/seats/operator-channel/fixtures/states.json @@ -60,5 +60,26 @@ "opened": "2026-11-11T10:00:00Z", "state": "refused" } + }, + { + "name": "an ask chosen, with its warrant in the router's record (design 47 G 700, A-91)", + "of": "state:asks/.", + "given": { + "asker": "mesh-delivery-pipeline", + "expires": "2026-11-12T10:00:00Z", + "headline": "Deliver a module?", + "key": "mesh-delivery-pipeline.approval-1", + "opened": "2026-11-11T10:00:00Z", + "state": "chosen", + "warrant": { + "about": "mod.main", + "ask": "approval-1", + "ask-digest": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "asker": "mesh-delivery-pipeline", + "at": "2026-11-11T10:05:00Z", + "option": "approve", + "outcome": "chosen" + } + } } ] diff --git a/operator-and-conversation/seats/operator-channel/seat.json b/operator-and-conversation/seats/operator-channel/seat.json index 31f7db8..3c44a1b 100644 --- a/operator-and-conversation/seats/operator-channel/seat.json +++ b/operator-and-conversation/seats/operator-channel/seat.json @@ -312,6 +312,9 @@ "type": "string", "description": "when the ask was held back, RFC 3339; present while its state is held-back" }, + "warrant": { + "$ref": "#/defs/Warrant" + }, "answer": { "type": "string", "description": "how it ended, in words" diff --git a/operator-and-conversation/ts/seats/operatorchannel/index.d.ts b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts index 3f91344..735429f 100644 --- a/operator-and-conversation/ts/seats/operatorchannel/index.d.ts +++ b/operator-and-conversation/ts/seats/operatorchannel/index.d.ts @@ -442,5 +442,6 @@ export interface AsksByAskerIDValue { "opened": string; /** how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused */ "state": string; + "warrant"?: Warrant; } From 2ae0c679304b828a3973dd23ecd19861577d141d Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 23:44:36 +0100 Subject: [PATCH 48/62] G A-92: the node-engine's seat definition gains the state bounds, key ., in its old section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §560, §557, §627, A-77, A-92 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/nodeengine/contract.go | 46 ++++++++++++++++++++++++++ go/seats/nodeengine/contract_test.go | 2 ++ seats/node-engine/fixtures/states.json | 9 +++++ seats/node-engine/seat.json | 33 ++++++++++++++++++ ts/seats/nodeengine/index.d.ts | 16 +++++++++ ts/seats/nodeengine/index.js | 20 +++++++++++ 6 files changed, 126 insertions(+) diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 79347cb..825e95e 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -121,6 +121,7 @@ const ( StatePackages = "packages" StateHealth = "health" StateFindings = "findings" + StateBounds = "bounds" ) // HaveByNodeModuleKey is the key of one value of the state have under the form ".". @@ -393,6 +394,42 @@ func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) { return v, nil } +// BoundsByWhatIDKey is the key of one value of the state bounds under the form ".". +func BoundsByWhatIDKey(what, id string) string { return what + "." + id } + +// ParseBoundsByWhatIDKey reads the parts of a key of the form ".", in the order of the form; the last result is false for a key of another form. +func ParseBoundsByWhatIDKey(key string) (string, string, bool) { + rest := key + v0, after0, found0 := strings.Cut(rest, ".") + if !found0 || v0 == "" { + return "", "", false + } + rest = after0 + if rest == "" { + return "", "", false + } + v2 := rest + rest = "" + if rest != "" { + return "", "", false + } + return v0, v2, true +} + +// DecodeBoundsByWhatIDValue reads one value of the state bounds under the form ".", refusing a field BoundsByWhatIDValue does not know and any text after the value. +func DecodeBoundsByWhatIDValue(raw []byte) (BoundsByWhatIDValue, error) { + var v BoundsByWhatIDValue + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + if err := dec.Decode(&v); err != nil { + return v, err + } + if dec.More() { + return v, errors.New("text after the value") + } + return v, nil +} + // AccountsHanded is the hashes of the users of the list, sealed to the vault. type AccountsHanded struct { // when @@ -1684,3 +1721,12 @@ const ( FindingsByKeyValueSeverityUrgent = "urgent" FindingsByKeyValueSeverityWarning = "warning" ) + +// BoundsByWhatIDValue is one value of the state bounds under the key .. +type BoundsByWhatIDValue struct { + Module string `json:"module,omitempty"` + // when the wait began, RFC 3339 + Since string `json:"since"` + // layout version, 1 + V int64 `json:"v"` +} diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index b3285b5..be4495f 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -93,6 +93,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v HealthByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a have that waits for the recovery module, with its wait, ask-at and act (design 47 G 560, 629)", subject: "", given: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}", wire: "{\"detail\":\"waiting for a restore point\",\"fp\":\"0123456789ab\",\"health\":\"waits\",\"phase\":\"held\",\"v\":1,\"wait\":{\"act\":\"a-20261111t100000\",\"ask-at\":\"2026-11-11T10:00:00Z\",\"bound\":\"90m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"on\":\"the recovery module's ended\",\"owner\":\"node-engine\",\"reason\":\"recovery wait\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\",\"words\":\"waiting for the point of postgres's data\"}}", decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "a bound of a wait on the recovery module's restore point", subject: "", given: "{\"module\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T14:00:00Z\",\"v\":1}", wire: "{\"module\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T14:00:00Z\",\"v\":1}", + decode: func(b []byte) (any, error) { var v BoundsByWhatIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "manifest-reads answers what the engine reads and when it stated it", subject: "", given: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}", wire: "{\"manifest-reads\":[\"form:seat-reference\",\"word:series\"],\"node\":\"ace\",\"stated-at\":\"2026-11-04T10:00:00Z\",\"v\":1}", decode: func(b []byte) (any, error) { var v ManifestReadsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "manifest-reads of an engine built before it said them is the baseline", subject: "", given: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}", wire: "{\"node\":\"g14\",\"stated-at\":\"2026-11-04T10:05:00Z\",\"v\":1}", diff --git a/seats/node-engine/fixtures/states.json b/seats/node-engine/fixtures/states.json index aa0ae83..db64100 100644 --- a/seats/node-engine/fixtures/states.json +++ b/seats/node-engine/fixtures/states.json @@ -538,5 +538,14 @@ }, "health": "waits" } + }, + { + "name": "a bound of a wait on the recovery module's restore point", + "of": "state:bounds/.", + "given": { + "v": 1, + "since": "2026-11-11T14:00:00Z", + "module": "mesh-delivery-assigner" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 19a8dd5..3225f06 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -1596,6 +1596,39 @@ } ], "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine..seat-list-unread`" + }, + { + "name": "bounds", + "template": "state", + "writer": "holder", + "history": 1, + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", + "properties": { + "v": { + "type": "integer", + "description": "layout version, 1" + }, + "since": { + "type": "string", + "description": "when the wait began, RFC 3339" + }, + "module": { + "type": "string" + } + }, + "required": [ + "v", + "since" + ] + } + } + ], + "description": "the bounds of the node-engine's waits, each a key . with its own time to live (design 47 G A-92)" } ], "defs": { diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index c34cace..8eeb44e 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -74,6 +74,7 @@ export declare const states: { readonly packages: "packages"; readonly health: "health"; readonly findings: "findings"; + readonly bounds: "bounds"; }; /** The key of one value of the state have under the form ".". */ @@ -124,6 +125,12 @@ export declare function findingsByKeyKey(key: string): string; /** The parts of a key of the form "", or undefined for a key of another form. */ export declare function parseFindingsByKeyKey(_key: string): { key: string } | undefined; +/** The key of one value of the state bounds under the form ".". */ +export declare function boundsByWhatIDKey(what: string, id: string): string; + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export declare function parseBoundsByWhatIDKey(_key: string): { what: string; id: string } | undefined; + /** the hashes of the users of the list, sealed to the vault */ export interface AccountsHanded { /** when */ @@ -1297,3 +1304,12 @@ export interface FindingsByKeyValue { "v": number; } +/** is one value of the state bounds under the key .. */ +export interface BoundsByWhatIDValue { + "module"?: string; + /** when the wait began, RFC 3339 */ + "since": string; + /** layout version, 1 */ + "v": number; +} + diff --git a/ts/seats/nodeengine/index.js b/ts/seats/nodeengine/index.js index 2c527bf..1ce11bb 100644 --- a/ts/seats/nodeengine/index.js +++ b/ts/seats/nodeengine/index.js @@ -90,6 +90,7 @@ export const states = { packages: "packages", health: "health", findings: "findings", + bounds: "bounds", }; /** The key of one value of the state have under the form ".". */ @@ -230,3 +231,22 @@ export function parseFindingsByKeyKey(_key) { return { key }; } +/** The key of one value of the state bounds under the form ".". */ +export function boundsByWhatIDKey(what, id) { + return what + "." + id; +} + +/** The parts of a key of the form ".", or undefined for a key of another form. */ +export function parseBoundsByWhatIDKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf("."); + if (_at0 <= 0) return undefined; + const what = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 1); + if (_rest === "") return undefined; + const id = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { what, id }; +} + From b58c4e6b1413b717e23b198cc5a13533550adc67 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 01:06:05 +0100 Subject: [PATCH 49/62] G A-117: the seat mesh-recovery's ended and restored events gain why, the hand act's words for a cancel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G A-117, §560 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshrecovery/contract.go | 4 ++++ go/seats/meshrecovery/contract_test.go | 2 ++ seats/mesh-recovery/fixtures/events.json | 14 ++++++++++++++ seats/mesh-recovery/seat.json | 8 ++++++++ ts/seats/meshrecovery/index.d.ts | 4 ++++ 5 files changed, 32 insertions(+) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go index 4f1846e..b9e28c3 100644 --- a/go/seats/meshrecovery/contract.go +++ b/go/seats/meshrecovery/contract.go @@ -449,6 +449,8 @@ type EndedEvent struct { Outcome string `json:"outcome"` Size int64 `json:"size,omitempty"` Snapshot string `json:"snapshot,omitempty"` + // the words of the hand act that ended it, for a cancel (design 47 G A-117, 560) + Why string `json:"why,omitempty"` } // The values of EndedEvent's outcome. @@ -487,6 +489,8 @@ type RestoredEvent struct { // how the act ended Outcome string `json:"outcome"` Snapshot string `json:"snapshot,omitempty"` + // the words of the hand act that ended it, for a cancel (design 47 G A-117, 560) + Why string `json:"why,omitempty"` } // The values of RestoredEvent's outcome. diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 8d7277d..346c550 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -25,6 +25,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restore-started\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "restored is said", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", wire: "{\"act\":\"a-3\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"restore point missing\",\"kept\":\"ledger\",\"missing\":true,\"module\":\"mesh-knowledge\",\"outcome\":\"failed\"}", decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "a cancelled act says the hand act's why", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}", + decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "set-aside is said", subject: "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", decode: func(b []byte) (any, error) { var v SetAsideEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.set-aside\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "aside-discarded is said", subject: "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", given: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", diff --git a/seats/mesh-recovery/fixtures/events.json b/seats/mesh-recovery/fixtures/events.json index 2b13fb8..724aefb 100644 --- a/seats/mesh-recovery/fixtures/events.json +++ b/seats/mesh-recovery/fixtures/events.json @@ -72,6 +72,20 @@ "missing": true } }, + { + "name": "a cancelled act says the hand act's why", + "of": "event:restored", + "subject": "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", + "given": { + "act": "a-4", + "at": "2026-11-11T10:00:00Z", + "module": "mesh-knowledge", + "kept": "ledger", + "outcome": "failed", + "error": "cancelled", + "why": "the operator stopped it to look at the disk" + } + }, { "name": "set-aside is said", "of": "event:set-aside", diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json index 31fff7a..ded2e60 100644 --- a/seats/mesh-recovery/seat.json +++ b/seats/mesh-recovery/seat.json @@ -669,6 +669,10 @@ "type": "string", "description": "when failed" }, + "why": { + "type": "string", + "description": "the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)" + }, "consumers": { "type": "array", "items": { @@ -788,6 +792,10 @@ "error": { "type": "string" }, + "why": { + "type": "string", + "description": "the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)" + }, "aside": { "$ref": "#/defs/Aside" }, diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts index fda42f1..292c4e1 100644 --- a/ts/seats/meshrecovery/index.d.ts +++ b/ts/seats/meshrecovery/index.d.ts @@ -399,6 +399,8 @@ export interface EndedEvent { "outcome": "done" | "failed"; "size"?: number; "snapshot"?: string; + /** the words of the hand act that ended it, for a cancel (design 47 G A-117, 560) */ + "why"?: string; } /** is the body of the event restore-started. */ @@ -431,6 +433,8 @@ export interface RestoredEvent { /** how the act ended */ "outcome": "done" | "failed"; "snapshot"?: string; + /** the words of the hand act that ended it, for a cancel (design 47 G A-117, 560) */ + "why"?: string; } /** is the body of the event set-aside. */ From e3520750d5ca87d08387fcf9a607436d60bf464d Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 01:17:22 +0100 Subject: [PATCH 50/62] G A-124: the seat mesh-recovery's aside says names, a list of the bus names it was live under MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G A-124, §516, §560 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshrecovery/contract.go | 22 ++++++++------- go/seats/meshrecovery/contract_test.go | 6 ++--- seats/mesh-recovery/fixtures/events.json | 12 ++++++--- seats/mesh-recovery/fixtures/verbs.json | 6 +++-- seats/mesh-recovery/seat.json | 34 +++++++++++++++++------- ts/seats/meshrecovery/index.d.ts | 10 ++++--- 6 files changed, 57 insertions(+), 33 deletions(-) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go index b9e28c3..735d240 100644 --- a/go/seats/meshrecovery/contract.go +++ b/go/seats/meshrecovery/contract.go @@ -124,8 +124,8 @@ const SubjectExpiryEnded = "mesh.seat.mesh-recovery.event.expiry-ended" type Aside struct { // the directory's name ID string `json:"id"` - // the bus name it was live under - Name string `json:"name"` + // the bus names it was live under, one per bus object + Names []string `json:"names"` // its bytes on disk Size int64 `json:"size"` } @@ -504,10 +504,11 @@ type SetAsideEvent struct { // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) Act string `json:"act"` // when it was said, RFC 3339 - At time.Time `json:"at"` - ID string `json:"id"` - Name string `json:"name"` - Size int64 `json:"size"` + At time.Time `json:"at"` + ID string `json:"id"` + // the bus names it was live under, one per bus object + Names []string `json:"names"` + Size int64 `json:"size"` } // AsideDiscardedEvent is the body of the event aside-discarded. @@ -515,10 +516,11 @@ type AsideDiscardedEvent struct { // the id the act was answered accepted with, or a hand act's own id (design 47 G 560) Act string `json:"act"` // when it was said, RFC 3339 - At time.Time `json:"at"` - ID string `json:"id"` - Name string `json:"name"` - Size int64 `json:"size"` + At time.Time `json:"at"` + ID string `json:"id"` + // the bus names it was live under, one per bus object + Names []string `json:"names"` + Size int64 `json:"size"` } // PointRemovedEvent is the body of the event point-removed. diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 346c550..05b8643 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -27,9 +27,9 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "a cancelled act says the hand act's why", subject: "mesh.seat.mesh-recovery.event.restored.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"error\":\"cancelled\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"outcome\":\"failed\",\"why\":\"the operator stopped it to look at the disk\"}", decode: func(b []byte) (any, error) { var v RestoredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.restored\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "set-aside is said", subject: "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", + {name: "set-aside is said", subject: "mesh.seat.mesh-recovery.event.set-aside.mesh-knowledge.ledger", given: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", wire: "{\"act\":\"a-4\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", decode: func(b []byte) (any, error) { var v SetAsideEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.set-aside\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "aside-discarded is said", subject: "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", given: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", wire: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}", + {name: "aside-discarded is said", subject: "mesh.seat.mesh-recovery.event.aside-discarded.mesh-knowledge.ledger", given: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", wire: "{\"act\":\"a-5\",\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}", decode: func(b []byte) (any, error) { var v AsideDiscardedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.aside-discarded\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "point-removed is said", subject: "mesh.seat.mesh-recovery.event.point-removed.mesh-knowledge.ledger", given: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}", wire: "{\"act\":\"a-6\",\"at\":\"2026-11-11T10:00:00Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"1-aaaaaaaaaaaa\"}", decode: func(b []byte) (any, error) { var v PointRemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-recovery\\.event\\.point-removed\\.[^.*> ]+\\.[^.*> ]+$")}, @@ -45,7 +45,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-kept answers an error naming why", subject: "", given: "{\"error\":\"aside-only is the operator's hand tool alone\"}", wire: "{\"error\":\"aside-only is the operator's hand tool alone\"}", decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"name\":\"mesh-knowledge_ledger\",\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", + {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/seats/mesh-recovery/fixtures/events.json b/seats/mesh-recovery/fixtures/events.json index 724aefb..bfc390b 100644 --- a/seats/mesh-recovery/fixtures/events.json +++ b/seats/mesh-recovery/fixtures/events.json @@ -94,8 +94,10 @@ "act": "a-4", "at": "2026-11-11T10:00:00Z", "id": "20261111T121200Z", - "name": "mesh-knowledge_ledger", - "size": 4096 + "size": 4096, + "names": [ + "mesh-knowledge_ledger" + ] } }, { @@ -106,8 +108,10 @@ "act": "a-5", "at": "2026-11-11T10:00:00Z", "id": "20261111T121200Z", - "name": "mesh-knowledge_ledger", - "size": 4096 + "size": 4096, + "names": [ + "mesh-knowledge_ledger" + ] } }, { diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json index 65f5c8b..502c08e 100644 --- a/seats/mesh-recovery/fixtures/verbs.json +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -84,8 +84,10 @@ "asides": [ { "id": "20261111T121200Z", - "name": "mesh-knowledge_ledger", - "size": 4096 + "size": 4096, + "names": [ + "mesh-knowledge_ledger" + ] } ], "running": { diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json index ded2e60..d748d33 100644 --- a/seats/mesh-recovery/seat.json +++ b/seats/mesh-recovery/seat.json @@ -836,8 +836,13 @@ "id": { "type": "string" }, - "name": { - "type": "string" + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 }, "size": { "type": "integer", @@ -848,7 +853,7 @@ "act", "at", "id", - "name", + "names", "size" ] } @@ -876,8 +881,13 @@ "id": { "type": "string" }, - "name": { - "type": "string" + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 }, "size": { "type": "integer", @@ -888,7 +898,7 @@ "act", "at", "id", - "name", + "names", "size" ] } @@ -1082,9 +1092,13 @@ "type": "string", "description": "the directory's name" }, - "name": { - "type": "string", - "description": "the bus name it was live under" + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 }, "size": { "type": "integer", @@ -1094,7 +1108,7 @@ }, "required": [ "id", - "name", + "names", "size" ] }, diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts index 292c4e1..1096439 100644 --- a/ts/seats/meshrecovery/index.d.ts +++ b/ts/seats/meshrecovery/index.d.ts @@ -74,8 +74,8 @@ export declare const expiryEndedSubject: "mesh.seat.mesh-recovery.event.expiry-e export interface Aside { /** the directory's name */ "id": string; - /** the bus name it was live under */ - "name": string; + /** the bus names it was live under, one per bus object */ + "names": string[]; /** its bytes on disk */ "size": number; } @@ -444,7 +444,8 @@ export interface SetAsideEvent { /** when it was said, RFC 3339 */ "at": string; "id": string; - "name": string; + /** the bus names it was live under, one per bus object */ + "names": string[]; "size": number; } @@ -455,7 +456,8 @@ export interface AsideDiscardedEvent { /** when it was said, RFC 3339 */ "at": string; "id": string; - "name": string; + /** the bus names it was live under, one per bus object */ + "names": string[]; "size": number; } From 630de8babcb5fbf3a04f45c39bca183a7abb9e34 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 01:29:07 +0100 Subject: [PATCH 51/62] G A-129: the seat mesh-recovery's kept-points answers unrestored MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The asides whose record ended at removed with no running act holding them, which the recovery module's health check fails on, are listed in the answer the tool and the check read. Builds: design 47 G A-129, §554, §657 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshrecovery/contract.go | 2 ++ go/seats/meshrecovery/contract_test.go | 2 +- seats/mesh-recovery/fixtures/verbs.json | 11 ++++++++++- seats/mesh-recovery/seat.json | 10 +++++++++- ts/seats/meshrecovery/index.d.ts | 2 ++ 5 files changed, 24 insertions(+), 3 deletions(-) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go index 735d240..ecc32b3 100644 --- a/go/seats/meshrecovery/contract.go +++ b/go/seats/meshrecovery/contract.go @@ -246,6 +246,8 @@ type KeptPointsAnswer struct { Asides []Aside `json:"asides"` Points []Point `json:"points"` Running *Running `json:"running,omitempty"` + // the asides whose record ended at removed that no running act holds: the live data of those names is gone and only the aside holds it; the module's health check fails while one is listed (design 47 G 554, 657, A-129) + Unrestored []Aside `json:"unrestored"` } // RestoreAsideInput is what restore-aside takes. diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 05b8643..73857d6 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -45,7 +45,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-kept answers an error naming why", subject: "", given: "{\"error\":\"aside-only is the operator's hand tool alone\"}", wire: "{\"error\":\"aside-only is the operator's hand tool alone\"}", decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"}}", + {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json index 502c08e..a777fec 100644 --- a/seats/mesh-recovery/fixtures/verbs.json +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -95,7 +95,16 @@ "step": "waiting on the dump", "since": "2026-11-11T10:00:00Z", "waits-on": "item-ended of the bus item" - } + }, + "unrestored": [ + { + "id": "20261110T080000Z", + "size": 1024, + "names": [ + "mesh-knowledge_ledger" + ] + } + ] } }, { diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json index d748d33..78e88a9 100644 --- a/seats/mesh-recovery/seat.json +++ b/seats/mesh-recovery/seat.json @@ -174,11 +174,19 @@ }, "running": { "$ref": "#/defs/Running" + }, + "unrestored": { + "type": "array", + "description": "the asides whose record ended at removed that no running act holds: the live data of those names is gone and only the aside holds it; the module's health check fails while one is listed (design 47 G 554, 657, A-129)", + "items": { + "$ref": "#/defs/Aside" + } } }, "required": [ "points", - "asides" + "asides", + "unrestored" ] } }, diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts index 1096439..df35b04 100644 --- a/ts/seats/meshrecovery/index.d.ts +++ b/ts/seats/meshrecovery/index.d.ts @@ -196,6 +196,8 @@ export interface KeptPointsAnswer { "asides": Aside[]; "points": Point[]; "running"?: Running; + /** the asides whose record ended at removed that no running act holds: the live data of those names is gone and only the aside holds it; the module's health check fails while one is listed (design 47 G 554, 657, A-129) */ + "unrestored": Aside[]; } /** is what restore-aside takes. */ From 6be23459ab732b1d0a1958503cb412385bbfc8c8 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 04:59:29 +0100 Subject: [PATCH 52/62] A7: the contracts' fixtures and the tests generated from them name no operator account and no workstation (role names) Builds: the lead's handover item A7 (fixtures name no operator account or node); no design line names it Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/clients/meshconfigclient/client_test.go | 31 +++++++++++++++++++ go/seats/meshrecovery/contract_test.go | 14 ++++----- go/seats/nodeengine/contract_test.go | 2 +- .../clients/meshhandactsclient/client_test.go | 2 +- .../go/seats/meshconditions/contract_test.go | 14 ++++----- .../mesh-conditions/fixtures/events.json | 6 ++-- .../mesh-conditions/fixtures/states.json | 8 ++--- .../go/seats/meshgrants/contract_test.go | 2 +- .../seats/mesh-grants/fixtures/events.json | 2 +- seats/mesh-recovery/fixtures/verbs.json | 14 ++++----- seats/node-engine/fixtures/verbs.json | 2 +- 11 files changed, 64 insertions(+), 33 deletions(-) diff --git a/go/clients/meshconfigclient/client_test.go b/go/clients/meshconfigclient/client_test.go index ede862f..4e0fc06 100644 --- a/go/clients/meshconfigclient/client_test.go +++ b/go/clients/meshconfigclient/client_test.go @@ -1,6 +1,9 @@ package meshconfigclient import ( + "io/fs" + "os" + "path/filepath" "strings" "testing" ) @@ -43,3 +46,31 @@ func TestAHeldValueIsTheOneItsKeyNames(t *testing.T) { } } } + +// Design 47 G: the contracts' fixtures, and the tests generated from them, name no account of the operator and no node +// they run on: a role name stands for either (`operator`, `workstation`). +func TestFixturesNameNoOperatorAccountAndNoWorkstation(t *testing.T) { + root := "../../.." + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + slash := filepath.ToSlash(path) + if !strings.Contains(slash, "/fixtures/") && !strings.HasSuffix(slash, "/contract_test.go") || strings.Contains(slash, "node_modules") { + return nil + } + raw, err := os.ReadFile(path) + if err != nil { + return err + } + for _, word := range []string{"jochen", "shanks"} { + if strings.Contains(string(raw), word) { + t.Errorf("%s names %q: a fixture names the operator and the workstation by role", slash, word) + } + } + return nil + }) + if err != nil { + t.Fatal(err) + } +} diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 73857d6..7f8e825 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -47,17 +47,17 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", + {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"asker\":\"jochen@shanks\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"asker\":\"jochen@shanks\",\"why\":\"the dump waits too long\"}", + {name: "cancel names the act", subject: "", given: "{\"act\":\"a-1\",\"asker\":\"operator@workstation\",\"why\":\"the dump waits too long\"}", wire: "{\"act\":\"a-1\",\"asker\":\"operator@workstation\",\"why\":\"the dump waits too long\"}", decode: func(b []byte) (any, error) { var v CancelInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "take names the fingerprint whose form the point is taken at", subject: "", given: "{\"asker\":\"jochen@shanks\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + {name: "take names the fingerprint whose form the point is taken at", subject: "", given: "{\"asker\":\"operator@workstation\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"fingerprint\":\"0123456789ab\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", decode: func(b []byte) (any, error) { var v TakeInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "take answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", decode: func(b []byte) (any, error) { var v TakeAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "restore takes a point by its name", subject: "", given: "{\"asker\":\"jochen@shanks\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", + {name: "restore takes a point by its name", subject: "", given: "{\"asker\":\"operator@workstation\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"from-backup\":true,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"snapshot\":\"2-0123456789ab\",\"why\":\"the operator's hand act\"}", decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "restore takes a keeper's snapshot by its request", subject: "", given: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", + {name: "restore takes a keeper's snapshot by its request", subject: "", given: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"request\":\"r-20261111t100000\",\"why\":\"the operator's hand act\"}", decode: func(b []byte) (any, error) { var v RestoreInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore answers busy with the act that runs", subject: "", given: "{\"busy\":\"a-20261111t100000\"}", wire: "{\"busy\":\"a-20261111t100000\"}", decode: func(b []byte) (any, error) { var v RestoreAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, @@ -65,11 +65,11 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RetryInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "retry answers an error when nothing failed", subject: "", given: "{\"error\":\"nothing to retry\"}", wire: "{\"error\":\"nothing to retry\"}", decode: func(b []byte) (any, error) { var v RetryAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "aside sets the live kept data aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + {name: "aside sets the live kept data aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", decode: func(b []byte) (any, error) { var v AsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "aside answers accepted with the act", subject: "", given: "{\"accepted\":\"a-20261111t100000\"}", wire: "{\"accepted\":\"a-20261111t100000\"}", decode: func(b []byte) (any, error) { var v AsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "discard-aside names the aside", subject: "", given: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"jochen@shanks\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", + {name: "discard-aside names the aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", wire: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"the operator's hand act\"}", decode: func(b []byte) (any, error) { var v DiscardAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "discard-aside answers an error", subject: "", given: "{\"error\":\"no such aside\"}", wire: "{\"error\":\"no such aside\"}", decode: func(b []byte) (any, error) { var v DiscardAsideAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index be4495f..54880cf 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -121,7 +121,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v FirstViewsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "entry-again names the fingerprint and why", subject: "", given: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}", wire: "{\"fingerprint\":\"b3f1c9\",\"why\":\"the entry could not be read\"}", decode: func(b []byte) (any, error) { var v EntryAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "entry-again answers what was asked and where it is read", subject: "", given: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", wire: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", + {name: "entry-again answers what was asked and where it is read", subject: "", given: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@workstation\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", wire: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@workstation\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", decode: func(b []byte) (any, error) { var v EntryAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { diff --git a/health-and-repair/go/clients/meshhandactsclient/client_test.go b/health-and-repair/go/clients/meshhandactsclient/client_test.go index a4ac41d..f2e7074 100644 --- a/health-and-repair/go/clients/meshhandactsclient/client_test.go +++ b/health-and-repair/go/clients/meshhandactsclient/client_test.go @@ -16,7 +16,7 @@ import ( // recorder records through the seat alone, the controller's verbs being gone, and says loudly when nothing was recorded. func TestAnActIsRecordedInTheLogThatAnswers(t *testing.T) { // The shape of mesh-controller internal/link HandAct, as its bucket keeps an entry (handacts.go at 0fbb5ef3). - raw := `{"id":"act-1","at":"2026-10-28T09:00:00Z","by":"person.jochen","verb":"hand-act record","why":"a stuck consumer",` + + raw := `{"id":"act-1","at":"2026-10-28T09:00:00Z","by":"person.operator","verb":"hand-act record","why":"a stuck consumer",` + `"cause":"consumer-lost","condition":"bus.EVENTS.x.consumer-lost","via":"telegram","ask":"a-1","proofs":["P1"],` + `"requested-by":"bus.EVENTS.x.consumer-lost","outcome":"done"}` var a seat.Act diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index 59c5275..7a76c90 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -17,21 +17,21 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ - {name: "the keeper asks one observer to state its findings", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"module\":\"mesh-host\"}", wire: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"module\":\"mesh-host\"}", + {name: "the keeper asks one observer to state its findings", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"operator\",\"module\":\"mesh-host\"}", wire: "{\"ask\":\"a-20261111t100000\",\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"operator\",\"module\":\"mesh-host\"}", decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, {name: "the keeper asks every observer", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", wire: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, - {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:jochen\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")}, - {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:jochen\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:jochen\"}", + {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v ConditionChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-changed$")}, {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"jochen@shanks\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"jochen@shanks\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", + {name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:jochen\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:jochen\"}", + {name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", decode: func(b []byte) (any, error) { @@ -45,13 +45,13 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"jochen@shanks\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"jochen@shanks\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + {name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:jochen\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:jochen\"}", + {name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) diff --git a/health-and-repair/seats/mesh-conditions/fixtures/events.json b/health-and-repair/seats/mesh-conditions/fixtures/events.json index e6fbff3..cc0ad70 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/events.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/events.json @@ -6,7 +6,7 @@ "given": { "ask": "a-20261111t100000", "at": "2026-11-11T10:00:00Z", - "by": "jochen", + "by": "operator", "module": "mesh-host" } }, @@ -36,7 +36,7 @@ "summary": "a directory waits for a hand", "source": "health-report", "resolver": "self", - "owner": "forge:jochen", + "owner": "forge:operator", "waiting-on": "node-engine", "event": "condition-raised", "at": "2026-11-11T10:00:00Z", @@ -64,7 +64,7 @@ "event": "condition-changed", "at": "2026-11-11T12:00:00Z", "change": "owner", - "was": "forge:jochen" + "was": "forge:operator" } } ] diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index 1b66c9e..f7566d9 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -89,7 +89,7 @@ "scope": "module" }, "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", - "owner": "jochen@shanks", + "owner": "operator@workstation", "waiting-on": "node-engine" } }, @@ -123,7 +123,7 @@ }, "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", "owner": "operator-channel", - "waiting-on": "forge:jochen" + "waiting-on": "forge:operator" } }, { @@ -196,7 +196,7 @@ "source": "health-report", "observer": "mesh-delivery-watchman", "at": "2026-11-11T10:00:00Z", - "owner": "jochen@shanks", + "owner": "operator@workstation", "waiting-on": "node-engine", "scope": "module", "id": "mesh-host.ace", @@ -219,7 +219,7 @@ "observer": "mesh-delivery-watchman", "at": "2026-11-11T10:00:00Z", "owner": "node-engine", - "waiting-on": "forge:jochen", + "waiting-on": "forge:operator", "scope": "module", "id": "mesh-host.ace", "since": "2026-11-11T10:00:00Z" diff --git a/identity-and-access/go/seats/meshgrants/contract_test.go b/identity-and-access/go/seats/meshgrants/contract_test.go index ef84ac6..b5f3c32 100644 --- a/identity-and-access/go/seats/meshgrants/contract_test.go +++ b/identity-and-access/go/seats/meshgrants/contract_test.go @@ -19,7 +19,7 @@ func TestFixtures(t *testing.T) { }{ {name: "a granting wait held", subject: "mesh.seat.mesh-grants.event.wait-held", given: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-held$")}, - {name: "a granting wait released", subject: "mesh.seat.mesh-grants.event.wait-ended", given: "{\"bound\":\"10m\",\"by\":\"jochen: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"by\":\"jochen: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", + {name: "a granting wait released", subject: "mesh.seat.mesh-grants.event.wait-ended", given: "{\"bound\":\"10m\",\"by\":\"operator: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", wire: "{\"bound\":\"10m\",\"by\":\"operator: the new grants part is stuck\",\"clock-from\":\"2026-11-09T20:55:00Z\",\"fp\":\"src2:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"how\":\"released\",\"module\":\"mesh-tools\",\"part\":\"mesh-grants\",\"since\":\"2026-11-09T21:00:00Z\",\"step\":\"grant\",\"version\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.wait-ended$")}, {name: "filling is said past 80 %", subject: "mesh.seat.mesh-grants.event.filling", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"bytes\":161061273,\"cap\":201326592,\"store\":\"SEAT_mesh-pipeline-runner_pipeline-ended\"}", decode: func(b []byte) (any, error) { var v FillingEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-grants\\.event\\.filling$")}, diff --git a/identity-and-access/seats/mesh-grants/fixtures/events.json b/identity-and-access/seats/mesh-grants/fixtures/events.json index 6e72de6..1ca9ce1 100644 --- a/identity-and-access/seats/mesh-grants/fixtures/events.json +++ b/identity-and-access/seats/mesh-grants/fixtures/events.json @@ -27,7 +27,7 @@ "since": "2026-11-09T21:00:00Z", "bound": "10m", "how": "released", - "by": "jochen: the new grants part is stuck", + "by": "operator: the new grants part is stuck", "clock-from": "2026-11-09T20:55:00Z" } }, diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json index a777fec..4120766 100644 --- a/seats/mesh-recovery/fixtures/verbs.json +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -115,7 +115,7 @@ "kept": "ledger", "id": "20261111T121200Z", "why": "an aside left at removed", - "asker": "jochen@shanks" + "asker": "operator@workstation" } }, { @@ -124,7 +124,7 @@ "given": { "act": "a-1", "why": "the dump waits too long", - "asker": "jochen@shanks" + "asker": "operator@workstation" } }, { @@ -134,7 +134,7 @@ "module": "mesh-knowledge", "kept": "ledger", "why": "the operator's hand act", - "asker": "jochen@shanks", + "asker": "operator@workstation", "fingerprint": "0123456789ab" } }, @@ -152,7 +152,7 @@ "module": "mesh-knowledge", "kept": "ledger", "why": "the operator's hand act", - "asker": "jochen@shanks", + "asker": "operator@workstation", "snapshot": "2-0123456789ab", "from-backup": true } @@ -164,7 +164,7 @@ "module": "mesh-knowledge", "kept": "ledger", "why": "the operator's hand act", - "asker": "jochen@shanks", + "asker": "operator@workstation", "request": "r-20261111t100000" } }, @@ -198,7 +198,7 @@ "module": "mesh-knowledge", "kept": "ledger", "why": "the operator's hand act", - "asker": "jochen@shanks" + "asker": "operator@workstation" } }, { @@ -215,7 +215,7 @@ "module": "mesh-knowledge", "kept": "ledger", "why": "the operator's hand act", - "asker": "jochen@shanks", + "asker": "operator@workstation", "id": "20261111T121200Z" } }, diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index 2e3cc3f..0140fbc 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -213,7 +213,7 @@ "v": 1, "fingerprint": "b3f1c9", "why": "the entry could not be read", - "by": "operator@shanks", + "by": "operator@workstation", "at": "2026-11-11T08:00:00Z" }, "read": "first-views" From 49e26f5d279def54be060ee92507d6de1ae8995f Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 05:00:12 +0100 Subject: [PATCH 53/62] Kept: the operator-channel client keeps an asked call's act, arguments and recorded mark MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An asker that asks for a call (the tool runner's approval gate) keeps beside the ask the act its options bind, the call's whole arguments, and whether its run is in the hand-act log; Take keeps all three as it marks the ask. Builds: design 46 7-approval-mark §13 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../go/clients/operatorchannelclient/client.go | 9 +++++++++ .../go/clients/operatorchannelclient/client_test.go | 12 ++++++++++++ 2 files changed, 21 insertions(+) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client.go b/operator-and-conversation/go/clients/operatorchannelclient/client.go index 01f974e..6f656aa 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client.go @@ -58,12 +58,21 @@ func (c *Client) now() time.Time { } // Kept is one ask as the module keeps it. +// +// An asker that asks for a call keeps beside it the act the ask binds, the call's whole arguments, and whether the act's +// run was recorded in the hand-act log (design 46 7-approval-mark §13): Take keeps all three as it marks the ask. type Kept struct { Ask seat.Ask `json:"ask"` Asked time.Time `json:"asked"` Acted bool `json:"acted,omitempty"` Ended string `json:"ended,omitempty"` Answer *seat.Warrant `json:"answer,omitempty"` + // Act is the act the ask's options bind, as its asker digested it. + Act Act `json:"act,omitempty"` + // Arguments are the asked call's arguments whole. + Arguments json.RawMessage `json:"arguments,omitempty"` + // Recorded says the act's run is in the hand-act log (`mesh-hand-acts.warranted` answered). + Recorded bool `json:"recorded,omitempty"` } func (c *Client) key(id string) string { return c.KeyPrefix + "ask." + id } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 02d6bb0..000c2ca 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -167,9 +167,21 @@ func TestAKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere(t *t if _, ok := store.vals[tc.key]; len(store.vals) != 1 || !ok { t.Fatalf("prefix %q: keys written %v, want %s", tc.prefix, store.vals, tc.key) } + // Design 46 7-approval-mark §13: the act and the call's arguments kept beside the ask stay as Take marks it. + e, _ := store.Get(tc.key) + var k Kept + _ = json.Unmarshal(e.Value, &k) + k.Act, k.Arguments = releaseHQ, json.RawMessage(`{"delivery":"hq"}`) + if _, err := store.Update(tc.key, k, e.Revision); err != nil { + t.Fatal(err) + } if h, err := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { return nil }); h != Acted || err != nil { t.Fatalf("prefix %q: the warrant was not read from %s: %s %v", tc.prefix, tc.key, h, err) } + raw := string(store.vals[tc.key]) + if !strings.Contains(raw, `"act":{"delivery":"hq","verb":"release"}`) || !strings.Contains(raw, `"arguments":{"delivery":"hq"}`) || strings.Contains(raw, `"recorded"`) { + t.Errorf("prefix %q: the kept ask after Take is %s", tc.prefix, raw) + } if _, _, err := c.Where("an-asker.d-1"); err != nil || asked != "an-asker.d-1" { t.Errorf("prefix %q: Where read %q", tc.prefix, asked) } From ff63be3028b3a4201fc9514677a4a84af8031aee Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 06:04:56 +0100 Subject: [PATCH 54/62] AM-D3/AM-H1 path: the node's record carries the runner's reading; mesh-grants gains withheld MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The grants part must tell a reading of the running tool runner from an older one, and the node-engine's composition reads the withheld subjects through a verb of the seat, never the grants part's state. Builds: design 46 7 §6 (the node's record takes the runner's capabilities and fingerprint; the seat mesh-grants' verb withheld, class read, callers the node-engine, persons and the operator, input node, with a fixture), lead answer A-203 (runner-capabilities, runner-fingerprint; withheld's input and answer) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/nodeengine/contract.go | 14 ++-- go/seats/nodeengine/contract_test.go | 2 +- .../go/seats/meshgrants/contract.go | 30 +++++++- .../go/seats/meshgrants/contract_test.go | 4 + .../seats/mesh-grants/fixtures/verbs.json | 33 ++++++++ .../seats/mesh-grants/seat.json | 76 +++++++++++++++++++ .../ts/seats/meshgrants/index.d.ts | 27 +++++++ .../ts/seats/meshgrants/index.js | 1 + seats/node-engine/fixtures/states.json | 7 +- seats/node-engine/seat.json | 11 +++ ts/seats/nodeengine/index.d.ts | 4 + 11 files changed, 201 insertions(+), 8 deletions(-) diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 825e95e..44e19e5 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -813,11 +813,15 @@ type NodeRecord struct { NetworksSaid bool `json:"networks-said,omitempty"` Node string `json:"node"` OutwardLinks []string `json:"outward-links,omitempty"` - SealingKey string `json:"sealing-key,omitempty"` - ServingKey string `json:"serving-key,omitempty"` - Trusts []string `json:"trusts,omitempty"` - TunnelKey string `json:"tunnel-key,omitempty"` - V int64 `json:"v"` + // the capabilities this node's tool runner states of the calls it answers, as its announcement carries them (design 46 approval mark 6) + RunnerCapabilities []string `json:"runner-capabilities,omitempty"` + // the fingerprint of the tool runner that stated runner-capabilities, as its announcement carries it; empty when it stated none + RunnerFingerprint string `json:"runner-fingerprint,omitempty"` + SealingKey string `json:"sealing-key,omitempty"` + ServingKey string `json:"serving-key,omitempty"` + Trusts []string `json:"trusts,omitempty"` + TunnelKey string `json:"tunnel-key,omitempty"` + V int64 `json:"v"` } // PeerSeen is a tunnel peer and whether it is seen. diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index be4495f..441832c 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -85,7 +85,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "the bus module's have carries the user list written (typed from the engine's values)", subject: "", given: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", wire: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", + {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a module's data items on a node (typed from the engine's values)", subject: "", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", decode: func(b []byte) (any, error) { var v DataByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/identity-and-access/go/seats/meshgrants/contract.go b/identity-and-access/go/seats/meshgrants/contract.go index a2c3e2c..6d40945 100644 --- a/identity-and-access/go/seats/meshgrants/contract.go +++ b/identity-and-access/go/seats/meshgrants/contract.go @@ -10,6 +10,7 @@ const Seat = "mesh-grants" const ( VerbGrantsFor = "grants-for" + VerbWithheld = "withheld" ) const ( @@ -21,7 +22,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbGrantsFor} + return []string{VerbGrantsFor, VerbWithheld} } // Events is every event published on the seat's subject: a new copy each call. @@ -113,6 +114,24 @@ const ( WaitStepGrant = "grant" ) +// WithheldModulesItem is a type of the contract. +type WithheldModulesItem struct { + Module string `json:"module"` + Subjects []WithheldSubject `json:"subjects"` +} + +// Withheld is a node's withheld subjects, by module. +type Withheld struct { + Modules []WithheldModulesItem `json:"modules"` + Node string `json:"node"` +} + +// WithheldSubject is one subject withheld, and why. +type WithheldSubject struct { + Subject string `json:"subject"` + Why string `json:"why"` +} + // GrantsForInput is what grants-for takes. type GrantsForInput struct { // its watched branch @@ -126,6 +145,15 @@ type GrantsForInput struct { // GrantsForAnswer is what grants-for answers. type GrantsForAnswer = GrantsFor +// WithheldInput is what withheld takes. +type WithheldInput struct { + // the node whose runtime's withheld subjects are asked + Node string `json:"node"` +} + +// WithheldAnswer is what withheld answers. +type WithheldAnswer = Withheld + // WaitHeldEvent is the body of the event wait-held. type WaitHeldEvent = Wait diff --git a/identity-and-access/go/seats/meshgrants/contract_test.go b/identity-and-access/go/seats/meshgrants/contract_test.go index ef84ac6..2c30e2e 100644 --- a/identity-and-access/go/seats/meshgrants/contract_test.go +++ b/identity-and-access/go/seats/meshgrants/contract_test.go @@ -29,6 +29,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v GrantsForAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "grants-for asks a source revision on a branch", subject: "", given: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}", wire: "{\"branch\":\"main\",\"source\":\"a1b2c3d4\"}", decode: func(b []byte) (any, error) { var v GrantsForInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "withheld answers a node's withheld subjects by module", subject: "", given: "{\"modules\":[{\"module\":\"zsh\",\"subjects\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.tool.execute.*\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.call.execute.\\u003e\",\"why\":\"its tool runner does not state approval-mark/1\"}]}],\"node\":\"workstation\"}", wire: "{\"modules\":[{\"module\":\"zsh\",\"subjects\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.tool.execute.*\",\"why\":\"its tool runner does not state approval-mark/1\"},{\"subject\":\"mesh.mod.zsh.call.execute.\\u003e\",\"why\":\"its tool runner does not state approval-mark/1\"}]}],\"node\":\"workstation\"}", + decode: func(b []byte) (any, error) { var v WithheldAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "withheld asks a node", subject: "", given: "{\"node\":\"workstation\"}", wire: "{\"node\":\"workstation\"}", + decode: func(b []byte) (any, error) { var v WithheldInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/identity-and-access/seats/mesh-grants/fixtures/verbs.json b/identity-and-access/seats/mesh-grants/fixtures/verbs.json index e2bd9f1..622e0cb 100644 --- a/identity-and-access/seats/mesh-grants/fixtures/verbs.json +++ b/identity-and-access/seats/mesh-grants/fixtures/verbs.json @@ -24,5 +24,38 @@ "source": "a1b2c3d4", "branch": "main" } + }, + { + "name": "withheld answers a node's withheld subjects by module", + "of": "verb:withheld.answer", + "given": { + "node": "workstation", + "modules": [ + { + "module": "zsh", + "subjects": [ + { + "subject": "mesh.mod.zsh.tool.execute", + "why": "its tool runner does not state approval-mark/1" + }, + { + "subject": "mesh.mod.zsh.tool.execute.*", + "why": "its tool runner does not state approval-mark/1" + }, + { + "subject": "mesh.mod.zsh.call.execute.>", + "why": "its tool runner does not state approval-mark/1" + } + ] + } + ] + } + }, + { + "name": "withheld asks a node", + "of": "verb:withheld.input", + "given": { + "node": "workstation" + } } ] diff --git a/identity-and-access/seats/mesh-grants/seat.json b/identity-and-access/seats/mesh-grants/seat.json index 8fdb2ca..49e5cd8 100644 --- a/identity-and-access/seats/mesh-grants/seat.json +++ b/identity-and-access/seats/mesh-grants/seat.json @@ -41,6 +41,32 @@ "answer": { "$ref": "#/defs/GrantsFor" } + }, + { + "name": "withheld", + "description": "The marked subjects withheld from each module a node's runtime carries, and why: where its tool runner does not state approval-mark/1, or its reading is not the running runner's (design 46 approval mark 6).", + "class": "read", + "callers": [ + "seat:node-engine", + "persons", + "operator" + ], + "input": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node whose runtime's withheld subjects are asked" + } + }, + "required": [ + "node" + ], + "additionalProperties": false + }, + "answer": { + "$ref": "#/defs/Withheld" + } } ], "events": [ @@ -217,6 +243,56 @@ "description": "why it could not be answered: the catalog half of the candidate is not held" } } + }, + "Withheld": { + "type": "object", + "description": "a node's withheld subjects, by module", + "properties": { + "node": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "subjects": { + "type": "array", + "items": { + "$ref": "#/defs/WithheldSubject" + } + } + }, + "required": [ + "module", + "subjects" + ] + } + } + }, + "required": [ + "node", + "modules" + ] + }, + "WithheldSubject": { + "type": "object", + "description": "one subject withheld, and why", + "properties": { + "subject": { + "type": "string" + }, + "why": { + "type": "string" + } + }, + "required": [ + "subject", + "why" + ] } } } diff --git a/identity-and-access/ts/seats/meshgrants/index.d.ts b/identity-and-access/ts/seats/meshgrants/index.d.ts index 167e2b8..899e889 100644 --- a/identity-and-access/ts/seats/meshgrants/index.d.ts +++ b/identity-and-access/ts/seats/meshgrants/index.d.ts @@ -6,6 +6,7 @@ export declare const seat: "mesh-grants"; export declare const verbs: { readonly grantsFor: "grants-for"; + readonly withheld: "withheld"; }; export declare const events: { @@ -78,6 +79,23 @@ export interface Wait { "version": string; } +export interface WithheldModulesItem { + "module": string; + "subjects": WithheldSubject[]; +} + +/** a node's withheld subjects, by module */ +export interface Withheld { + "modules": WithheldModulesItem[]; + "node": string; +} + +/** one subject withheld, and why */ +export interface WithheldSubject { + "subject": string; + "why": string; +} + /** is what grants-for takes. */ export interface GrantsForInput { /** its watched branch */ @@ -91,6 +109,15 @@ export interface GrantsForInput { /** is what grants-for answers. */ export type GrantsForAnswer = GrantsFor; +/** is what withheld takes. */ +export interface WithheldInput { + /** the node whose runtime's withheld subjects are asked */ + "node": string; +} + +/** is what withheld answers. */ +export type WithheldAnswer = Withheld; + /** is the body of the event wait-held. */ export type WaitHeldEvent = Wait; diff --git a/identity-and-access/ts/seats/meshgrants/index.js b/identity-and-access/ts/seats/meshgrants/index.js index e19f333..2bd80bd 100644 --- a/identity-and-access/ts/seats/meshgrants/index.js +++ b/identity-and-access/ts/seats/meshgrants/index.js @@ -6,6 +6,7 @@ export const seat = "mesh-grants"; export const verbs = { grantsFor: "grants-for", + withheld: "withheld", }; export const events = { diff --git a/seats/node-engine/fixtures/states.json b/seats/node-engine/fixtures/states.json index db64100..f9b2f5b 100644 --- a/seats/node-engine/fixtures/states.json +++ b/seats/node-engine/fixtures/states.json @@ -388,6 +388,7 @@ "node": "ace", "tunnel-key": "k", "capabilities": [ + "approval-mark/1", "docker" ], "networks": [ @@ -397,7 +398,11 @@ } ], "networks-said": true, - "contract": 3 + "contract": 3, + "runner-capabilities": [ + "approval-mark/1" + ], + "runner-fingerprint": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "composes": "own", "candidates": { diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 3225f06..6ff2c9e 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -2342,6 +2342,17 @@ "items": { "type": "string" } + }, + "runner-capabilities": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the capabilities this node's tool runner states of the calls it answers, as its announcement carries them (design 46 approval mark 6)" + }, + "runner-fingerprint": { + "type": "string", + "description": "the fingerprint of the tool runner that stated runner-capabilities, as its announcement carries it; empty when it stated none" } }, "required": [ diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index 8eeb44e..7051477 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -473,6 +473,10 @@ export interface NodeRecord { "networks-said"?: boolean; "node": string; "outward-links"?: string[]; + /** the capabilities this node's tool runner states of the calls it answers, as its announcement carries them (design 46 approval mark 6) */ + "runner-capabilities"?: string[]; + /** the fingerprint of the tool runner that stated runner-capabilities, as its announcement carries it; empty when it stated none */ + "runner-fingerprint"?: string; "sealing-key"?: string; "serving-key"?: string; "trusts"?: string[]; From 33d9b288698f1c9930db4b821e19e5f203db4208 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 06:09:18 +0100 Subject: [PATCH 55/62] A3d item 1: operatorchannelclient re-exports mesh-sdk's act and its digest, one form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §677, lead answers A-198, A-219 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../go/clients/operatorchannelclient/ask.go | 34 +++---------------- .../clients/operatorchannelclient/ask_test.go | 6 ++++ 2 files changed, 11 insertions(+), 29 deletions(-) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/ask.go b/operator-and-conversation/go/clients/operatorchannelclient/ask.go index eb5a5ed..f0a28cb 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/ask.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/ask.go @@ -13,12 +13,12 @@ import ( "errors" "fmt" "regexp" - "sort" "strconv" "strings" "time" seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + "git.novox.be/novox/mesh-sdk/go/operatorask" ) // The levels an option is answered at: how much proof its answer needs (novox/hq ADR 0234 §8, the glossary's @@ -57,35 +57,11 @@ const ( OutcomeRefused = "refused" // it was never shown: Words says why ) -// An Act is what an option binds: named fields, each a string — the verb, the machine, the level, and each -// argument under a name of its own ("arg.delivery"). Flat on purpose: its digest is over these names and -// values alone, never over how a language happens to encode a struct. -type Act map[string]string +// An Act is what an option binds: mesh-sdk's operatorask.Act, re-exported (design 47 G lead answers A-198, A-219). +type Act = operatorask.Act -// ActDigest is the digest an asker puts in an option's Binds: SHA-256 over the act's canonical encoding -// (canonical), written "sha256:". The same names and values give the same digest in any language, whatever -// order they were set in; a field renamed, added or emptied gives another. -func ActDigest(act Act) (string, error) { - if len(act) == 0 { - return "", fmt.Errorf("the act cannot be digested: it names nothing") - } - keys := make([]string, 0, len(act)) - for k := range act { - if k == "" { - return "", fmt.Errorf("the act cannot be digested: a field has no name") - } - keys = append(keys, k) - } - sort.Strings(keys) - var b strings.Builder - b.WriteString("novox.act.v1\n") - for _, k := range keys { - canonical(&b, k) - canonical(&b, act[k]) - } - sum := sha256.Sum256([]byte(b.String())) - return "sha256:" + hex.EncodeToString(sum[:]), nil -} +// ActDigest is the digest an asker puts in an option's Binds: mesh-sdk's operatorask.ActDigest, re-exported. +func ActDigest(act Act) (string, error) { return operatorask.ActDigest(act) } // canonical writes one value as its length in bytes, a colon, the bytes and a newline: no value can be read // as another's end or start, so two different sequences of values never encode the same. diff --git a/operator-and-conversation/go/clients/operatorchannelclient/ask_test.go b/operator-and-conversation/go/clients/operatorchannelclient/ask_test.go index 9d32152..c025c4e 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/ask_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/ask_test.go @@ -10,6 +10,7 @@ import ( "time" seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + "git.novox.be/novox/mesh-sdk/go/operatorask" ) var now = time.Date(2026, 10, 8, 14, 0, 0, 0, time.UTC) @@ -189,6 +190,11 @@ func TestDigestsAreCanonicalOverNamedFields(t *testing.T) { Digest(gold) != "sha256:997af29a80663c5eb7d9dd38fc029c4a15fd726220b25e3c7cdc54d5a60bbbae" { t.Errorf("the digests changed with the move: %s, %s", Digest(held()), Digest(gold)) } + // The act is mesh-sdk's, re-exported (A-198, A-219): one form, so the seat server's gate digests as an asker does. + var shared operatorask.Act = Act{"verb": "release", "arg.delivery": "hq"} + if d, _ := operatorask.ActDigest(shared); d == "" { + t.Error("mesh-sdk's digest of the act is empty") + } a1, _ := ActDigest(Act{"verb": "release", "arg.delivery": "hq"}) b := Act{} b["arg.delivery"] = "hq" From 1d3f24250c6d85314a3f643cccebeabc90c2d053 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 06:25:56 +0100 Subject: [PATCH 56/62] A3e item 1: operatorchannelclient implements the gate's channel and re-exports its Kept MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §677, §700, lead answers A-219, A-224, A-228 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../go/clients/operatorchannelclient/ask.go | 3 +- .../clients/operatorchannelclient/client.go | 22 ++--- .../operatorchannelclient/client_test.go | 59 ++++++++++++ .../go/clients/operatorchannelclient/gate.go | 90 +++++++++++++++++++ 4 files changed, 156 insertions(+), 18 deletions(-) create mode 100644 operator-and-conversation/go/clients/operatorchannelclient/gate.go diff --git a/operator-and-conversation/go/clients/operatorchannelclient/ask.go b/operator-and-conversation/go/clients/operatorchannelclient/ask.go index f0a28cb..06c0d8f 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/ask.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/ask.go @@ -18,6 +18,7 @@ import ( "time" seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + "git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/operatorask" ) @@ -178,7 +179,7 @@ const ( MostOpen = 3 ApproveLasts = 24 * time.Hour DestroyLasts = 10 * time.Minute - HeadlineLength = 60 + HeadlineLength = approval.HeadlineLength LabelLength = 24 ) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client.go b/operator-and-conversation/go/clients/operatorchannelclient/client.go index 6f656aa..da574cb 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client.go @@ -19,6 +19,7 @@ import ( seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/approval" ) // Client asks as one module. @@ -57,23 +58,10 @@ func (c *Client) now() time.Time { return time.Now() } -// Kept is one ask as the module keeps it. -// -// An asker that asks for a call keeps beside it the act the ask binds, the call's whole arguments, and whether the act's -// run was recorded in the hand-act log (design 46 7-approval-mark §13): Take keeps all three as it marks the ask. -type Kept struct { - Ask seat.Ask `json:"ask"` - Asked time.Time `json:"asked"` - Acted bool `json:"acted,omitempty"` - Ended string `json:"ended,omitempty"` - Answer *seat.Warrant `json:"answer,omitempty"` - // Act is the act the ask's options bind, as its asker digested it. - Act Act `json:"act,omitempty"` - // Arguments are the asked call's arguments whole. - Arguments json.RawMessage `json:"arguments,omitempty"` - // Recorded says the act's run is in the hand-act log (`mesh-hand-acts.warranted` answered). - Recorded bool `json:"recorded,omitempty"` -} +// Kept is one ask as the module keeps it: mesh-sdk's go/approval's form (design 47 G lead answer A-228) over the generated +// contract's ask and warrant. An asker that asks for a call keeps beside it the act the ask binds, the call's whole +// arguments, and whether the act's run was recorded in the hand-act log (design 46 7-approval-mark §13). +type Kept = approval.Kept[seat.Ask, seat.Warrant] func (c *Client) key(id string) string { return c.KeyPrefix + "ask." + id } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 000c2ca..7fd0ce8 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -8,6 +8,7 @@ import ( seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/approval" "git.novox.be/novox/mesh-sdk/go/process" ) @@ -200,3 +201,61 @@ func TestWhereReadsTheRecordsWarrantTyped(t *testing.T) { t.Fatalf("Where = %q, %+v, %v; want chosen and the record's warrant", state, w, err) } } + +// The gate's channel (design 47 G lead answers A-219, A-228): the gate's ask raised to the operator at the level approve, +// the router's record read in the gate's form with its warrant whole, and a warrant claimed once, only for the act its +// option binds. +func TestTheGateChannelTranslatesTheGatesForms(t *testing.T) { + st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} + records := map[string]seat.AsksByAskerIDValue{} + g := &GateChannel{State: st, KeyPrefix: "n1.", Now: func() time.Time { return now }, + Publish: func(module, subject string, body any, id string) error { + if subject != seat.AcceptSubjectAsk(module) { + t.Fatalf("published on %s", subject) + } + return nil + }, + ReadRecord: func(module, id string) (*stdio.StateEntry, error) { + rec, ok := records[module+"."+id] + if !ok { + return nil, nil + } + raw, _ := json.Marshal(rec) + return &stdio.StateEntry{Value: raw}, nil + }} + digest, _ := ActDigest(releaseHQ) + a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), + OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} + if err := g.Ask("shell", a); err != nil { + t.Fatal(err) + } + var k Kept + if e, _ := st.Get("n1.ask.a1"); e == nil || json.Unmarshal(e.Value, &k) != nil || k.Ask.Who != Operator || k.Ask.Options[0].Level != Approve { + t.Fatalf("kept %+v", k) + } + if rec, err := g.Record("shell", "a1"); rec != nil || err != nil { + t.Fatalf("a record not yet there: %+v %v", rec, err) + } + w := seat.Warrant{Ask: "a1", Asker: "shell", Outcome: OutcomeChosen, Option: "approve", Level: Approve, At: FormatTime(now), + AskDigest: Digest(k.Ask), Channel: "telegram", By: &seat.Person{Who: Operator, Kind: "telegram"}} + records["shell.a1"] = seat.AsksByAskerIDValue{Asker: "shell", State: "chosen", Opened: FormatTime(now), Warrant: &w} + rec, err := g.Record("shell", "a1") + if err != nil || rec == nil || rec.State != "chosen" || rec.Warrant == nil || rec.Warrant.Channel != "telegram" || rec.Warrant.Option != "approve" { + t.Fatalf("record %+v %v", rec, err) + } + if h, err := g.Claim("shell", *rec.Warrant, map[string]string{"verb": "other"}, func() { t.Fatal("ran another act") }); h != approval.Claimed || err == nil { + t.Fatalf("another act: %s %v", h, err) + } + delete(st.vals, "n1.ask.a1") + _ = g.Ask("shell", a) + runs := 0 + for i := 0; i < 2; i++ { + h, err := g.Claim("shell", *rec.Warrant, releaseHQ, func() { runs++ }) + if want := []approval.Claim{approval.Claimed, approval.ClaimDone}[i]; h != want || err != nil { + t.Fatalf("claim %d: %s %v", i, h, err) + } + } + if runs != 1 || g.Decided("shell") != seat.SubjectDecided("shell") { + t.Fatalf("runs %d", runs) + } +} diff --git a/operator-and-conversation/go/clients/operatorchannelclient/gate.go b/operator-and-conversation/go/clients/operatorchannelclient/gate.go new file mode 100644 index 0000000..0e6cfa0 --- /dev/null +++ b/operator-and-conversation/go/clients/operatorchannelclient/gate.go @@ -0,0 +1,90 @@ +package operatorchannelclient + +import ( + "encoding/json" + "fmt" + "time" + + seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/approval" + "git.novox.be/novox/mesh-sdk/go/operatorask" +) + +// GateChannel is the operator channel as mesh-sdk's approval gate reaches it (design 47 G lead answers A-219, A-228): it +// translates the gate's own forms to and from the generated contract's, asking under the marked module's name through a +// Client whose asks are kept in the gate's state under KeyPrefix. +type GateChannel struct { + // State is the gate's state approvals; KeyPrefix is put before every key the client keeps there. + State Store + KeyPrefix string + Now func() time.Time + // Publish says an accept on the seat under module's name; ReadRecord reads the router's record `.` of the + // seat's state asks, both on the gate's holder's own account (design 47 G §700). + Publish func(module, subject string, body any, id string) error + ReadRecord func(module, id string) (*stdio.StateEntry, error) +} + +var _ approval.Channel = (*GateChannel)(nil) + +func (g *GateChannel) client(module string) *Client { + return &Client{Module: module, State: g.State, KeyPrefix: g.KeyPrefix, Now: g.Now, + Publish: func(subject string, body any, id string) error { return g.Publish(module, subject, body, id) }, + Record: func(id string) (*stdio.StateEntry, error) { return g.ReadRecord(module, id) }} +} + +// Ask raises the gate's ask to the operator, every option at the level approve. +func (g *GateChannel) Ask(module string, a approval.Ask) error { + ask := seat.Ask{ID: a.ID, About: a.About, Who: Operator, Headline: a.Headline, Explanation: a.Explanation, + Expires: a.Expires, OnExpiry: a.OnExpiry} + for _, o := range a.Options { + ask.Options = append(ask.Options, seat.Option{ID: o.ID, Label: o.Label, Does: o.Does, Level: Approve, Binds: o.Binds}) + } + return g.client(module).Ask(ask) +} + +// Record is the router's record of module's ask in the gate's form, nil while there is none. +func (g *GateChannel) Record(module, id string) (*approval.Record, error) { + e, err := g.ReadRecord(module, id) + if err != nil || e == nil { + return nil, err + } + var rec seat.AsksByAskerIDValue + if err := json.Unmarshal(e.Value, &rec); err != nil { + return nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err) + } + out := &approval.Record{State: rec.State, Answer: rec.Answer, Opened: rec.Opened, Expires: rec.Expires, OfferedOn: rec.OfferedOn} + if w := rec.Warrant; w != nil { + whole, err := json.Marshal(w) + if err != nil { + return nil, err + } + out.Warrant = &approval.Warrant{Ask: w.Ask, Asker: w.Asker, Option: w.Option, Channel: w.Channel, At: w.At, Whole: whole} + } + return out, nil +} + +// Claim takes the warrant once with Take, holding the chosen option to act before run. +func (g *GateChannel) Claim(module string, w approval.Warrant, act operatorask.Act, run func()) (approval.Claim, error) { + var sw seat.Warrant + if err := json.Unmarshal(w.Whole, &sw); err != nil { + return approval.ClaimRefused, fmt.Errorf("the warrant for the ask %s cannot be read: %w", w.Ask, err) + } + h, err := g.client(module).Take(sw, func(o seat.Option, _ seat.Warrant) error { + if err := Performs(o, act); err != nil { + return err + } + run() + return nil + }) + return approval.Claim(h), err +} + +// Cancel takes module's ask back. +func (g *GateChannel) Cancel(module, id string) error { return g.client(module).Cancel(id) } + +// Decided is the subject of the router's `decided` for module. +func (g *GateChannel) Decided(module string) string { return seat.SubjectDecided(module) } + +// Seat is the seat the gate's asks are raised on. +func (g *GateChannel) Seat() string { return seat.Seat } From dbb197b0c75c4a5a27e5a8821d81af63b703b04f Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 06:26:10 +0100 Subject: [PATCH 57/62] AM-H1 contract: the node-engine's composition answer names the withheld subjects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A session reads in one composition why a marked tool is not served on a node, or that the grants part did not answer. Builds: design 46 7 §6 (the node-engine's composition of the module names the withheld subjects; "withheld unknown: the grants part does not answer"), lead answer A-239 (withheld, withheld-unknown) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/nodeengine/contract.go | 10 +++++++ go/seats/nodeengine/contract_test.go | 4 +++ seats/node-engine/fixtures/verbs.json | 41 +++++++++++++++++++++++++++ seats/node-engine/seat.json | 23 +++++++++++++++ ts/seats/nodeengine/index.d.ts | 9 ++++++ 5 files changed, 87 insertions(+) diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 44e19e5..f4fb044 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -1280,6 +1280,12 @@ type CompositionAnswerWant struct { Yes string `json:"yes,omitempty"` } +// CompositionAnswerWithheldItem is a type of the contract. +type CompositionAnswerWithheldItem struct { + Subject string `json:"subject"` + Why string `json:"why"` +} + // CompositionAnswer is what composition answers. type CompositionAnswer struct { // the module's last apply that did not end running; absent when none @@ -1305,6 +1311,10 @@ type CompositionAnswer struct { Started bool `json:"started"` // the module's want as the agent holds it; absent when it holds none Want *CompositionAnswerWant `json:"want,omitempty"` + // the module's marked subjects the grants part withholds from this node's runtime, each with why, read through mesh-grants' verb withheld (design 46 approval mark 6) + Withheld []CompositionAnswerWithheldItem `json:"withheld,omitempty"` + // withheld unknown: the grants part does not answer, when its verb withheld did not answer + WithheldUnknown string `json:"withheld-unknown,omitempty"` } // ComposeInput is what compose takes. diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index 441832c..497fc5f 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -123,6 +123,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v EntryAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "entry-again answers what was asked and where it is read", subject: "", given: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", wire: "{\"asked\":{\"at\":\"2026-11-11T08:00:00Z\",\"by\":\"operator@shanks\",\"fingerprint\":\"b3f1c9\",\"v\":1,\"why\":\"the entry could not be read\"},\"read\":\"first-views\"}", decode: func(b []byte) (any, error) { var v EntryAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "composition names what the grants part withholds of the module", subject: "", given: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"}]}", wire: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld\":[{\"subject\":\"mesh.mod.zsh.tool.execute\",\"why\":\"its tool runner does not state approval-mark/1\"}]}", + decode: func(b []byte) (any, error) { var v CompositionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "composition says withheld unknown when the grants part does not answer", subject: "", given: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld-unknown\":\"withheld unknown: the grants part does not answer\"}", wire: "{\"composition\":{\"key\":\"\"},\"judged\":{\"judgement\":\"\",\"waits_for_yes\":false,\"words\":\"\"},\"module\":\"zsh\",\"node\":\"workstation\",\"started\":false,\"withheld-unknown\":\"withheld unknown: the grants part does not answer\"}", + decode: func(b []byte) (any, error) { var v CompositionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index 2e3cc3f..28acd5a 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -218,5 +218,46 @@ }, "read": "first-views" } + }, + { + "name": "composition names what the grants part withholds of the module", + "of": "verb:composition.answer", + "given": { + "node": "workstation", + "module": "zsh", + "started": false, + "composition": { + "key": "" + }, + "judged": { + "judgement": "", + "waits_for_yes": false, + "words": "" + }, + "withheld": [ + { + "subject": "mesh.mod.zsh.tool.execute", + "why": "its tool runner does not state approval-mark/1" + } + ] + } + }, + { + "name": "composition says withheld unknown when the grants part does not answer", + "of": "verb:composition.answer", + "given": { + "node": "workstation", + "module": "zsh", + "started": false, + "composition": { + "key": "" + }, + "judged": { + "judgement": "", + "waits_for_yes": false, + "words": "" + }, + "withheld-unknown": "withheld unknown: the grants part does not answer" + } } ] diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 6ff2c9e..37bc985 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -494,6 +494,29 @@ "provisioner_account" ], "description": "of the node's own composition, its own fields beside what runs names" + }, + "withheld": { + "type": "array", + "description": "the module's marked subjects the grants part withholds from this node's runtime, each with why, read through mesh-grants' verb withheld (design 46 approval mark 6)", + "items": { + "type": "object", + "properties": { + "subject": { + "type": "string" + }, + "why": { + "type": "string" + } + }, + "required": [ + "subject", + "why" + ] + } + }, + "withheld-unknown": { + "type": "string", + "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" } }, "required": [ diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index 7051477..1d9f9c9 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -913,6 +913,11 @@ export interface CompositionAnswerWant { "yes"?: string; } +export interface CompositionAnswerWithheldItem { + "subject": string; + "why": string; +} + /** is what composition answers. */ export interface CompositionAnswer { /** the module's last apply that did not end running; absent when none */ @@ -938,6 +943,10 @@ export interface CompositionAnswer { "started": boolean; /** the module's want as the agent holds it; absent when it holds none */ "want"?: CompositionAnswerWant; + /** the module's marked subjects the grants part withholds from this node's runtime, each with why, read through mesh-grants' verb withheld (design 46 approval mark 6) */ + "withheld"?: CompositionAnswerWithheldItem[]; + /** withheld unknown: the grants part does not answer, when its verb withheld did not answer */ + "withheld-unknown"?: string; } /** is what compose takes. */ From 886be5cca788d114bd3854484713dbe455400327 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 10:23:22 +0100 Subject: [PATCH 58/62] A3h item 2b: NewGateChannel is the gate's operator channel over a process connection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It asks and cancels as accepted kinds of the seat operator-channel through the connection's Accept, and reads the router's record by a get in the seat holder's state asks, never through a bucket named in code. Builds: design 47 G §677, §700; lead answers A-272, A-273 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../operatorchannelclient/gate_conn.go | 51 +++++++++++++ .../operatorchannelclient/gate_conn_test.go | 71 +++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 operator-and-conversation/go/clients/operatorchannelclient/gate_conn.go create mode 100644 operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go diff --git a/operator-and-conversation/go/clients/operatorchannelclient/gate_conn.go b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn.go new file mode 100644 index 0000000..932d8ff --- /dev/null +++ b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn.go @@ -0,0 +1,51 @@ +package operatorchannelclient + +import ( + "fmt" + + seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/process" +) + +// asksRead is a state of another module read by key: process.State is one. +type asksRead interface { + Get(key string) (*stdio.StateEntry, error) +} + +// NewGateChannel is the operator channel as a process holder's gate reaches it over its own connection (design 47 G §677, +// §700; lead answers A-272, A-273): an ask and its cancel are sent on the seat operator-channel's accept subjects through +// conn's Accept, and the router's record is read by a get of the key `.` in the seat's state asks, whose bucket +// is formed from holder (the module the seat list names for the seat operator-channel) and the contract's StateAsks, on the +// process's own account. state keeps the asks, under keyPrefix (the gate's state approvals and its node). +func NewGateChannel(conn *process.Conn, state Store, keyPrefix string, holder func() (string, error)) *GateChannel { + return gateChannelOver(conn.Accept, func(read string) asksRead { return conn.Read(read) }, state, keyPrefix, holder) +} + +// gateChannelOver is NewGateChannel over the two things it reaches a connection through. +func gateChannelOver(accept func(seat, kind string, body any, opts ...stdio.EmitOptions) error, read func(read string) asksRead, + state Store, keyPrefix string, holder func() (string, error)) *GateChannel { + return &GateChannel{State: state, KeyPrefix: keyPrefix, + Publish: func(module, subject string, body any, id string) error { + var kind string + switch subject { + case seat.AcceptSubjectAsk(module): + kind = seat.AcceptAsk + case seat.AcceptSubjectCancel(module): + kind = seat.AcceptCancel + default: + return fmt.Errorf("%s is no accept subject of the seat %s that %s may use", subject, seat.Seat, module) + } + return accept(seat.Seat, kind, body, stdio.EmitOptions{MessageID: id}) + }, + ReadRecord: func(module, id string) (*stdio.StateEntry, error) { + held, err := holder() + if err != nil { + return nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err) + } + if held == "" { + return nil, fmt.Errorf("the router's record of %s cannot be read: the seat list names no holder of the seat %s", id, seat.Seat) + } + return read(held + "." + seat.StateAsks).Get(seat.AsksByAskerIDKey(module, id)) + }} +} diff --git a/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go new file mode 100644 index 0000000..fbacc0c --- /dev/null +++ b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go @@ -0,0 +1,71 @@ +package operatorchannelclient + +import ( + "encoding/json" + "errors" + "testing" + "time" + + seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/approval" +) + +type readOf struct { + state string + vals map[string]json.RawMessage +} + +func (r readOf) Get(key string) (*stdio.StateEntry, error) { + if v, ok := r.vals[r.state+"|"+key]; ok { + return &stdio.StateEntry{Key: key, Value: v}, nil + } + return nil, nil +} + +// The gate's channel over a process connection (design 47 G lead answers A-272, A-273): an ask and its cancel go out as +// accepted kinds of the seat operator-channel with the ask's id as the message id, the router's record is the get of +// `.` in the state asks of the seat's holder, and nothing else is reached: another subject, or a seat with no +// holder, is refused. +func TestTheGateChannelOverAConnectionAsksAndReadsOnlyThroughTheSeat(t *testing.T) { + type sent struct{ seat, kind, id string } + var out []sent + accept := func(s, kind string, _ any, opts ...stdio.EmitOptions) error { + out = append(out, sent{s, kind, opts[0].MessageID}) + return nil + } + raw, _ := json.Marshal(seat.AsksByAskerIDValue{Asker: "shell", State: "open", Opened: FormatTime(now)}) + vals := map[string]json.RawMessage{"messenger_holder.asks|shell.a1": raw, "other.asks|shell.a1": json.RawMessage(`{"state":"wrong"}`)} + read := func(r string) asksRead { return readOf{state: r, vals: vals} } + holder := func() (string, error) { return "messenger_holder", nil } + st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} + g := gateChannelOver(accept, read, st, "n1.", holder) + g.Now = func() time.Time { return now } + + digest, _ := ActDigest(releaseHQ) + a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), + OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} + if err := g.Ask("shell", a); err != nil { + t.Fatal(err) + } + if err := g.Cancel("shell", "a1"); err != nil { + t.Fatal(err) + } + if len(out) != 2 || out[0] != (sent{seat.Seat, seat.AcceptAsk, "a1"}) || out[1] != (sent{seat.Seat, seat.AcceptCancel, "cancel.a1"}) { + t.Fatalf("sent %+v, want the ask and its cancel on the seat's accepts", out) + } + if rec, err := g.Record("shell", "a1"); err != nil || rec == nil || rec.State != "open" { + t.Fatalf("record %+v %v, want the one in the holder's state asks", rec, err) + } + if rec, err := g.Record("shell", "zz"); err != nil || rec != nil { + t.Fatalf("a record not there: %+v %v", rec, err) + } + if err := g.Publish("shell", "mesh.seat.operator-channel.accept.ask.other", nil, "x"); err == nil { + t.Fatal("an accept subject naming another caller was sent") + } + for _, c := range []func() (string, error){func() (string, error) { return "", nil }, func() (string, error) { return "", errors.New("unread") }} { + if _, err := gateChannelOver(accept, read, st, "n1.", c).Record("shell", "a1"); err == nil { + t.Fatal("a record was read with no holder of the seat") + } + } +} From 181dd3263d99cfd6676556e5593a0ff6133a1856 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 11:35:10 +0100 Subject: [PATCH 59/62] G A-230: the seat mesh-recovery's restore point says names, the bus names it took MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Point gains names, one per bus object as Aside's (required, at least one), regenerated with seatgen; the kept-points fixture names its point's bus name, so the fixture test fails without the field. Builds: design 47 G A-230, §554, §565 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshrecovery/contract.go | 2 ++ go/seats/meshrecovery/contract_test.go | 2 +- seats/mesh-recovery/fixtures/verbs.json | 3 +++ seats/mesh-recovery/seat.json | 11 ++++++++++- ts/seats/meshrecovery/index.d.ts | 2 ++ 5 files changed, 18 insertions(+), 2 deletions(-) diff --git a/go/seats/meshrecovery/contract.go b/go/seats/meshrecovery/contract.go index ecc32b3..e028a54 100644 --- a/go/seats/meshrecovery/contract.go +++ b/go/seats/meshrecovery/contract.go @@ -165,6 +165,8 @@ type Point struct { Kept string `json:"kept"` // the module Module string `json:"module"` + // the bus names it took, one per bus object (design 47 G A-230) + Names []string `json:"names"` // its bytes Size int64 `json:"size"` // the point's name, also its directory's diff --git a/go/seats/meshrecovery/contract_test.go b/go/seats/meshrecovery/contract_test.go index 7f8e825..8111f7e 100644 --- a/go/seats/meshrecovery/contract_test.go +++ b/go/seats/meshrecovery/contract_test.go @@ -45,7 +45,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RestoreKeptInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-kept answers an error naming why", subject: "", given: "{\"error\":\"aside-only is the operator's hand tool alone\"}", wire: "{\"error\":\"aside-only is the operator's hand tool alone\"}", decode: func(b []byte) (any, error) { var v RestoreKeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", + {name: "kept-points lists a point, an aside and the act that runs", subject: "", given: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", wire: "{\"asides\":[{\"id\":\"20261111T121200Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":4096}],\"points\":[{\"at\":\"2026-11-11T10:00:00Z\",\"catch-up\":{\"tool\":\"knowledge_catch_up\"},\"consumers\":[{\"name\":\"c1\",\"sequence\":42,\"stream\":\"KV_x\"}],\"digests\":[{\"digest\":\"sha256:00\",\"name\":\"KV_x\"}],\"fingerprint\":\"0123456789ab\",\"form\":2,\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":2048,\"snapshot\":\"2-0123456789ab\"}],\"running\":{\"act\":\"a-1\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"waiting on the dump\",\"waits-on\":\"item-ended of the bus item\"},\"unrestored\":[{\"id\":\"20261110T080000Z\",\"names\":[\"mesh-knowledge_ledger\"],\"size\":1024}]}", decode: func(b []byte) (any, error) { var v KeptPointsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "restore-aside names the aside", subject: "", given: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", wire: "{\"asker\":\"operator@workstation\",\"id\":\"20261111T121200Z\",\"kept\":\"ledger\",\"module\":\"mesh-knowledge\",\"why\":\"an aside left at removed\"}", decode: func(b []byte) (any, error) { var v RestoreAsideInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/seats/mesh-recovery/fixtures/verbs.json b/seats/mesh-recovery/fixtures/verbs.json index 4120766..66fa8f6 100644 --- a/seats/mesh-recovery/fixtures/verbs.json +++ b/seats/mesh-recovery/fixtures/verbs.json @@ -78,6 +78,9 @@ "name": "KV_x", "digest": "sha256:00" } + ], + "names": [ + "mesh-knowledge_ledger" ] } ], diff --git a/seats/mesh-recovery/seat.json b/seats/mesh-recovery/seat.json index 78e88a9..6b7546d 100644 --- a/seats/mesh-recovery/seat.json +++ b/seats/mesh-recovery/seat.json @@ -1080,6 +1080,14 @@ "$ref": "#/defs/Digest" }, "description": "the digest of each object's bytes, checked before a restore (design 47 G 567)" + }, + "names": { + "type": "array", + "description": "the bus names it took, one per bus object (design 47 G A-230)", + "items": { + "type": "string" + }, + "minItems": 1 } }, "required": [ @@ -1089,7 +1097,8 @@ "fingerprint", "snapshot", "size", - "at" + "at", + "names" ] }, "Aside": { diff --git a/ts/seats/meshrecovery/index.d.ts b/ts/seats/meshrecovery/index.d.ts index df35b04..a7b4310 100644 --- a/ts/seats/meshrecovery/index.d.ts +++ b/ts/seats/meshrecovery/index.d.ts @@ -115,6 +115,8 @@ export interface Point { "kept": string; /** the module */ "module": string; + /** the bus names it took, one per bus object (design 47 G A-230) */ + "names": string[]; /** its bytes */ "size": number; /** the point's name, also its directory's */ From 821d6115305e028bce672352597993e45c75c77a Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 22:18:04 +0100 Subject: [PATCH 60/62] Round 2 T1, T2, T5: the contracts end G with no more tests than at their merge base; fixtures name roles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The test that read every fixture for the operator's account and a node goes (T1); the tests G added fold into existing ones as subtests, so each module counts its merge base (design 47 G §626, A-306); node names in the lines G adds are role names (T5). Builds: design 47 G §626, A-306; review round 2 findings T1, T2, T5 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/clients/meshconfigclient/client_test.go | 31 -- go/clients/nodeengineclient/have_test.go | 31 +- go/seats/meshmoduleassigner/contract_test.go | 4 +- go/seats/nodeengine/contract_test.go | 20 +- .../go/seats/meshconditions/contract_test.go | 14 +- .../go/seats/meshhealers/contract_test.go | 4 +- .../go/seats/meshwatchdogs/contract_test.go | 4 +- .../mesh-conditions/fixtures/events.json | 12 +- .../mesh-conditions/fixtures/states.json | 26 +- .../seats/mesh-healers/fixtures/events.json | 6 +- .../seats/mesh-watchdogs/fixtures/events.json | 8 +- .../meshnodeenrollerclient/enrolment_test.go | 45 ++- .../operatorchannelclient/client_test.go | 275 ++++++++++-------- .../operatorchannelclient/gate_conn_test.go | 52 ---- seats/node-engine/fixtures/events.json | 16 +- 15 files changed, 253 insertions(+), 295 deletions(-) diff --git a/go/clients/meshconfigclient/client_test.go b/go/clients/meshconfigclient/client_test.go index 4e0fc06..ede862f 100644 --- a/go/clients/meshconfigclient/client_test.go +++ b/go/clients/meshconfigclient/client_test.go @@ -1,9 +1,6 @@ package meshconfigclient import ( - "io/fs" - "os" - "path/filepath" "strings" "testing" ) @@ -46,31 +43,3 @@ func TestAHeldValueIsTheOneItsKeyNames(t *testing.T) { } } } - -// Design 47 G: the contracts' fixtures, and the tests generated from them, name no account of the operator and no node -// they run on: a role name stands for either (`operator`, `workstation`). -func TestFixturesNameNoOperatorAccountAndNoWorkstation(t *testing.T) { - root := "../../.." - err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { - if err != nil || d.IsDir() { - return err - } - slash := filepath.ToSlash(path) - if !strings.Contains(slash, "/fixtures/") && !strings.HasSuffix(slash, "/contract_test.go") || strings.Contains(slash, "node_modules") { - return nil - } - raw, err := os.ReadFile(path) - if err != nil { - return err - } - for _, word := range []string{"jochen", "shanks"} { - if strings.Contains(string(raw), word) { - t.Errorf("%s names %q: a fixture names the operator and the workstation by role", slash, word) - } - } - return nil - }) - if err != nil { - t.Fatal(err) - } -} diff --git a/go/clients/nodeengineclient/have_test.go b/go/clients/nodeengineclient/have_test.go index 6a408d7..0ccf323 100644 --- a/go/clients/nodeengineclient/have_test.go +++ b/go/clients/nodeengineclient/have_test.go @@ -58,22 +58,21 @@ func TestHaveCodec(t *testing.T) { if _, err := DecodeHave([]byte(`{"v":1,"phase":"running","health":"ok","extra":1}`)); err == nil { t.Fatal("an unknown field is read") } -} - -func TestSameHaveComparesTimesAsInstants(t *testing.T) { - at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC) - zone := time.FixedZone("x", 3600) - mk := func(tm time.Time) seat.HaveByNodeModuleValue { - return seat.HaveByNodeModuleValue{Phase: PhaseFailed, Health: HealthFailed, - PullWait: &seat.PullWait{Image: "i", Holder: "h", Began: tm}, - UserList: &seat.UserListWritten{Source: "s", At: tm}} - } - if !SameHave(mk(at), mk(at.In(zone))) { - t.Fatal("the same instant in another zone differs") - } - if SameHave(mk(at), mk(at.Add(time.Second))) { - t.Fatal("another instant is the same") - } + t.Run("SameHaveComparesTimesAsInstants", func(t *testing.T) { + at := time.Date(2026, 11, 5, 12, 0, 0, 0, time.UTC) + zone := time.FixedZone("x", 3600) + mk := func(tm time.Time) seat.HaveByNodeModuleValue { + return seat.HaveByNodeModuleValue{Phase: PhaseFailed, Health: HealthFailed, + PullWait: &seat.PullWait{Image: "i", Holder: "h", Began: tm}, + UserList: &seat.UserListWritten{Source: "s", At: tm}} + } + if !SameHave(mk(at), mk(at.In(zone))) { + t.Fatal("the same instant in another zone differs") + } + if SameHave(mk(at), mk(at.Add(time.Second))) { + t.Fatal("another instant is the same") + } + }) } func TestHaveNodeCodec(t *testing.T) { diff --git a/go/seats/meshmoduleassigner/contract_test.go b/go/seats/meshmoduleassigner/contract_test.go index b5f4fa0..e38965e 100644 --- a/go/seats/meshmoduleassigner/contract_test.go +++ b/go/seats/meshmoduleassigner/contract_test.go @@ -41,7 +41,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a module's key on a watched branch and a build", subject: "", given: "{\"node\":\"ace\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", wire: "{\"node\":\"ace\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", + {name: "a module's key on a watched branch and a build", subject: "", given: "{\"node\":\"home-server\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", wire: "{\"node\":\"home-server\",\"placed\":{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"plex\"},\"v\":1}", decode: func(b []byte) (any, error) { var v AssignmentsByNodeModuleValue err := json.Unmarshal(b, &v) @@ -53,7 +53,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a proposal placing a module on a watched branch at an earlier build", subject: "", given: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", wire: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"ace\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", + {name: "a proposal placing a module on a watched branch at an earlier build", subject: "", given: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"home-server\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", wire: "{\"at\":\"2026-11-10T12:00:00Z\",\"base\":{\"home-server\":3},\"by\":\"operator\",\"changes\":[{\"branch\":\"beta\",\"build\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"op\":\"place\"}],\"id\":\"p-20261110t120000-aabbccdd\",\"state\":\"answering\",\"why\":\"run nats from beta, back one build\"}", decode: func(b []byte) (any, error) { var v ProposalsByProposalValue err := json.Unmarshal(b, &v) diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index e206c6d..1872313 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -35,19 +35,19 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.manifest-reads-changed\\.[A-Za-z0-9_-]+$")}, - {name: "composed is said", subject: "mesh.seat.node-engine.event.composed.ace", given: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + {name: "composed is said", subject: "mesh.seat.node-engine.event.composed.home-server", given: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:00:00Z\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", decode: func(b []byte) (any, error) { var v ComposedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.composed\\.[^.*> ]+$")}, - {name: "running is said, its node and module in its subject", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + {name: "running is said, its node and module in its subject", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-09T20:01:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "running says the build that runs is healthy", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + {name: "running says the build that runs is healthy", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":true,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "running says the build that runs turned unhealthy, still running", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"ace\",\"v\":1}", + {name: "running says the build that runs turned unhealthy, still running", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", wire: "{\"at\":\"2026-11-11T09:05:00Z\",\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"healthy\":false,\"manifest\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"module\":\"nats\",\"node\":\"home-server\",\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "running says a module stopped on the node, with no fingerprint", subject: "mesh.seat.node-engine.event.running.ace.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"ace\",\"stopped\":true,\"v\":1}", + {name: "running says a module stopped on the node, with no fingerprint", subject: "mesh.seat.node-engine.event.running.home-server.nats", given: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"home-server\",\"stopped\":true,\"v\":1}", wire: "{\"at\":\"2026-11-11T09:00:00Z\",\"module\":\"nats\",\"node\":\"home-server\",\"stopped\":true,\"v\":1}", decode: func(b []byte) (any, error) { var v RunningEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.running\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "a kept build's wait is held", subject: "mesh.seat.node-engine.event.wait-held.ace.postgres", given: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"ace\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on ace\"}", wire: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"ace\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on ace\"}", + {name: "a kept build's wait is held", subject: "mesh.seat.node-engine.event.wait-held.home-server.postgres", given: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"home-server\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on home-server\"}", wire: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"node\":\"home-server\",\"on\":\"the kept build of postgres\",\"owner\":\"node-engine\",\"reason\":\"node away\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"kept-build\",\"words\":\"waiting for the kept build of postgres on home-server\"}", decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-held\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "a hold of the composition ends", subject: "mesh.seat.node-engine.event.wait-ended.ace.postgres", given: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", wire: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", + {name: "a hold of the composition ends", subject: "mesh.seat.node-engine.event.wait-ended.home-server.postgres", given: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", wire: "{\"owner\":\"node-engine\",\"reason\":\"restore point missing\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"compose\"}", decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-engine\\.event\\.wait-ended\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "the finding of a seat list unread, as the engine writes it", subject: "", given: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", wire: "{\"at\":\"2026-11-05T14:00:00Z\",\"key\":\"machine.ace.seat-list-unread\",\"kind\":\"seat-list-unread\",\"observer\":\"mesh-host\",\"severity\":\"warning\",\"source\":\"node-engine.seat-list\",\"subject\":{\"id\":\"ace\",\"machine\":\"ace\",\"scope\":\"machine\"},\"summary\":\"the seat list has not been read for five minutes\",\"v\":1}", decode: func(b []byte) (any, error) { var v FindingsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, @@ -85,7 +85,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "the bus module's have carries the user list written (typed from the engine's values)", subject: "", given: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", wire: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", + {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"home-server\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"home-server\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a module's data items on a node (typed from the engine's values)", subject: "", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", decode: func(b []byte) (any, error) { var v DataByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, @@ -111,9 +111,9 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v SeatListAgainAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "process-builds asks one module", subject: "", given: "{\"module\":\"nats\"}", wire: "{\"module\":\"nats\"}", decode: func(b []byte) (any, error) { var v ProcessBuildsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "process-builds answers each process's build", subject: "", given: "{\"node\":\"ace\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", wire: "{\"node\":\"ace\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", + {name: "process-builds answers each process's build", subject: "", given: "{\"node\":\"home-server\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", wire: "{\"node\":\"home-server\",\"processes\":[{\"fingerprint\":\"src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"service\",\"module\":\"nats\",\"process\":\"nats.service\",\"started\":\"2026-11-09T19:00:00Z\"},{\"kind\":\"container\",\"module\":\"route-proxy\",\"process\":\"route-proxy\",\"started\":\"2026-11-01T08:00:00Z\",\"unknown\":\"started before the node-engine handed MESH_FINGERPRINT\"}]}", decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "process-builds answers an error", subject: "", given: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", wire: "{\"error\":\"the service manager did not answer\",\"node\":\"ace\",\"processes\":[]}", + {name: "process-builds answers an error", subject: "", given: "{\"error\":\"the service manager did not answer\",\"node\":\"home-server\",\"processes\":[]}", wire: "{\"error\":\"the service manager did not answer\",\"node\":\"home-server\",\"processes\":[]}", decode: func(b []byte) (any, error) { var v ProcessBuildsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "first-view-again names the owner, its state and why", subject: "", given: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", wire: "{\"owner\":\"mesh-delivery-indexer\",\"state\":\"manifests\",\"why\":\"the picture lags the indexer by hand\"}", decode: func(b []byte) (any, error) { var v FirstViewAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index 7a76c90..a64f2a7 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -21,17 +21,17 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, {name: "the keeper asks every observer", subject: "mesh.seat.mesh-conditions.event.findings-asked", given: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", wire: "{\"ask\":\"a-20261111t100100\",\"at\":\"2026-11-11T10:01:00Z\",\"by\":\"mesh-conditions\"}", decode: func(b []byte) (any, error) { var v FindingsAskedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.findings-asked$")}, - {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + {name: "a condition raised with its owner and what it waits on (design 47 G 685)", subject: "mesh.seat.mesh-conditions.event.condition-raised", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"change\":\"raised\",\"event\":\"condition-raised\",\"key\":\"module.mesh-host.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"owner\":\"forge:operator\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")}, - {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.ace.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", + {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v ConditionChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-changed$")}, {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", + {name: "a condition carrying its finding's owner, a session, and what it waits on, a seat (design 47 G 685)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator@workstation\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", + {name: "a condition owned by a commit's author, handed to operator-channel when the keeper hands it over (design 47 G 685, 540)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"key\":\"module.mesh-build-node.home-server.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"owner\":\"operator-channel\",\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on home-server is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\",\"waiting-on\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a finding of the bus scope with its zero time (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", wire: "{\"at\":\"0001-01-01T00:00:00Z\",\"evidence\":[{\"at\":\"0001-01-01T00:00:00Z\",\"said\":\"1 held for EVENTS.controller (counted again every 5m0s while any is held, so one delivered again or dropped ends this within it)\"}],\"id\":\"EVENTS.controller\",\"kind\":\"max-deliveries\",\"needs\":\"deliver them again or drop them, from the mesh MCP server.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"bus\",\"severity\":\"warning\",\"since\":\"0001-01-01T00:00:00Z\",\"source\":\"S9\",\"subject\":{\"id\":\"EVENTS.controller\",\"scope\":\"bus\"},\"summary\":\"the controller's consumer on EVENTS gave up on a message; it is kept in DEAD_LETTERS until delivered again or dropped, with why\"}", decode: func(b []byte) (any, error) { @@ -39,19 +39,19 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.ace\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.ace\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", + {name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", + {name: "a finding owned by a session and waiting on a seat (design 47 G 678)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"operator@workstation\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"node-engine\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.ace\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", + {name: "a finding owned by a seat and waiting on a commit's author (design 47 G 678, 540)", subject: "", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"id\":\"mesh-host.home-server\",\"kind\":\"directory-used-as-found\",\"observer\":\"mesh-delivery-watchman\",\"owner\":\"node-engine\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-11-11T10:00:00Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-host.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a directory waits for a hand\",\"waiting-on\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) diff --git a/health-and-repair/go/seats/meshhealers/contract_test.go b/health-and-repair/go/seats/meshhealers/contract_test.go index c0c3e4c..3b58c3c 100644 --- a/health-and-repair/go/seats/meshhealers/contract_test.go +++ b/health-and-repair/go/seats/meshhealers/contract_test.go @@ -17,9 +17,9 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ - {name: "an attempt begun, said with its end (design 47 G 665)", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.ace.directory-used-as-found\",\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", wire: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.ace.directory-used-as-found\",\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", + {name: "an attempt begun, said with its end (design 47 G 665)", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.home-server.directory-used-as-found\",\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", wire: "{\"act\":\"hand-over\",\"begun\":\"2026-11-11T10:00:00Z\",\"budget-key\":\"module.mesh-host.home-server.directory-used-as-found\",\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"healer\":\"directory\",\"kind\":\"directory-used-as-found\",\"outcome\":\"acting\",\"until\":\"2026-11-11T12:00:00Z\"}", decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")}, - {name: "an attempt ended by its healer", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"removed\":true}", wire: "{\"condition\":\"module.mesh-host.ace.directory-used-as-found\",\"removed\":true}", + {name: "an attempt ended by its healer", subject: "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", given: "{\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"removed\":true}", wire: "{\"condition\":\"module.mesh-host.home-server.directory-used-as-found\",\"removed\":true}", decode: func(b []byte) (any, error) { var v AttemptChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-healers\\.event\\.attempt-changed\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "an act a healer would have made, kept from the controller's time (captured)", subject: "", given: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}", wire: "{\"act\":\"assert the module's buckets, logs and streams again through the grants part (grants_assert)\",\"at\":\"2026-11-02T08:15:56.49507336Z\",\"condition\":\"bus.EVENTS.4fs9xzyDY7CD2Cf1wVFYDK_1.consumer-lost\",\"healer\":\"H3\",\"kind\":\"consumer-lost\",\"why\":\"the controller's lease names a controller (or none is written, so one may take it): every act is written as would\"}", decode: func(b []byte) (any, error) { var v WouldByWouldValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/health-and-repair/go/seats/meshwatchdogs/contract_test.go b/health-and-repair/go/seats/meshwatchdogs/contract_test.go index 7b3018b..782d864 100644 --- a/health-and-repair/go/seats/meshwatchdogs/contract_test.go +++ b/health-and-repair/go/seats/meshwatchdogs/contract_test.go @@ -17,9 +17,9 @@ func TestFixtures(t *testing.T) { decode func([]byte) (any, error) subjectIs *regexp.Regexp }{ - {name: "a machine's presence expired", subject: "mesh.seat.mesh-watchdogs.event.machine-away.g14", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"g14\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"g14\",\"v\":1}", + {name: "a machine's presence expired", subject: "mesh.seat.mesh-watchdogs.event.machine-away.laptop", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"laptop\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"last-heard\":\"2026-11-11T09:58:00Z\",\"machine\":\"laptop\",\"v\":1}", decode: func(b []byte) (any, error) { var v MachineAwayEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-away\\.[^.*> ]+$")}, - {name: "a machine heard again", subject: "mesh.seat.mesh-watchdogs.event.machine-back.g14", given: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"g14\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"g14\",\"v\":1}", + {name: "a machine heard again", subject: "mesh.seat.mesh-watchdogs.event.machine-back.laptop", given: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"laptop\",\"v\":1}", wire: "{\"at\":\"2026-11-11T10:30:00Z\",\"last-heard\":\"2026-11-11T10:30:00Z\",\"machine\":\"laptop\",\"v\":1}", decode: func(b []byte) (any, error) { var v MachineBackEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-watchdogs\\.event\\.machine-back\\.[^.*> ]+$")}, {name: "a node's agent online (captured)", subject: "", given: "{\"online\":true,\"v\":1}", wire: "{\"online\":true,\"v\":1}", decode: func(b []byte) (any, error) { var v PresenceByNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/health-and-repair/seats/mesh-conditions/fixtures/events.json b/health-and-repair/seats/mesh-conditions/fixtures/events.json index cc0ad70..3bff1d2 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/events.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/events.json @@ -25,12 +25,12 @@ "of": "event:condition-raised", "subject": "mesh.seat.mesh-conditions.event.condition-raised", "given": { - "key": "module.mesh-host.ace.directory-used-as-found", + "key": "module.mesh-host.home-server.directory-used-as-found", "kind": "directory-used-as-found", "subject": { "scope": "module", - "id": "mesh-host.ace", - "machine": "ace" + "id": "mesh-host.home-server", + "machine": "home-server" }, "severity": "warning", "summary": "a directory waits for a hand", @@ -48,12 +48,12 @@ "of": "event:condition-changed", "subject": "mesh.seat.mesh-conditions.event.condition-changed", "given": { - "key": "module.mesh-delivery.ace.pipeline-failed", + "key": "module.mesh-delivery.home-server.pipeline-failed", "kind": "pipeline-failed", "subject": { "scope": "module", - "id": "mesh-delivery.ace", - "machine": "ace" + "id": "mesh-delivery.home-server", + "machine": "home-server" }, "severity": "warning", "summary": "a head failed its pipeline", diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index f7566d9..5f78e8e 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -7,7 +7,7 @@ "evidence": [ { "at": "2026-10-26T20:19:41.474823121Z", - "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", @@ -27,7 +27,7 @@ "machine": "ace", "scope": "module" }, - "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } }, { @@ -68,7 +68,7 @@ "evidence": [ { "at": "2026-10-26T20:19:41.474823121Z", - "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", @@ -88,7 +88,7 @@ "machine": "ace", "scope": "module" }, - "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", + "summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", "owner": "operator@workstation", "waiting-on": "node-engine" } @@ -101,7 +101,7 @@ "evidence": [ { "at": "2026-10-26T20:19:41.474823121Z", - "said": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" + "said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", @@ -121,7 +121,7 @@ "machine": "ace", "scope": "module" }, - "summary": "mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", + "summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", "owner": "operator-channel", "waiting-on": "forge:operator" } @@ -177,7 +177,7 @@ ], "at": "2026-10-26T20:19:41.474823121Z", "scope": "module", - "id": "mesh-build-node.ace", + "id": "mesh-build-node.home-server", "since": "2026-10-26T20:19:41.474823121Z" } }, @@ -188,8 +188,8 @@ "kind": "directory-used-as-found", "subject": { "scope": "module", - "id": "mesh-host.ace", - "machine": "ace" + "id": "mesh-host.home-server", + "machine": "home-server" }, "severity": "warning", "summary": "a directory waits for a hand", @@ -199,7 +199,7 @@ "owner": "operator@workstation", "waiting-on": "node-engine", "scope": "module", - "id": "mesh-host.ace", + "id": "mesh-host.home-server", "since": "2026-11-11T10:00:00Z" } }, @@ -210,8 +210,8 @@ "kind": "directory-used-as-found", "subject": { "scope": "module", - "id": "mesh-host.ace", - "machine": "ace" + "id": "mesh-host.home-server", + "machine": "home-server" }, "severity": "warning", "summary": "a directory waits for a hand", @@ -221,7 +221,7 @@ "owner": "node-engine", "waiting-on": "forge:operator", "scope": "module", - "id": "mesh-host.ace", + "id": "mesh-host.home-server", "since": "2026-11-11T10:00:00Z" } } diff --git a/health-and-repair/seats/mesh-healers/fixtures/events.json b/health-and-repair/seats/mesh-healers/fixtures/events.json index abe6d7f..d9ad3e8 100644 --- a/health-and-repair/seats/mesh-healers/fixtures/events.json +++ b/health-and-repair/seats/mesh-healers/fixtures/events.json @@ -5,9 +5,9 @@ "subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", "given": { "healer": "directory", - "condition": "module.mesh-host.ace.directory-used-as-found", + "condition": "module.mesh-host.home-server.directory-used-as-found", "kind": "directory-used-as-found", - "budget-key": "module.mesh-host.ace.directory-used-as-found", + "budget-key": "module.mesh-host.home-server.directory-used-as-found", "act": "hand-over", "outcome": "acting", "begun": "2026-11-11T10:00:00Z", @@ -19,7 +19,7 @@ "of": "event:attempt-changed", "subject": "mesh.seat.mesh-healers.event.attempt-changed.c-1.a-1", "given": { - "condition": "module.mesh-host.ace.directory-used-as-found", + "condition": "module.mesh-host.home-server.directory-used-as-found", "removed": true } } diff --git a/health-and-repair/seats/mesh-watchdogs/fixtures/events.json b/health-and-repair/seats/mesh-watchdogs/fixtures/events.json index 2c50557..2316bb8 100644 --- a/health-and-repair/seats/mesh-watchdogs/fixtures/events.json +++ b/health-and-repair/seats/mesh-watchdogs/fixtures/events.json @@ -2,10 +2,10 @@ { "name": "a machine's presence expired", "of": "event:machine-away", - "subject": "mesh.seat.mesh-watchdogs.event.machine-away.g14", + "subject": "mesh.seat.mesh-watchdogs.event.machine-away.laptop", "given": { "v": 1, - "machine": "g14", + "machine": "laptop", "at": "2026-11-11T10:00:00Z", "last-heard": "2026-11-11T09:58:00Z" } @@ -13,10 +13,10 @@ { "name": "a machine heard again", "of": "event:machine-back", - "subject": "mesh.seat.mesh-watchdogs.event.machine-back.g14", + "subject": "mesh.seat.mesh-watchdogs.event.machine-back.laptop", "given": { "v": 1, - "machine": "g14", + "machine": "laptop", "at": "2026-11-11T10:30:00Z", "last-heard": "2026-11-11T10:30:00Z" } diff --git a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go index fc61d8b..e4063c2 100644 --- a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go +++ b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go @@ -32,27 +32,26 @@ func TestATokenLifeAndTheRedeemProofAreAsTheHolderMakesThem(t *testing.T) { if got := (RedeemAnswer{Node: "g14", Signature: "x"}).SignedBytes(); string(got) == "" || string(got) == "x" { t.Errorf("SignedBytes = %s", got) } -} - -// TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and -// the contract's reads back as the client's wire. -func TestTheRedeemAnswerIsTheContractsWire(t *testing.T) { - mine := RedeemAnswer{Node: "g14", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} - wire, _ := json.Marshal(mine) - var theirs seat.RedeemAnswer - d := json.NewDecoder(bytes.NewReader(wire)) - d.DisallowUnknownFields() - if err := d.Decode(&theirs); err != nil { - t.Fatal(err) - } - if theirs.Node != "g14" || theirs.Signer != "dg==" || theirs.Signature != "cw==" { - t.Errorf("the contract reads %+v", theirs) - } - back, _ := json.Marshal(theirs) - var a, b map[string]string - _ = json.Unmarshal(wire, &a) - _ = json.Unmarshal(back, &b) - if len(a) != 6 || !reflect.DeepEqual(a, b) { - t.Errorf("the contract reads %s back as %s", wire, back) - } + // TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and + // the contract's reads back as the client's wire. + t.Run("TheRedeemAnswerIsTheContractsWire", func(t *testing.T) { + mine := RedeemAnswer{Node: "g14", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} + wire, _ := json.Marshal(mine) + var theirs seat.RedeemAnswer + d := json.NewDecoder(bytes.NewReader(wire)) + d.DisallowUnknownFields() + if err := d.Decode(&theirs); err != nil { + t.Fatal(err) + } + if theirs.Node != "g14" || theirs.Signer != "dg==" || theirs.Signature != "cw==" { + t.Errorf("the contract reads %+v", theirs) + } + back, _ := json.Marshal(theirs) + var a, b map[string]string + _ = json.Unmarshal(wire, &a) + _ = json.Unmarshal(back, &b) + if len(a) != 6 || !reflect.DeepEqual(a, b) { + t.Errorf("the contract reads %s back as %s", wire, back) + } + }) } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go index 7fd0ce8..92732b9 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/client_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/client_test.go @@ -2,6 +2,7 @@ package operatorchannelclient import ( "encoding/json" + "errors" "strings" "testing" "time" @@ -88,6 +89,51 @@ func TestAnAskIsKeptThenPublishedUnderTheModulesOwnName(t *testing.T) { if err := c.Ask(bad); err == nil { t.Error("an ask the contract refuses was published") } + t.Run("AKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere", func(t *testing.T) { + for _, tc := range []struct{ prefix, key string }{{"n1.", "n1.ask.d-1"}, {"", "ask.d-1"}} { + c, _ := client() + store := c.State.(*mem) + c.KeyPrefix = tc.prefix + var asked string + c.Record = func(k string) (*stdio.StateEntry, error) { asked = k; return nil, nil } + if err := c.Ask(askedHeld()); err != nil { + t.Fatal(err) + } + if _, ok := store.vals[tc.key]; len(store.vals) != 1 || !ok { + t.Fatalf("prefix %q: keys written %v, want %s", tc.prefix, store.vals, tc.key) + } + // Design 46 7-approval-mark §13: the act and the call's arguments kept beside the ask stay as Take marks it. + e, _ := store.Get(tc.key) + var k Kept + _ = json.Unmarshal(e.Value, &k) + k.Act, k.Arguments = releaseHQ, json.RawMessage(`{"delivery":"hq"}`) + if _, err := store.Update(tc.key, k, e.Revision); err != nil { + t.Fatal(err) + } + if h, err := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { return nil }); h != Acted || err != nil { + t.Fatalf("prefix %q: the warrant was not read from %s: %s %v", tc.prefix, tc.key, h, err) + } + raw := string(store.vals[tc.key]) + if !strings.Contains(raw, `"act":{"delivery":"hq","verb":"release"}`) || !strings.Contains(raw, `"arguments":{"delivery":"hq"}`) || strings.Contains(raw, `"recorded"`) { + t.Errorf("prefix %q: the kept ask after Take is %s", tc.prefix, raw) + } + if _, _, err := c.Where("an-asker.d-1"); err != nil || asked != "an-asker.d-1" { + t.Errorf("prefix %q: Where read %q", tc.prefix, asked) + } + } + }) + // Design 47 G §700, A-91: Where reads the router's record as the contract's typed value, its warrant included. + t.Run("WhereReadsTheRecordsWarrantTyped", func(t *testing.T) { + c, _ := client() + rec := seat.AsksByAskerIDValue{Key: "an-asker.d-1", Asker: "an-asker", State: "chosen", + Warrant: &seat.Warrant{Ask: "d-1", Asker: "an-asker", Outcome: seat.WarrantOutcomeChosen, Option: "ok"}} + raw, _ := json.Marshal(rec) + c.Record = func(string) (*stdio.StateEntry, error) { return &stdio.StateEntry{Value: raw}, nil } + state, w, err := c.Where("d-1") + if err != nil || state != "chosen" || w == nil || w.Option != "ok" { + t.Fatalf("Where = %q, %+v, %v; want chosen and the record's warrant", state, w, err) + } + }) } func TestAWarrantIsActedOnOnceAndOnlyForItsOwnAsk(t *testing.T) { @@ -126,6 +172,109 @@ func TestAWarrantIsActedOnOnceAndOnlyForItsOwnAsk(t *testing.T) { if acted != 1 { t.Errorf("acted %d times", acted) } + // The gate's channel (design 47 G lead answers A-219, A-228): the gate's ask raised to the operator at the level approve, + // the router's record read in the gate's form with its warrant whole, and a warrant claimed once, only for the act its + // option binds. + t.Run("TheGateChannelTranslatesTheGatesForms", func(t *testing.T) { + st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} + records := map[string]seat.AsksByAskerIDValue{} + g := &GateChannel{State: st, KeyPrefix: "n1.", Now: func() time.Time { return now }, + Publish: func(module, subject string, body any, id string) error { + if subject != seat.AcceptSubjectAsk(module) { + t.Fatalf("published on %s", subject) + } + return nil + }, + ReadRecord: func(module, id string) (*stdio.StateEntry, error) { + rec, ok := records[module+"."+id] + if !ok { + return nil, nil + } + raw, _ := json.Marshal(rec) + return &stdio.StateEntry{Value: raw}, nil + }} + digest, _ := ActDigest(releaseHQ) + a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), + OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} + if err := g.Ask("shell", a); err != nil { + t.Fatal(err) + } + var k Kept + if e, _ := st.Get("n1.ask.a1"); e == nil || json.Unmarshal(e.Value, &k) != nil || k.Ask.Who != Operator || k.Ask.Options[0].Level != Approve { + t.Fatalf("kept %+v", k) + } + if rec, err := g.Record("shell", "a1"); rec != nil || err != nil { + t.Fatalf("a record not yet there: %+v %v", rec, err) + } + w := seat.Warrant{Ask: "a1", Asker: "shell", Outcome: OutcomeChosen, Option: "approve", Level: Approve, At: FormatTime(now), + AskDigest: Digest(k.Ask), Channel: "telegram", By: &seat.Person{Who: Operator, Kind: "telegram"}} + records["shell.a1"] = seat.AsksByAskerIDValue{Asker: "shell", State: "chosen", Opened: FormatTime(now), Warrant: &w} + rec, err := g.Record("shell", "a1") + if err != nil || rec == nil || rec.State != "chosen" || rec.Warrant == nil || rec.Warrant.Channel != "telegram" || rec.Warrant.Option != "approve" { + t.Fatalf("record %+v %v", rec, err) + } + if h, err := g.Claim("shell", *rec.Warrant, map[string]string{"verb": "other"}, func() { t.Fatal("ran another act") }); h != approval.Claimed || err == nil { + t.Fatalf("another act: %s %v", h, err) + } + delete(st.vals, "n1.ask.a1") + _ = g.Ask("shell", a) + runs := 0 + for i := 0; i < 2; i++ { + h, err := g.Claim("shell", *rec.Warrant, releaseHQ, func() { runs++ }) + if want := []approval.Claim{approval.Claimed, approval.ClaimDone}[i]; h != want || err != nil { + t.Fatalf("claim %d: %s %v", i, h, err) + } + } + if runs != 1 || g.Decided("shell") != seat.SubjectDecided("shell") { + t.Fatalf("runs %d", runs) + } + }) + // The gate's channel over a process connection (design 47 G lead answers A-272, A-273): an ask and its cancel go out as + // accepted kinds of the seat operator-channel with the ask's id as the message id, the router's record is the get of + // `.` in the state asks of the seat's holder, and nothing else is reached: another subject, or a seat with no + // holder, is refused. + t.Run("TheGateChannelOverAConnectionAsksAndReadsOnlyThroughTheSeat", func(t *testing.T) { + type sent struct{ seat, kind, id string } + var out []sent + accept := func(s, kind string, _ any, opts ...stdio.EmitOptions) error { + out = append(out, sent{s, kind, opts[0].MessageID}) + return nil + } + raw, _ := json.Marshal(seat.AsksByAskerIDValue{Asker: "shell", State: "open", Opened: FormatTime(now)}) + vals := map[string]json.RawMessage{"messenger_holder.asks|shell.a1": raw, "other.asks|shell.a1": json.RawMessage(`{"state":"wrong"}`)} + read := func(r string) asksRead { return readOf{state: r, vals: vals} } + holder := func() (string, error) { return "messenger_holder", nil } + st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} + g := gateChannelOver(accept, read, st, "n1.", holder) + g.Now = func() time.Time { return now } + + digest, _ := ActDigest(releaseHQ) + a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), + OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} + if err := g.Ask("shell", a); err != nil { + t.Fatal(err) + } + if err := g.Cancel("shell", "a1"); err != nil { + t.Fatal(err) + } + if len(out) != 2 || out[0] != (sent{seat.Seat, seat.AcceptAsk, "a1"}) || out[1] != (sent{seat.Seat, seat.AcceptCancel, "cancel.a1"}) { + t.Fatalf("sent %+v, want the ask and its cancel on the seat's accepts", out) + } + if rec, err := g.Record("shell", "a1"); err != nil || rec == nil || rec.State != "open" { + t.Fatalf("record %+v %v, want the one in the holder's state asks", rec, err) + } + if rec, err := g.Record("shell", "zz"); err != nil || rec != nil { + t.Fatalf("a record not there: %+v %v", rec, err) + } + if err := g.Publish("shell", "mesh.seat.operator-channel.accept.ask.other", nil, "x"); err == nil { + t.Fatal("an accept subject naming another caller was sent") + } + for _, c := range []func() (string, error){func() (string, error) { return "", nil }, func() (string, error) { return "", errors.New("unread") }} { + if _, err := gateChannelOver(accept, read, st, "n1.", c).Record("shell", "a1"); err == nil { + t.Fatal("a record was read with no holder of the seat") + } + } + }) } func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) { @@ -139,123 +288,17 @@ func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) { if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done { t.Errorf("%s", h) } -} - -func TestAnAskTheRouterRefusedEndsTheRequestWithItsWords(t *testing.T) { - c, _ := client() - _ = c.Ask(askedHeld()) - w := askedWarrant() - w.Outcome, w.Option, w.By, w.Words = OutcomeRefused, "", nil, "its expiry passes the bound of its level" - h, err := c.Take(w, func(seat.Option, seat.Warrant) error { t.Fatal("acted"); return nil }) - if h != Refused || err == nil || !strings.Contains(err.Error(), w.Words) { - t.Fatalf("%s %v, want refused with the router's words", h, err) - } - if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done { - t.Errorf("the refused ask was not closed: %s", h) - } -} - -func TestAKeyPrefixIsPutBeforeEveryKeyOfTheClientsOwnStateAndNotBeforeWhere(t *testing.T) { - for _, tc := range []struct{ prefix, key string }{{"n1.", "n1.ask.d-1"}, {"", "ask.d-1"}} { + t.Run("AnAskTheRouterRefusedEndsTheRequestWithItsWords", func(t *testing.T) { c, _ := client() - store := c.State.(*mem) - c.KeyPrefix = tc.prefix - var asked string - c.Record = func(k string) (*stdio.StateEntry, error) { asked = k; return nil, nil } - if err := c.Ask(askedHeld()); err != nil { - t.Fatal(err) + _ = c.Ask(askedHeld()) + w := askedWarrant() + w.Outcome, w.Option, w.By, w.Words = OutcomeRefused, "", nil, "its expiry passes the bound of its level" + h, err := c.Take(w, func(seat.Option, seat.Warrant) error { t.Fatal("acted"); return nil }) + if h != Refused || err == nil || !strings.Contains(err.Error(), w.Words) { + t.Fatalf("%s %v, want refused with the router's words", h, err) } - if _, ok := store.vals[tc.key]; len(store.vals) != 1 || !ok { - t.Fatalf("prefix %q: keys written %v, want %s", tc.prefix, store.vals, tc.key) + if h, _ := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done { + t.Errorf("the refused ask was not closed: %s", h) } - // Design 46 7-approval-mark §13: the act and the call's arguments kept beside the ask stay as Take marks it. - e, _ := store.Get(tc.key) - var k Kept - _ = json.Unmarshal(e.Value, &k) - k.Act, k.Arguments = releaseHQ, json.RawMessage(`{"delivery":"hq"}`) - if _, err := store.Update(tc.key, k, e.Revision); err != nil { - t.Fatal(err) - } - if h, err := c.Take(askedWarrant(), func(seat.Option, seat.Warrant) error { return nil }); h != Acted || err != nil { - t.Fatalf("prefix %q: the warrant was not read from %s: %s %v", tc.prefix, tc.key, h, err) - } - raw := string(store.vals[tc.key]) - if !strings.Contains(raw, `"act":{"delivery":"hq","verb":"release"}`) || !strings.Contains(raw, `"arguments":{"delivery":"hq"}`) || strings.Contains(raw, `"recorded"`) { - t.Errorf("prefix %q: the kept ask after Take is %s", tc.prefix, raw) - } - if _, _, err := c.Where("an-asker.d-1"); err != nil || asked != "an-asker.d-1" { - t.Errorf("prefix %q: Where read %q", tc.prefix, asked) - } - } -} - -// Design 47 G §700, A-91: Where reads the router's record as the contract's typed value, its warrant included. -func TestWhereReadsTheRecordsWarrantTyped(t *testing.T) { - c, _ := client() - rec := seat.AsksByAskerIDValue{Key: "an-asker.d-1", Asker: "an-asker", State: "chosen", - Warrant: &seat.Warrant{Ask: "d-1", Asker: "an-asker", Outcome: seat.WarrantOutcomeChosen, Option: "ok"}} - raw, _ := json.Marshal(rec) - c.Record = func(string) (*stdio.StateEntry, error) { return &stdio.StateEntry{Value: raw}, nil } - state, w, err := c.Where("d-1") - if err != nil || state != "chosen" || w == nil || w.Option != "ok" { - t.Fatalf("Where = %q, %+v, %v; want chosen and the record's warrant", state, w, err) - } -} - -// The gate's channel (design 47 G lead answers A-219, A-228): the gate's ask raised to the operator at the level approve, -// the router's record read in the gate's form with its warrant whole, and a warrant claimed once, only for the act its -// option binds. -func TestTheGateChannelTranslatesTheGatesForms(t *testing.T) { - st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} - records := map[string]seat.AsksByAskerIDValue{} - g := &GateChannel{State: st, KeyPrefix: "n1.", Now: func() time.Time { return now }, - Publish: func(module, subject string, body any, id string) error { - if subject != seat.AcceptSubjectAsk(module) { - t.Fatalf("published on %s", subject) - } - return nil - }, - ReadRecord: func(module, id string) (*stdio.StateEntry, error) { - rec, ok := records[module+"."+id] - if !ok { - return nil, nil - } - raw, _ := json.Marshal(rec) - return &stdio.StateEntry{Value: raw}, nil - }} - digest, _ := ActDigest(releaseHQ) - a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), - OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} - if err := g.Ask("shell", a); err != nil { - t.Fatal(err) - } - var k Kept - if e, _ := st.Get("n1.ask.a1"); e == nil || json.Unmarshal(e.Value, &k) != nil || k.Ask.Who != Operator || k.Ask.Options[0].Level != Approve { - t.Fatalf("kept %+v", k) - } - if rec, err := g.Record("shell", "a1"); rec != nil || err != nil { - t.Fatalf("a record not yet there: %+v %v", rec, err) - } - w := seat.Warrant{Ask: "a1", Asker: "shell", Outcome: OutcomeChosen, Option: "approve", Level: Approve, At: FormatTime(now), - AskDigest: Digest(k.Ask), Channel: "telegram", By: &seat.Person{Who: Operator, Kind: "telegram"}} - records["shell.a1"] = seat.AsksByAskerIDValue{Asker: "shell", State: "chosen", Opened: FormatTime(now), Warrant: &w} - rec, err := g.Record("shell", "a1") - if err != nil || rec == nil || rec.State != "chosen" || rec.Warrant == nil || rec.Warrant.Channel != "telegram" || rec.Warrant.Option != "approve" { - t.Fatalf("record %+v %v", rec, err) - } - if h, err := g.Claim("shell", *rec.Warrant, map[string]string{"verb": "other"}, func() { t.Fatal("ran another act") }); h != approval.Claimed || err == nil { - t.Fatalf("another act: %s %v", h, err) - } - delete(st.vals, "n1.ask.a1") - _ = g.Ask("shell", a) - runs := 0 - for i := 0; i < 2; i++ { - h, err := g.Claim("shell", *rec.Warrant, releaseHQ, func() { runs++ }) - if want := []approval.Claim{approval.Claimed, approval.ClaimDone}[i]; h != want || err != nil { - t.Fatalf("claim %d: %s %v", i, h, err) - } - } - if runs != 1 || g.Decided("shell") != seat.SubjectDecided("shell") { - t.Fatalf("runs %d", runs) - } + }) } diff --git a/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go index fbacc0c..8c119b1 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/gate_conn_test.go @@ -2,13 +2,8 @@ package operatorchannelclient import ( "encoding/json" - "errors" - "testing" - "time" - seat "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" stdio "git.novox.be/novox/mesh-sdk/go" - "git.novox.be/novox/mesh-sdk/go/approval" ) type readOf struct { @@ -22,50 +17,3 @@ func (r readOf) Get(key string) (*stdio.StateEntry, error) { } return nil, nil } - -// The gate's channel over a process connection (design 47 G lead answers A-272, A-273): an ask and its cancel go out as -// accepted kinds of the seat operator-channel with the ask's id as the message id, the router's record is the get of -// `.` in the state asks of the seat's holder, and nothing else is reached: another subject, or a seat with no -// holder, is refused. -func TestTheGateChannelOverAConnectionAsksAndReadsOnlyThroughTheSeat(t *testing.T) { - type sent struct{ seat, kind, id string } - var out []sent - accept := func(s, kind string, _ any, opts ...stdio.EmitOptions) error { - out = append(out, sent{s, kind, opts[0].MessageID}) - return nil - } - raw, _ := json.Marshal(seat.AsksByAskerIDValue{Asker: "shell", State: "open", Opened: FormatTime(now)}) - vals := map[string]json.RawMessage{"messenger_holder.asks|shell.a1": raw, "other.asks|shell.a1": json.RawMessage(`{"state":"wrong"}`)} - read := func(r string) asksRead { return readOf{state: r, vals: vals} } - holder := func() (string, error) { return "messenger_holder", nil } - st := &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}} - g := gateChannelOver(accept, read, st, "n1.", holder) - g.Now = func() time.Time { return now } - - digest, _ := ActDigest(releaseHQ) - a := approval.Ask{ID: "a1", About: digest, Headline: "Run wipe?", Explanation: "Wipes.", Expires: FormatTime(now.Add(time.Hour)), - OnExpiry: "nothing runs", Options: []approval.Option{{ID: "approve", Label: "Approve", Does: "runs", Binds: digest}}} - if err := g.Ask("shell", a); err != nil { - t.Fatal(err) - } - if err := g.Cancel("shell", "a1"); err != nil { - t.Fatal(err) - } - if len(out) != 2 || out[0] != (sent{seat.Seat, seat.AcceptAsk, "a1"}) || out[1] != (sent{seat.Seat, seat.AcceptCancel, "cancel.a1"}) { - t.Fatalf("sent %+v, want the ask and its cancel on the seat's accepts", out) - } - if rec, err := g.Record("shell", "a1"); err != nil || rec == nil || rec.State != "open" { - t.Fatalf("record %+v %v, want the one in the holder's state asks", rec, err) - } - if rec, err := g.Record("shell", "zz"); err != nil || rec != nil { - t.Fatalf("a record not there: %+v %v", rec, err) - } - if err := g.Publish("shell", "mesh.seat.operator-channel.accept.ask.other", nil, "x"); err == nil { - t.Fatal("an accept subject naming another caller was sent") - } - for _, c := range []func() (string, error){func() (string, error) { return "", nil }, func() (string, error) { return "", errors.New("unread") }} { - if _, err := gateChannelOver(accept, read, st, "n1.", c).Record("shell", "a1"); err == nil { - t.Fatal("a record was read with no holder of the seat") - } - } -} diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index bf8142c..2e85efb 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -69,7 +69,7 @@ { "name": "composed is said", "of": "event:composed", - "subject": "mesh.seat.node-engine.event.composed.ace", + "subject": "mesh.seat.node-engine.event.composed.home-server", "given": { "v": 1, "node": "ace", @@ -82,7 +82,7 @@ { "name": "running is said, its node and module in its subject", "of": "event:running", - "subject": "mesh.seat.node-engine.event.running.ace.nats", + "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, "node": "ace", @@ -95,7 +95,7 @@ { "name": "running says the build that runs is healthy", "of": "event:running", - "subject": "mesh.seat.node-engine.event.running.ace.nats", + "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, "node": "ace", @@ -109,7 +109,7 @@ { "name": "running says the build that runs turned unhealthy, still running", "of": "event:running", - "subject": "mesh.seat.node-engine.event.running.ace.nats", + "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, "node": "ace", @@ -123,7 +123,7 @@ { "name": "running says a module stopped on the node, with no fingerprint", "of": "event:running", - "subject": "mesh.seat.node-engine.event.running.ace.nats", + "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, "node": "ace", @@ -135,7 +135,7 @@ { "name": "a kept build's wait is held", "of": "event:wait-held", - "subject": "mesh.seat.node-engine.event.wait-held.ace.postgres", + "subject": "mesh.seat.node-engine.event.wait-held.home-server.postgres", "given": { "owner": "node-engine", "step": "kept-build", @@ -144,14 +144,14 @@ "bound": "60m", "since": "2026-11-11T10:00:00Z", "clock-from": "2026-11-11T10:00:00Z", - "words": "waiting for the kept build of postgres on ace", + "words": "waiting for the kept build of postgres on home-server", "reason": "node away" } }, { "name": "a hold of the composition ends", "of": "event:wait-ended", - "subject": "mesh.seat.node-engine.event.wait-ended.ace.postgres", + "subject": "mesh.seat.node-engine.event.wait-ended.home-server.postgres", "given": { "owner": "node-engine", "step": "compose", From 5e95cbed5936d540ef24bbfb69abb575cf36abe5 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 22:48:01 +0100 Subject: [PATCH 61/62] A-316: the assigner's candidate gains added, the version and parts the want it would write carries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The state candidates' value (CandidatesByProposalNodeValue) gains `added`, by module name, each an AddedModule with `version` and `parts` in the want's own forms. It is a copy of the two properties of the seat mesh-wants' state wants, because the seat-definition format cannot reuse another repository's seat's forms (includes take only parts/ of the same repository, and a part holds no state value); a fixture holds both to the want's wire. Regenerated with seatgen. The node names the first round-2 pass left in fixtures lines equal to base lines are role names now, the generated tests with them. Builds: design 47 G A-316 (corrected, hq #594), §626 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seats/meshmoduleassigner/contract.go | 10 ++++++++ go/seats/meshmoduleassigner/contract_test.go | 2 +- go/seats/nodeengine/contract_test.go | 2 +- .../go/seats/meshconditions/contract_test.go | 4 ++-- .../mesh-conditions/fixtures/states.json | 24 +++++++++---------- .../meshnodeenrollerclient/enrolment_test.go | 4 ++-- .../mesh-module-assigner/fixtures/states.json | 18 ++++++++++---- seats/mesh-module-assigner/seat.json | 24 +++++++++++++++++++ seats/node-engine/fixtures/events.json | 12 +++++----- seats/node-engine/fixtures/verbs.json | 4 ++-- ts/seats/meshmoduleassigner/index.d.ts | 10 ++++++++ 11 files changed, 83 insertions(+), 31 deletions(-) diff --git a/go/seats/meshmoduleassigner/contract.go b/go/seats/meshmoduleassigner/contract.go index e8a5beb..c260a03 100644 --- a/go/seats/meshmoduleassigner/contract.go +++ b/go/seats/meshmoduleassigner/contract.go @@ -344,6 +344,14 @@ func DecodeSeatHoldersBySeatNodeValue(raw []byte) (SeatHoldersBySeatNodeValue, e return v, nil } +// AddedModule is what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316). +type AddedModule struct { + // the digest of each of the module's parts, by `:` (design 47 G section 379) + Parts map[string]string `json:"parts,omitempty"` + // the module's released version, for people; none for a build of another watched branch (design 47 G section 379) + Version string `json:"version,omitempty"` +} + // Assignments is one node's assignments assembled. type Assignments struct { Decided NodeDecided `json:"decided"` @@ -687,6 +695,8 @@ type ProposalsByProposalValue = Proposal // CandidatesByProposalNodeValue is one value of the state candidates under the key .. type CandidatesByProposalNodeValue struct { + // by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry + Added map[string]AddedModule `json:"added,omitempty"` // the node's assignments with the proposal laid over it; absent when the proposal takes its key away Assignments *Assignments `json:"assignments,omitempty"` Proposal string `json:"proposal"` diff --git a/go/seats/meshmoduleassigner/contract_test.go b/go/seats/meshmoduleassigner/contract_test.go index e38965e..b083e81 100644 --- a/go/seats/meshmoduleassigner/contract_test.go +++ b/go/seats/meshmoduleassigner/contract_test.go @@ -59,7 +59,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a candidate", subject: "", given: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", wire: "{\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", + {name: "a candidate, with the modules it adds and what their wants would carry", subject: "", given: "{\"added\":{\"mesh-build-go\":{\"parts\":{\"mesh-build-go:go-binary\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"version\":\"1.4.0\"}},\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", wire: "{\"added\":{\"mesh-build-go\":{\"parts\":{\"mesh-build-go:go-binary\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"version\":\"1.4.0\"}},\"proposal\":\"p-20261105t120000-aabbccdd\",\"v\":1}", decode: func(b []byte) (any, error) { var v CandidatesByProposalNodeValue err := json.Unmarshal(b, &v) diff --git a/go/seats/nodeengine/contract_test.go b/go/seats/nodeengine/contract_test.go index 1872313..4ebf1aa 100644 --- a/go/seats/nodeengine/contract_test.go +++ b/go/seats/nodeengine/contract_test.go @@ -85,7 +85,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "the bus module's have carries the user list written (typed from the engine's values)", subject: "", given: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", wire: "{\"health\":\"ok\",\"phase\":\"running\",\"user-list\":{\"at\":\"2026-11-05T12:00:00Z\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"follows\":\"grants\",\"handed\":{\"at\":\"2026-11-05T12:00:00Z\",\"box\":{\"ct\":\"c\",\"eph\":\"e\",\"iv\":\"i\",\"tag\":\"t\",\"v\":1},\"from\":\"ace\",\"to\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"users\":3},\"key\":\"-----BEGIN PUBLIC KEY-----\",\"revision\":7,\"source\":\"user-list\",\"users\":3,\"wanted\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"home-server\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"home-server\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", + {name: "a node's own facts with its record and an answer to a candidate (typed from the engine's values)", subject: "", given: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", wire: "{\"candidates\":{\"p1\":{\"added\":[{\"module\":\"db\",\"unissued\":[\"db.secret\"]}],\"differs\":[{\"bodies\":[{\"id\":\"api.cfg\",\"paths\":[\"/etc/api.conf\"],\"why\":\"content\"}],\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"module\":\"api\",\"running\":\"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"why\":\"a file differs\"}],\"proposal\":\"p1\",\"refusals\":[{\"module\":\"mail\",\"today\":\"runs\",\"why\":\"a value is missing\"}],\"removed\":[\"old\"],\"revision\":4,\"same\":[\"web\"],\"verdict\":\"differs\"}},\"composed\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"composes\":\"own\",\"record\":{\"capabilities\":[\"approval-mark/1\",\"docker\"],\"contract\":3,\"networks\":[{\"link\":\"eth0\",\"network\":\"192.0.2.0/24\"}],\"networks-said\":true,\"node\":\"ace\",\"runner-capabilities\":[\"approval-mark/1\"],\"runner-fingerprint\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"tunnel-key\":\"k\",\"v\":1},\"v\":1}", decode: func(b []byte) (any, error) { var v HaveByNodeNodeValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a module's data items on a node (typed from the engine's values)", subject: "", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"items\":[{\"class\":\"database\",\"covered_by\":\"/var/lib/postgres\",\"item\":\"cluster\",\"measure\":\"dataset\",\"module\":\"postgres\",\"path\":\"/var/lib/postgres\",\"protection\":\"backup\"}],\"module\":\"postgres\",\"node\":\"ace\",\"v\":1}", decode: func(b []byte) (any, error) { var v DataByNodeModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/health-and-repair/go/seats/meshconditions/contract_test.go b/health-and-repair/go/seats/meshconditions/contract_test.go index a64f2a7..bb12b8a 100644 --- a/health-and-repair/go/seats/meshconditions/contract_test.go +++ b/health-and-repair/go/seats/meshconditions/contract_test.go @@ -25,7 +25,7 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ConditionRaisedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-raised$")}, {name: "a condition's owner handed to the operator after two hours (design 47 G 540, A-58)", subject: "mesh.seat.mesh-conditions.event.condition-changed", given: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", wire: "{\"at\":\"2026-11-11T12:00:00Z\",\"change\":\"owner\",\"event\":\"condition-changed\",\"key\":\"module.mesh-delivery.home-server.pipeline-failed\",\"kind\":\"pipeline-failed\",\"owner\":\"operator-channel\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"runner\",\"subject\":{\"id\":\"mesh-delivery.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"a head failed its pipeline\",\"waiting-on\":\"operator-channel\",\"was\":\"forge:operator\"}", decode: func(b []byte) (any, error) { var v ConditionChangedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-conditions\\.event\\.condition-changed$")}, - {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `ace/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", + {name: "a condition raised from a finding, as the keeper holds it (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"key\":\"module.mesh-build-node.ace.directory-used-as-found\",\"kind\":\"directory-used-as-found\",\"last-observed\":\"2026-10-26T20:19:41.474823121Z\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.076843727Z\",\"resolved\":\"mesh-build-node's directory on ace is the mesh's\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a condition with an empty evidence trail of headline (captured; empty fields left out)", subject: "", given: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", wire: "{\"count\":1,\"evidence\":[{\"at\":\"2026-10-30T13:03:46.432309782Z\",\"said\":\"The backup of postgres failed on ace\"}],\"explanation\":\"Needs you: answer whether to back up again or go on without a backup. The backup before applying postgres at 978b5db8cb4e on ace failed: node-backup.now could not be asked: not asked: nothing on this machine answers mesh.seat.node-backup.tool.now.ace.\",\"headline\":\"The backup of postgres failed on ace\",\"key\":\"module.ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f.backup\",\"kind\":\"backup\",\"last-observed\":\"2026-10-30T13:03:46.432309782Z\",\"needs\":\"answer whether to back up again or go on without a backup\",\"observations\":1,\"raised\":\"2026-10-31T08:19:57.069818178Z\",\"resolver\":\"self\",\"severity\":\"warning\",\"source\":\"assigner.backup\",\"subject\":{\"id\":\"ace.postgres.978b5db8cb4ef746ce68d82cc616d1439a53266d335e60f368dc44c4cb25610f\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"The backup of postgres failed on ace\"}", decode: func(b []byte) (any, error) { var v ConditionsByKeyValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, @@ -39,7 +39,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on home-server uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on home-server\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.home-server\",\"machine\":\"home-server\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on home-server uses mesh-build-node.cache as found\"}", + {name: "a finding of the module scope with its machine (in the finding layout (design 47 G 660))", subject: "", given: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", wire: "{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"evidence\":[{\"at\":\"2026-10-26T20:19:41.474823121Z\",\"said\":\"mesh-build-node on ace uses mesh-build-node.cache as found: owned by 10005:10005, mode 700, as found\"}],\"explanation\":\"Needs you: hand the directory over from the control-node, as the operator.\",\"headline\":\"mesh-build-node waits for a directory on ace\",\"id\":\"mesh-build-node.home-server\",\"kind\":\"directory-used-as-found\",\"needs\":\"hand the directory over from the control-node, as the operator; the details name it and the line to type.\",\"observer\":\"mesh-delivery-watchman\",\"scope\":\"module\",\"severity\":\"warning\",\"since\":\"2026-10-26T20:19:41.474823121Z\",\"source\":\"health-report\",\"subject\":{\"id\":\"mesh-build-node.ace\",\"machine\":\"ace\",\"scope\":\"module\"},\"summary\":\"mesh-build-node on ace uses mesh-build-node.cache as found\"}", decode: func(b []byte) (any, error) { var v FindingsByScopeIDKindValue err := json.Unmarshal(b, &v) diff --git a/health-and-repair/seats/mesh-conditions/fixtures/states.json b/health-and-repair/seats/mesh-conditions/fixtures/states.json index 5f78e8e..6422a5a 100644 --- a/health-and-repair/seats/mesh-conditions/fixtures/states.json +++ b/health-and-repair/seats/mesh-conditions/fixtures/states.json @@ -71,21 +71,21 @@ "said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], - "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", - "headline": "mesh-build-node waits for a directory on ace", - "key": "module.mesh-build-node.ace.directory-used-as-found", + "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.", + "headline": "mesh-build-node waits for a directory on home-server", + "key": "module.mesh-build-node.home-server.directory-used-as-found", "kind": "directory-used-as-found", "last-observed": "2026-10-26T20:19:41.474823121Z", "needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.", "observations": 1, "raised": "2026-10-31T08:19:57.076843727Z", - "resolved": "mesh-build-node's directory on ace is the mesh's", + "resolved": "mesh-build-node's directory on home-server is the mesh's", "resolver": "self", "severity": "warning", "source": "health-report", "subject": { - "id": "mesh-build-node.ace", - "machine": "ace", + "id": "mesh-build-node.home-server", + "machine": "home-server", "scope": "module" }, "summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", @@ -104,21 +104,21 @@ "said": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh" } ], - "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on ace, with another owner or mode than mesh-build-node declares.", - "headline": "mesh-build-node waits for a directory on ace", - "key": "module.mesh-build-node.ace.directory-used-as-found", + "explanation": "Needs you: hand the directory over from the control-node, as the operator; the details name it and the line to type. A directory of mesh-build-node was already on home-server, with another owner or mode than mesh-build-node declares.", + "headline": "mesh-build-node waits for a directory on home-server", + "key": "module.mesh-build-node.home-server.directory-used-as-found", "kind": "directory-used-as-found", "last-observed": "2026-10-26T20:19:41.474823121Z", "needs": "hand the directory over from the control-node, as the operator; the details name it and the line to type.", "observations": 1, "raised": "2026-10-31T08:19:57.076843727Z", - "resolved": "mesh-build-node's directory on ace is the mesh's", + "resolved": "mesh-build-node's directory on home-server is the mesh's", "resolver": "self", "severity": "warning", "source": "health-report", "subject": { - "id": "mesh-build-node.ace", - "machine": "ace", + "id": "mesh-build-node.home-server", + "machine": "home-server", "scope": "module" }, "summary": "mesh-build-node on home-server uses mesh-build-node.cache as found: used as found: owned by 10005:10005, mode 700, as found; mesh-build-node, mode 0711 was declared and not given it — `home-server/node-engine.hand-over` with the directory's path, then your yes on your channel, with its path, hands it to the mesh", diff --git a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go index e4063c2..1628885 100644 --- a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go +++ b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go @@ -35,7 +35,7 @@ func TestATokenLifeAndTheRedeemProofAreAsTheHolderMakesThem(t *testing.T) { // TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and // the contract's reads back as the client's wire. t.Run("TheRedeemAnswerIsTheContractsWire", func(t *testing.T) { - mine := RedeemAnswer{Node: "g14", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} + mine := RedeemAnswer{Node: "laptop", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} wire, _ := json.Marshal(mine) var theirs seat.RedeemAnswer d := json.NewDecoder(bytes.NewReader(wire)) @@ -43,7 +43,7 @@ func TestATokenLifeAndTheRedeemProofAreAsTheHolderMakesThem(t *testing.T) { if err := d.Decode(&theirs); err != nil { t.Fatal(err) } - if theirs.Node != "g14" || theirs.Signer != "dg==" || theirs.Signature != "cw==" { + if theirs.Node != "laptop" || theirs.Signer != "dg==" || theirs.Signature != "cw==" { t.Errorf("the contract reads %+v", theirs) } back, _ := json.Marshal(theirs) diff --git a/seats/mesh-module-assigner/fixtures/states.json b/seats/mesh-module-assigner/fixtures/states.json index d08098b..6a6fcd3 100644 --- a/seats/mesh-module-assigner/fixtures/states.json +++ b/seats/mesh-module-assigner/fixtures/states.json @@ -63,7 +63,7 @@ "of": "state:assignments/.", "given": { "v": 1, - "node": "ace", + "node": "home-server", "placed": { "module": "plex", "branch": "beta", @@ -106,24 +106,32 @@ "changes": [ { "op": "place", - "node": "ace", + "node": "home-server", "module": "nats", "branch": "beta", "build": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "base": { - "ace": 3 + "home-server": 3 }, "state": "answering" } }, { - "name": "a candidate", + "name": "a candidate, with the modules it adds and what their wants would carry", "of": "state:candidates/.", "given": { "v": 1, - "proposal": "p-20261105t120000-aabbccdd" + "proposal": "p-20261105t120000-aabbccdd", + "added": { + "mesh-build-go": { + "version": "1.4.0", + "parts": { + "mesh-build-go:go-binary": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + } + } + } } }, { diff --git a/seats/mesh-module-assigner/seat.json b/seats/mesh-module-assigner/seat.json index 09eb93b..9529223 100644 --- a/seats/mesh-module-assigner/seat.json +++ b/seats/mesh-module-assigner/seat.json @@ -350,6 +350,13 @@ "assignments": { "$ref": "#/defs/Assignments", "description": "the node's assignments with the proposal laid over it; absent when the proposal takes its key away" + }, + "added": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/AddedModule" + }, + "description": "by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry" } }, "required": [ @@ -1061,6 +1068,23 @@ "branch", "nodes" ] + }, + "AddedModule": { + "type": "object", + "description": "what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316)", + "properties": { + "version": { + "type": "string", + "description": "the module's released version, for people; none for a build of another watched branch (design 47 G section 379)" + }, + "parts": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the digest of each of the module's parts, by `:` (design 47 G section 379)" + } + } } } } diff --git a/seats/node-engine/fixtures/events.json b/seats/node-engine/fixtures/events.json index 2e85efb..052157f 100644 --- a/seats/node-engine/fixtures/events.json +++ b/seats/node-engine/fixtures/events.json @@ -72,7 +72,7 @@ "subject": "mesh.seat.node-engine.event.composed.home-server", "given": { "v": 1, - "node": "ace", + "node": "home-server", "module": "nats", "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", @@ -85,7 +85,7 @@ "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, - "node": "ace", + "node": "home-server", "module": "nats", "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", @@ -98,7 +98,7 @@ "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, - "node": "ace", + "node": "home-server", "module": "nats", "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", @@ -112,7 +112,7 @@ "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, - "node": "ace", + "node": "home-server", "module": "nats", "fingerprint": "src2:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "manifest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", @@ -126,7 +126,7 @@ "subject": "mesh.seat.node-engine.event.running.home-server.nats", "given": { "v": 1, - "node": "ace", + "node": "home-server", "module": "nats", "stopped": true, "at": "2026-11-11T09:00:00Z" @@ -139,7 +139,7 @@ "given": { "owner": "node-engine", "step": "kept-build", - "node": "ace", + "node": "home-server", "on": "the kept build of postgres", "bound": "60m", "since": "2026-11-11T10:00:00Z", diff --git a/seats/node-engine/fixtures/verbs.json b/seats/node-engine/fixtures/verbs.json index 206e63c..94914a3 100644 --- a/seats/node-engine/fixtures/verbs.json +++ b/seats/node-engine/fixtures/verbs.json @@ -129,7 +129,7 @@ "name": "process-builds answers each process's build", "of": "verb:process-builds.answer", "given": { - "node": "ace", + "node": "home-server", "processes": [ { "module": "nats", @@ -152,7 +152,7 @@ "name": "process-builds answers an error", "of": "verb:process-builds.answer", "given": { - "node": "ace", + "node": "home-server", "processes": [], "error": "the service manager did not answer" } diff --git a/ts/seats/meshmoduleassigner/index.d.ts b/ts/seats/meshmoduleassigner/index.d.ts index 44beeef..fb8994b 100644 --- a/ts/seats/meshmoduleassigner/index.d.ts +++ b/ts/seats/meshmoduleassigner/index.d.ts @@ -86,6 +86,14 @@ export declare function seatHoldersBySeatNodeKey(seat: string, node: string): st /** The parts of a key of the form ".", or undefined for a key of another form. */ export declare function parseSeatHoldersBySeatNodeKey(_key: string): { seat: string; node: string } | undefined; +/** what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316) */ +export interface AddedModule { + /** the digest of each of the module's parts, by `:` (design 47 G section 379) */ + "parts"?: Record; + /** the module's released version, for people; none for a build of another watched branch (design 47 G section 379) */ + "version"?: string; +} + /** one node's assignments assembled */ export interface Assignments { "decided": NodeDecided; @@ -415,6 +423,8 @@ export type ProposalsByProposalValue = Proposal; /** is one value of the state candidates under the key .. */ export interface CandidatesByProposalNodeValue { + /** by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry */ + "added"?: Record; /** the node's assignments with the proposal laid over it; absent when the proposal takes its key away */ "assignments"?: Assignments; "proposal": string; From ef1fe33a9da50c7e1fff4fc8450befeba4b46b7b Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 23:27:49 +0100 Subject: [PATCH 62/62] T5: the enrolment client test names a role, laptop-login, not a node Builds: design 47 G (review round 2 finding T5) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- .../go/clients/meshnodeenrollerclient/enrolment_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go index 1628885..ef68cd7 100644 --- a/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go +++ b/identity-and-access/go/clients/meshnodeenrollerclient/enrolment_test.go @@ -35,7 +35,7 @@ func TestATokenLifeAndTheRedeemProofAreAsTheHolderMakesThem(t *testing.T) { // TestTheRedeemAnswerIsTheContractsWire: the client's answer reads into the contract's type with no field dropped, and // the contract's reads back as the client's wire. t.Run("TheRedeemAnswerIsTheContractsWire", func(t *testing.T) { - mine := RedeemAnswer{Node: "laptop", Login: "g14-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} + mine := RedeemAnswer{Node: "laptop", Login: "laptop-login", Account: "YQ==", Certificate: "pem", Signer: "dg==", Signature: "cw=="} wire, _ := json.Marshal(mine) var theirs seat.RedeemAnswer d := json.NewDecoder(bytes.NewReader(wire))