A-384 runner-hears-new-events: every tool runner account carries the ordered consumer of EVENTS and each kept seat stream, kept or held ones included

Builds: design 47 G A-384 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-14 00:44:32 +01:00
parent 968e1b7493
commit c3fd353abe
6 changed files with 99 additions and 3 deletions
@@ -87,6 +87,14 @@ func theGrantsPartCreatesOnlyDeclaredStreams(t *testing.T) {
{"novox.node-tools", "$KV.mesh-host_acts.novox.act.hand-over-1", false},
// The runner never carries the engine (issue 774): its health report is the node's own key alone.
{"novox.node-tools", "$KV.mesh-host_health.novox", false},
// A-384: the runner hears a new event of a seat through an ordered consumer of its own on the stream that carries it.
{"novox.node-tools", "$JS.API.CONSUMER.CREATE.EVENTS.abc", true},
{"novox.node-tools", "$JS.API.CONSUMER.CREATE.EVENTS.abc.mesh.seat.mesh-conditions.event.findings-asked", true},
{"novox.node-tools", "$JS.API.CONSUMER.INFO.EVENTS.abc", true},
{"novox.node-tools", "$JS.API.CONSUMER.DELETE.EVENTS.abc", true},
{"novox.node-tools", "$JS.FC.EVENTS.abc.def.ghi", true},
{"novox.node-tools", "$JS.API.CONSUMER.CREATE.ASSIGNMENTS.abc", false},
{"mesh-delivery-builder", "$JS.API.CONSUMER.CREATE.EVENTS.abc", false},
{"novox.node-tools", "$KV.mesh-host_acts.novox.ask.x", false},
{"node.novox", "$KV.mesh-host_health.novox", true},
{"node.novox", "$KV.mesh-host_health.ace", false},
@@ -203,6 +203,9 @@ type Principal struct {
// seat's verbs on this node — derived from the same declarations the modules' own principals
// are, so the runtime can serve nothing a module could not have served for itself.
Carries []Declared
// NewEventStreams are the streams whose events the runner's bundles may hear from the next message on, each through an ordered
// consumer of its own (mesh-tools node-tools SubscribeNew; design 47 G A-384): the shared events stream and each kept seat stream.
NewEventStreams []string
// Withholds says this node's tool runner does not honour the approval mark (design 46 approval mark §6), for a
// KindNodeTools principal: every marked subject of what it carries is denied it (MarksWithheld).
Withholds bool
@@ -698,6 +701,9 @@ func PermissionsFor(p Principal) (Permissions, error) {
sub = append(sub, answered...)
}
perms.Publish, perms.Subscribe = append(perms.Publish, pub...), append(perms.Subscribe, sub...)
if p.Kind == KindNodeTools {
perms.Publish = append(perms.Publish, NewEventGrants(p.NewEventStreams)...)
}
// Every account of a module, its processes, its node and the tool runner (not a ledger's or an enrolling node's, which publish on a few subjects alone) asks the names of the bus's streams: a client finds the stream that carries a subject by it (the tool runner's
// subscription to a seat's event, the grants part's creation of a kept stream; design 47 G A-381, A-382).
if slices.Contains([]Kind{KindModule, KindNodeTools, KindNode, KindProcess}, p.Kind) && !slices.Contains(perms.Publish, StreamNamesSubject) {
@@ -706,6 +712,38 @@ func PermissionsFor(p Principal) (Permissions, error) {
return perms, nil
}
// NewEventGrants are what hearing a new event on each stream through an ordered consumer needs, in the forms the client library
// sends: the create of a consumer the client names itself (with its filter or without, as it has one filter subject or several), its
// info and its delete, the next-message fetch, and the flow control (design 47 G A-384). The whole of each stream's subjects: inside the mesh
// every module is trusted (principle 6).
func NewEventGrants(streams []string) []string {
var out []string
for _, s := range streams {
if !safeSubject.MatchString(s) {
continue
}
out = append(out, "$JS.API.CONSUMER.CREATE."+s+".*", "$JS.API.CONSUMER.CREATE."+s+".*.>", "$JS.API.CONSUMER.INFO."+s+".*",
"$JS.API.CONSUMER.DELETE."+s+".*", "$JS.API.CONSUMER.MSG.NEXT."+s+".*", "$JS.FC."+s+".>")
}
return out
}
// RunnerNewEventGrants are, by the runner's user, what NewEventGrants gives its account: for a pass that keeps a runner's account
// from the list in force and would not compose them (A-383's kind of copy).
func RunnerNewEventGrants(r Records) map[string][]string {
users, err := Users(r)
if err != nil {
return nil
}
out := map[string][]string{}
for _, u := range users {
if u.Kind == KindNodeTools {
out[u.Username()] = NewEventGrants(u.NewEventStreams)
}
}
return out
}
// StreamNamesSubject is the request for the names of the bus's streams, granted to every account.
const StreamNamesSubject = "$JS.API.STREAM.NAMES"
@@ -386,7 +386,8 @@ func Users(r Records) ([]Principal, error) {
// approval mark §6).
reading, read := r.Readings[node]
out = append(out, Principal{Kind: KindNodeTools, Node: node, Module: runner, Carries: carried,
Withholds: Withholds(reading, read, r.Running[node+"."+runner])})
NewEventStreams: newEventStreams(r.Kept),
Withholds: Withholds(reading, read, r.Running[node+"."+runner])})
}
}
// A node enrols through the seat mesh-enrolment alone (ADR 0587 §6, ADR 0590): while no holder serves redeem, an
@@ -711,3 +712,14 @@ func keptOfSeat(kept []KeptEvent, seat string) []KeptEvent {
}
return out
}
// newEventStreams are the streams a runner's bundles hear new events on: the shared events stream and each kept seat stream.
func newEventStreams(kept []KeptEvent) []string {
out := []string{EventsStream}
for _, k := range kept {
if !slices.Contains(out, k.Stream) {
out = append(out, k.Stream)
}
}
return out
}
@@ -0,0 +1,26 @@
package grants
import (
"slices"
"testing"
"mesh-grants/internal/buscompose"
)
// Design 47 G A-383, A-384: a runner's account kept from the list in force gains the rights of hearing new events and the streams'
// names, and loses nothing; a ledger's account gains neither.
func TestAKeptRunnerGainsWhatEveryRunnerCarries(t *testing.T) {
own := map[string][]string{"novox.node-tools": buscompose.NewEventGrants([]string{"EVENTS"})}
kept := map[string]User{"novox.node-tools": {User: "novox.node-tools", Publish: []string{"a"}}, "ledger.novox.m": {User: "ledger.novox.m", Publish: []string{"b"}}}
users, kept := withEveryAccountsRights([]User{{User: "novox.node-tools", Publish: []string{"a"}}}, kept, own)
for _, u := range []User{users[0], kept["novox.node-tools"]} {
for _, want := range []string{"a", buscompose.StreamNamesSubject, "$JS.API.CONSUMER.CREATE.EVENTS.*", "$JS.FC.EVENTS.>"} {
if !slices.Contains(u.Publish, want) {
t.Errorf("the runner lacks %s: %v", want, u.Publish)
}
}
}
if got := kept["ledger.novox.m"].Publish; !slices.Equal(got, []string{"b"}) {
t.Errorf("a ledger's account = %v", got)
}
}
+1 -1
View File
@@ -401,7 +401,7 @@ func (p *Part) Compose() Result {
}
// A right every account carries is written to every account of the list, one kept or held from the list in force included
// (design 47 G A-383); the pass only adds.
users, kept = withEveryAccountsRights(users, kept)
users, kept = withEveryAccountsRights(users, kept, buscompose.RunnerNewEventGrants(listRecs))
users = WithHashes(users, in.Hashes)
st.Digest, st.Users = Digest(users), len(users)
st.Compare = Compare(users, loaded, Placed(in)).Excusing(ExcusedBy(MultiHeld(listRecs)))
+13 -1
View File
@@ -141,8 +141,9 @@ func (p *Part) sayPrincipalsRefused(refused map[string]string, kept map[string]U
// withEveryAccountsRights gives each account a right every account of its kind carries (buscompose.StreamNamesSubject, design 47 G
// A-382) that it lacks, in users and in kept: a user kept from the list in force or held is copied whole, so it would never gain it. An
// account of a ledger, an enrolling node, a person or a provisioner publishes on a few subjects alone and gets none. It only adds.
func withEveryAccountsRights(users []User, kept map[string]User) ([]User, map[string]User) {
func withEveryAccountsRights(users []User, kept map[string]User, own map[string][]string) ([]User, map[string]User) {
add := func(u User) User {
u.Publish = withMissing(u.Publish, own[u.User])
for _, alone := range []string{"ledger.", "enrol.", "person.", "provisioner."} {
if strings.HasPrefix(u.User, alone) {
return u
@@ -166,3 +167,14 @@ func withEveryAccountsRights(users []User, kept map[string]User) ([]User, map[st
}
return out, withKept
}
// withMissing is list with each of rights it lacks, never taking one away.
func withMissing(list, rights []string) []string {
out := list
for _, r := range rights {
if !slices.Contains(out, r) {
out = append(slices.Clone(out), r)
}
}
return out
}