A-385 runner-reads-a-carried-modules-bound-ledger: the tool runner carrying a module with a bound ledger reads its state, indexes, history and snapshots, and writes its state

Builds: design 47 G A-385 (G-22-lead-answers-2.md), their bindings

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-14 01:26:46 +01:00
parent 66ae3cd918
commit 14901e8723
3 changed files with 89 additions and 0 deletions
+52
View File
@@ -5469,3 +5469,55 @@ func TestAHeldRunnerIsWrittenAsTheUnionOfTheListInForceAndWhatIsComposed(t *test
}
}
}
// Design 47 G A-385 (their bindings): a runner carrying a module with a bound ledger reads that ledger's state, its indexes, its history
// and its snapshots on its own connection, and writes its state; it publishes on no history (only the ledger account does, ADR 0597 §9).
func TestARunnerCarryingABoundLedgerReadsItsStateHistoryAndSnapshots(t *testing.T) {
const runner = `{"module":"node-tools","version":"1","tool-runner":true,"own-secrets":{"broker":"/var/lib/nt/broker"}}`
const carried = `{"module":"mod-c","version":"1","tools":["t"],"requires":[{"name":"records","storage":"ledger","template":"ledger",` +
`"types":[{"name":"decision","schema":{},"operations":[{"name":"propose","effect":"set-fields"}]}]}]}`
b := fixture()
b.manifestOf("node-tools", runner)
b.manifestOf("mod-c", carried)
b.assign("a", "node-tools")
b.assign("a", "mod-c")
busKey, err := seal.GenerateKeyPair()
if err != nil {
t.Fatal(err)
}
b.put(grants.ReadHave, "a.nats", nodeengine.HaveByNodeModuleValue{V: keys.Version, Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK,
UserList: &nodeengine.UserListWritten{Source: grantsstate.GrantsUserListSource, Revision: 8, Wanted: "sha256:aa", Digest: "sha256:aa", Users: 5,
Key: busKey.PublicKey, Follows: grantsstate.FollowGrants}})
for _, u := range shadowOf(t, b) {
b.put(grants.ReadAccounts, u.User, map[string]any{"user": u.User, "hash": "$2a$10$x", "generation": 1, "fingerprint": "sha256:1"})
}
p := partOn(b)
p.Bus = grants.BusAddress{URL: "nats://a.mesh:4222", Fingerprint: "ab"}
p.Objects = &fakeObjects{}
binding := membership.BusBinding{Local: "records", Storage: "ledger", Template: "ledger", Stream: "mod-c_records", History: "mod-c_records",
Subject: "mesh.ledger.mod-c.records.history", State: "mod-c_records_state", Snapshot: "mesh.ledger.mod-c.records.snapshot"}
p.Compose() // the pass that learns the bus module is the broker
body, _ := json.Marshal(grants.BrokerEvent{V: 1, Module: "mod-c", Local: "records", Storage: "ledger", Template: "ledger", Binding: binding})
if _, err := p.HearBroker("mesh.seat.mesh-broker.event.created", body, p.Brokers()); err != nil {
t.Fatal(err)
}
p.Compose()
sealed, _, _ := p.Sealed()
var got grants.User
if err := json.Unmarshal(b.own[grants.StateUserList][grants.SealedUserKey(sealed.Digest, "a.node-tools")], &got); err != nil {
t.Fatal(err)
}
for _, want := range []string{
"$JS.API.STREAM.INFO.KV_mod-c_records_state", "$JS.API.DIRECT.GET.KV_mod-c_records_state.>", "$KV.mod-c_records_state.>",
"$JS.API.CONSUMER.CREATE.KV_mod-c_records_state.>", "$JS.API.DIRECT.GET.mod-c_records.>", "$JS.API.CONSUMER.CREATE.mod-c_records.>",
"$JS.API.DIRECT.GET.mod-c_records_snapshot.>"} {
if !slices.Contains(got.Publish, want) {
t.Errorf("the runner of a lacks %s", want)
}
}
for _, no := range []string{"mesh.ledger.mod-c.records.history.>", "mesh.ledger.mod-c.records.snapshot.>"} {
if slices.Contains(got.Publish, no) {
t.Errorf("the runner may publish on the ledger's %s", no)
}
}
}
@@ -231,6 +231,8 @@ func withoutActing(served []string) []string {
// `state` is; the bus names of its object stores, granted as an old `objects` is; and what its streams (events, work
// queue, log, bare) are published and read on. A ledger has its own account (ledger.go) and is not among them.
type boundGrants struct {
// Ledgers are the runner's grants on a bound ledger (ledgerReaderGrants).
Ledgers []string
States, Objects, Streams []string
}
@@ -269,6 +271,8 @@ func boundOn(module, node string, bindings []membership.BusBinding) boundGrants
if b.ObjectStore == base {
g.Objects = append(g.Objects, base)
}
case catalogue.StorageLedger:
g.Ledgers = append(g.Ledgers, ledgerReaderGrants(base, b)...)
case catalogue.StorageStream:
if b.Stream != base || b.Subject != "mesh.bus."+module+"."+b.Local {
continue
@@ -284,3 +288,35 @@ func boundOn(module, node string, bindings []membership.BusBinding) boundGrants
}
return g
}
// ledgerReaderGrants are what the tool runner carrying a module with a bound ledger is granted on it, for the runner reads the ledger
// on its own connection (design 47 G A-385): its state bucket and each index bucket read and written (the instances' latest state), its
// history stream and its snapshots' stream read. Never a publish on a history or a snapshot subject: only the module's ledger account
// does (ADR 0597 §9). Each name is the one the module's ledger derives; a binding naming another is granted nothing.
func ledgerReaderGrants(base string, b membership.BusBinding) []string {
var out []string
kv := func(bucket string) {
stream := "KV_" + bucket
out = append(out, "$KV."+bucket+".>", "$JS.API.STREAM.INFO."+stream, "$JS.API.DIRECT.GET."+stream+".>",
"$JS.API.CONSUMER.CREATE."+stream+".>", "$JS.API.CONSUMER.DELETE."+stream+".>", "$JS.FC."+stream+".>")
}
read := func(stream string) {
out = append(out, "$JS.API.STREAM.INFO."+stream, "$JS.API.STREAM.MSG.GET."+stream, "$JS.API.DIRECT.GET."+stream+".>",
"$JS.API.CONSUMER.CREATE."+stream+".>", "$JS.API.CONSUMER.DELETE."+stream+".>", "$JS.FC."+stream+".>")
}
if b.State == base+"_state" {
kv(b.State)
}
for name, bucket := range b.Indexes {
if safeSubject.MatchString(name) && bucket == base+"_index-"+name {
kv(bucket)
}
}
if b.History == base {
read(base)
}
if b.Snapshot != "" {
read(base + "_snapshot")
}
return out
}
@@ -1281,6 +1281,7 @@ func permissionsFor(p Principal) (Permissions, error) {
PerMachine: perMachineNames(d.State), ReadOnly: readOnlyNames(d.State), Reads: d.Reads, KeyedReads: d.KeyedReads, Nodes: p.Nodes})...)
pub = append(pub, objectGrants(append(objectNames(d.Objects), bound.Objects...), d.ReadsObjects)...)
pub = append(pub, bound.Streams...)
pub = append(pub, bound.Ledgers...)
// A bundle reads every node's compositions on the runtime's own connection (ADR 0593 §6), which hears a node's
// bucket made later by any stream's creation.
if slices.Contains(d.Reads, ComposedRead) && !slices.Contains(sub, familyCreatedAdvisory) {