GR13 purge: the named asks go at the first revision that leaves them, or by grants_named_purge

While no entry of the revision invokes a queue of a build seat (seat:<seat>.accept.<queue>,
read by catalogue.QueueInvoke), the part composes no named worker, and at the first such
pass it purges accept.<queue>.* of each build seat's stream and deletes the named workers,
saying each in its journal; a failed read of the catalog half purges nothing. Its account
alone is granted the stream's purge and the named workers' delete. The hand tool
grants_named_purge records its hand act first, then asks the process to do it.

Builds: design 47 G §544, §600, §601, A-231

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-12 06:22:54 +01:00
parent 5a7747f2bf
commit ff2f90ec18
14 changed files with 404 additions and 10 deletions
@@ -111,3 +111,29 @@ func TestAVerbIsGrantedToItsEffectiveCallersAlone(t *testing.T) {
}
}
}
// Design 47 G §544: the grants part's account alone is granted the purge of a build seat's stream and the delete of its
// named workers, for every queue of a build seat a composed user holds.
func TestTheGrantsPartAlonePurgesTheNamedAsks(t *testing.T) {
held := Seat{Name: "node-build-go", Scope: "node", Accepts: []string{"check"}, PulledByKind: true}
users, err := Users(Records{Nodes: []string{"one"}, Assigned: map[string][]Declared{"one": {
{Module: GrantsModule}, {Module: "go-module", Holds: []Seat{held}}}}})
if err != nil {
t.Fatal(err)
}
for _, u := range users {
perms, err := PermissionsFor(u)
if err != nil {
t.Fatal(err)
}
for _, subject := range []string{"$JS.API.STREAM.PURGE.SEAT_NODE_BUILD_GO",
"$JS.API.CONSUMER.DELETE.SEAT_NODE_BUILD_GO.SEAT_NODE_BUILD_GO_CHECK_named_worker"} {
if got, want := MayPublish(perms, subject), u.Module == GrantsModule && u.Kind == KindModule; got != want {
t.Errorf("%s may publish %s: %v, want %v", u.Username(), subject, got, want)
}
}
if u.Module == GrantsModule && MayPublish(perms, "$JS.API.CONSUMER.DELETE.SEAT_NODE_BUILD_GO.SEAT_NODE_BUILD_GO_CHECK_worker") {
t.Errorf("the grants part may delete main's worker")
}
}
}
@@ -113,6 +113,9 @@ type Seat struct {
// subject only where that list names it (A-179), so the bus holds every other caller out. Empty where the seat list is
// unread, and then no verb of the seat is granted to its users.
VerbCallers map[string][]string
// NoNamedAsks says no entry of the revision invokes a queue of a build seat (`seat:<seat>.accept.<queue>`), so its queues
// have no named worker: the grants part purges their named asks and deletes those workers (design 47 G §544, A-231).
NoNamedAsks bool
// HeldByTheEngine says every node's engine holds the seat on its own account (catalogue.Seat.HeldByTheEngine, novox/hq
// ADR 0563 §1): each of its events names the engine's machine as its last token (machineEvent).
HeldByTheEngine bool
@@ -152,6 +155,9 @@ type Principal struct {
// ruling, registry milestone 13:0x): `mesh.seat.mesh-broker.event.<event>` for each event the seat's definition
// names, as a holder's own account would be granted them; set on the keeper alone.
SaysSeatEvents []string
// PurgesNamed are the named asks of every queue of a build seat a composed user holds, for the grants part alone: the
// purge of their subjects on the seat's stream and the delete of their named workers (design 47 G §544).
PurgesNamed []NamedQueue
// Process is the process resource's id, for a KindProcess principal alone (novox/hq ADR 0436 §2):
// Username and inbox are <node>.<module>.<process id>.
Process string
@@ -930,6 +936,8 @@ func permissionsFor(p Principal) (Permissions, error) {
pub = append(pub, CreateStreamGrants(p.CreatesStreams)...)
// And creating each durable consumer an account needs, by its stream and name (ADR 0561 §6).
pub = append(pub, CreateConsumerGrants(p.CreatesConsumers)...)
// And the purge of the build seats' named asks and the delete of their named workers (design 47 G §544).
pub = append(pub, NamedPurgeGrants(p.PurgesNamed)...)
// And its own object bucket, where it writes the user list sealed to the bus node (ADR 0547 clause 7).
pub = append(pub, GrantsUserListWrites()...)
}
@@ -2,6 +2,8 @@ package buscompose
import (
"fmt"
"maps"
"slices"
"sort"
)
@@ -41,6 +43,61 @@ func NamedWorkerName(seat, queue string) string {
return "SEAT_" + upperSnake(seat) + "_" + upperSnake(queue) + "_named_worker"
}
// NamedAsksSubject is the subject of every named ask of a build seat's queue, `accept.<queue>.*` (design 47 G §544, §600).
func NamedAsksSubject(seat, queue string) string {
return "mesh.seat." + seat + ".accept." + queue + ".*"
}
// NamedQueue is one queue of a build seat: the stream its asks are on, the subject of its named asks and its named worker.
type NamedQueue struct {
Seat, Queue, Stream, Subject, Worker string
}
// NamedQueuesOf are the queues of every pulled-by-kind seat a composed user holds, once each, sorted: what the grants part
// purges at the first revision in which no entry invokes a queue of a build seat (design 47 G §544). Pure.
func NamedQueuesOf(users []Principal) []NamedQueue {
seen := map[string]NamedQueue{}
add := func(holds []Seat) {
for _, s := range holds {
if !s.PulledByKind || !safeSubject.MatchString(s.Name) {
continue
}
for _, q := range s.Accepts {
if safeSubject.MatchString(q) {
seen[s.Name+"."+q] = NamedQueue{Seat: s.Name, Queue: q, Stream: seatStreamName(s.Name),
Subject: NamedAsksSubject(s.Name, q), Worker: NamedWorkerName(s.Name, q)}
}
}
}
}
for _, p := range users {
switch p.Kind {
case KindModule:
add(p.Holds)
case KindNodeTools:
for _, d := range p.Carries {
add(d.Holds)
}
}
}
out := make([]NamedQueue, 0, len(seen))
for _, k := range slices.Sorted(maps.Keys(seen)) {
out = append(out, seen[k])
}
return out
}
// NamedPurgeGrants are the subjects the purge of each queue's named asks and the delete of its named worker need: the stream's
// purge (whose subject filter is the request's, so the grant is the stream's) and the one consumer's delete and info.
func NamedPurgeGrants(queues []NamedQueue) []string {
var out []string
for _, q := range queues {
out = append(out, "$JS.API.STREAM.PURGE."+q.Stream, "$JS.API.CONSUMER.DELETE."+q.Stream+"."+q.Worker,
"$JS.API.CONSUMER.INFO."+q.Stream+"."+q.Worker)
}
return unique(out)
}
// MainAskers are the seats that may publish a build seat's ask on main's subject `accept.<queue>`, which names no asker: the
// checker and the builder, until main's subject goes (design 47 G §543, §600, A-184).
var MainAskers = []string{"mesh-delivery-checker", "mesh-builds"}
@@ -96,9 +153,12 @@ func SeatTrafficOf(module string, holds, uses, watches []Seat) SeatTraffic {
for _, a := range s.Accepts {
t.Workers = append(t.Workers, Worker{Stream: seatStreamName(s.Name), Consumer: WorkerName(s.Name, a),
Filter: "mesh.seat." + s.Name + ".accept." + a})
// Its named asks have a worker of their own (§544); a holder of G pulls it, one before G knows only main's.
t.Workers = append(t.Workers, Worker{Stream: seatStreamName(s.Name), Consumer: NamedWorkerName(s.Name, a),
Filter: "mesh.seat." + s.Name + ".accept." + a + ".*"})
// Its named asks have a worker of their own (§544); a holder of G pulls it, one before G knows only main's. None
// while no entry invokes a queue of a build seat, whose named asks the grants part purges.
if !s.NoNamedAsks {
t.Workers = append(t.Workers, Worker{Stream: seatStreamName(s.Name), Consumer: NamedWorkerName(s.Name, a),
Filter: NamedAsksSubject(s.Name, a)})
}
}
} else if len(s.Accepts) > 0 {
stream := seatStreamName(s.Name)
@@ -378,6 +378,7 @@ func Users(r Records) ([]Principal, error) {
// The grants part creates the durable consumers the accounts need (novox/hq ADR 0561 §6), by stream and name.
if grants >= 0 {
out[grants].CreatesConsumers = AccountConsumers(out)
out[grants].PurgesNamed = NamedQueuesOf(out)
}
// Refused here rather than discovered by the server. Two users with one name is a file the