Let a trusted file that names its keys hold only those keys at the terminal (hq issue 586, ADR 0329 §5) #286
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: novox/mesh-controller#286
Reference in New Issue
Block a user
What
TrustedMergeablereturns nothing for a module whose mergeable files all name their keys (ADR 0326), andasksForreads a naming file'stakes-settingsas the keys it asks for. So for such a module only a trusted file's named keys are terminal keys (refused through thesettingsverb, proposed instead), and a key of a file marked"trusted": falseis set through the verb. A module whose files name no keys keeps the whole-layer rule of issue 340.Why
ADR 0329 §5: betterbird's
tags(intags.json,trusted: false) may be set through thesettingsverb, whileaccounts,identities,calendars,address-books,filtersandprefsstay the terminal's or the operator's warrant. Today any trusted mergeable file puts the module's whole layer at the terminal, because such a file took any key; withtakes-settingsa file takes exactly its named keys, and a key no file names is stray and refused where it is set, so the whole-layer rule is no longer needed for these modules (searxng, keycloak, betterbird).How it was tested
internal/catalogue:TestOnlyANamedKeyOfATrustedFileIsTheTerminals(betterbird's four files: terminal keys are accounts, address-books, calendars, filters, identities, prefs, not tags; a silent module keeps the whole layer). Fails without the change.cmd/mesh-controller(store test, added totestdata/store-tests):TestOnlyATrustedFilesNamedKeyIsRefusedThroughAVerb: tags set through the verb, accounts refused, the layer holds the tags alone. Fails without the change.go test ./internal/catalogue/ ./cmd/mesh-controller/against a throwaway postgres 17: ok; gofmt and vet clean.module checkon every catalogue manifest with this binary: 127 checked, no problem.Part of issue 586 (with novox/mesh-catalog fix/586-betterbird-owns-its-configuration).
Delivery
novox/mesh-controller@3275a16bebbb— delivered since 2026-10-13T03:46:32ZDelivery plan — builds build-agent, mesh-controller → ace, g14, novox, shanks; no bus step
Machines
Transitions
The commit's note under
refs/notes/mesh-plankeeps every transition:git log --notes=mesh-plan.Merge check at
3379ab3bJudged: head
3379ab3b61acmerged into trunk454a3db69a1e; read beside it: mesh-catalog39e7a06e6293, mesh-controller-main454a3db69a1e, mesh-host7a41e120635b, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: build-agent, mesh-controller)mesh/repo-check: PASS — its merge-check.sh passedDelivery plan — builds build-agent, mesh-controller → ace, g14, novox, shanks; no bus step
Run by the build seat on shanks as
build-1791849840531899425(builds --log build-1791849840531899425).Out of date when it landed: out of date: judged against trunk
454a3db69a, the trunk is now 4473bc7d7315; judged again on a recheck or when it is mergedVerdict: request changes at
3379ab3b61Blocking
4473bc7d73), and it appended TestPlanAndNodeListAnOptionalRequirementLeftUnbound to the end of testdata/store-tests, the same place this change appends TestOnlyATrustedFilesNamedKeyIsRefusedThroughAVerb. A merge of this head into main stops with a content conflict in testdata/store-tests. The fix is a rebase that keeps both lines. I resolved it that way locally: go vet is clean and the two new tests, the issue 340 test and 281's store test pass on the result. The code itself needs no change; this is the only reason for this verdict, and a rebased head whose diff to main is these same four files is one I would approve.Findings that do not block
The code does what ADR 0329 §5 and ADR 0326 decide and nothing broader in the files. TrustedMergeable now answers nothing for a module whose mergeable files all carry takes-settings (namesItsKeys), and asksFor gives such a file exactly its named keys plus any ${setting:} its content asks for. A file that names no keys keeps the whole-layer rule of issue 340, and a mixed module cannot reach this path, because takenSettingsProblems refuses it where it is checked and where it is composed. A key no file names is stray and refused where it is set, as before.
I composed every module of mesh-catalog and mesh-media-catalog main through this head's catalogue package. Only betterbird, keycloak and searxng name their keys. Their terminal keys are now: betterbird places, accesses, accounts, prefs (accounts is its only mergeable file, trusted; prefs comes from user.js's placeholder); keycloak places, accesses, url, user, realm, issuer and its served authorization-path, token-path, userinfo-path (its runtime-config names url, user, realm, issuer and says nothing on trust, so it counts as trusted); searxng places, accesses and all ten keys its settings file names. Every other module with a mergeable file (39 of them) names no keys and keeps its whole layer at the terminal, unchanged. No ${setting:} placeholder anywhere in those three manifests falls outside the terminal keys. So no key that lands in a trusted file of any catalogue module becomes settable through the settings verb.
What does leave the terminal for keycloak and searxng is every key that was protected only by the whole-layer rule: the mesh words (ports, expose, reach, endpoints) and the keys their contributions declare, which a setting overrides (overridden in settings.go). For keycloak that is name on its postgres-database contribution and label and endpoint on its route; for searxng label and endpoint on its route. Those values reach a provider's received file, not keycloak's or searxng's own. This is the rule every module without a trusted mergeable file already lives under (model-usage, mesh-knowledge, n8n and umami contribute postgres-database the same way), so it is issue 339's scope and not a defect of this change. I think a contribution's key that names another module's resource, such as a database name, deserves its own issue, because through a verb it could point keycloak's login at another module's database.
Rollback is safe. The change stores nothing new and has no migration. On a rollback to main, a value set through the verb (betterbird's tags once it has a file) stays in the layer and is read and composed as before, since takes-settings filtering is already on main; main would only refuse the next verb change to that module's layer, as it does today.
Tests. Both new tests pass at this head and fail with terminal_keys.go reverted to main: the unit test because TrustedMergeable answers [accounts configuration prefs], the store test because the tags change is refused under issue 340. go vet ./... is clean and gofmt lists nothing. go test -race -count=1 ./internal/catalogue/ ./cmd/mesh-controller/ passes against a throwaway postgres 17 (catalogue 10 s, mesh-controller 315 s).
Remark: the verb judges a layer change against the module's current definition in the catalogue table, while a node that has not yet received a new build composes with the build it has. That was already so before this change; it matters here only for a module whose stored build is silent and whose new definition names its keys, during its walk.
Statuses at this head, from the forge: mesh/merge-gate pending, "out of date: judged against trunk
454a3db69a, the trunk is now 4473bc7d7315; judged again on a recheck or when it is merged"; mesh/repo-check pending with the same words; mesh/delivery pending, "checking". The forge says it is not mergeable while both required checks are pending.3379ab3b61to4c965e3cf6Verdict: approve at
4c965e3cf6The rebase adds nothing beyond itself. git range-diff 454a3db..3379ab3b against 4473bc7..4c965e3 shows one commit, with the same message and the same code. The only difference is in testdata/store-tests, which now carries both #281's TestPlanAndNodeListAnOptionalRequirementLeftUnbound and this change's TestOnlyATrustedFilesNamedKeyIsRefusedThroughAVerb. The diff to main is the same four files as before (79 lines added, 1 removed). This settles the only blocking finding of my review of
3379ab3b, and its other findings stand unchanged.go build ./... and go vet ./... are clean, and go test -race -count=1 ./internal/catalogue/ passes in 13.8 s.
Statuses at this head, from the forge: mesh/merge-gate is pending with "building on ace since 02:21", mesh/repo-check is missing, and mesh/delivery is pending with "checking". The forge says the pull request is not mergeable until both required checks are a success, so it must not be merged before then.
Merge check at
4c965e3cJudged: head
4c965e3cf6d5merged into trunk4473bc7d7315; read beside it: mesh-catalog39e7a06e6293, mesh-controller-main4473bc7d7315, mesh-host7a41e120635b, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: build-agent, mesh-controller)mesh/repo-check: FAIL — its merge-check.sh failed: --- FAIL: TestBorrowedWordsAreLogged (0.01s)Delivery plan — builds build-agent, mesh-controller → ace, g14, novox, shanks; no bus step
Run by the build seat on ace as
build-1791850897302374619(builds --log build-1791850897302374619).Merge check at
4c965e3cJudged: head
4c965e3cf6d5merged into trunk584ee991961cmesh/merge-gate: FAIL — head4c965e3cf6does not merge cleanly into trunk584ee99196: in conflict testdata/store-tests (modules: build-agent, mesh-controller)mesh/repo-check: FAIL — head4c965e3cf6does not merge cleanly into trunk584ee99196: in conflict testdata/store-testsDelivery plan — builds build-agent, mesh-controller → ace, g14, novox, shanks; no bus step
Run by the build seat on ace as
build-1791861685670977695(builds --log build-1791861685670977695).4c965e3cf6to3275a16bebMerge check at
3275a16bJudged: head
3275a16bebbbmerged into trunk584ee991961c; read beside it: mesh-catalogf88e3452f8b8, mesh-controller-main584ee991961c, mesh-host7a41e120635b, mesh-tools954e1a53eef9mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: build-agent, mesh-controller)mesh/repo-check: PASS — its merge-check.sh passedDelivery plan — builds build-agent, mesh-controller → ace, g14, novox, shanks; no bus step
Run by the build seat on g14 as
build-1791861829243255338(builds --log build-1791861829243255338).Verdict: approve at
3275a16bebgit range-diff 4473bc7..4c965e3c 584ee991..3275a16bshows the rebase changes only the testdata/store-tests hunk — it keeps both TestReplay340 (picked up from main) and TestOnlyATrustedFilesNamedKeyIsRefusedThroughAVerb (this PR's own line), and the diff of the actual code (internal/catalogue/terminal_keys.go and the two test files) is byte-identical to the reviewed head.go vet ./internal/catalogue/is clean andgo test -race ./internal/catalogue/is ok (18.3s); gitea's statuses on3275a16bread mesh/merge-gate success ("head3275a16bebmerged into trunk584ee99196— pass: builds build-agent, mesh-controller → ace, g14, novox, shanks"), mesh/repo-check success ("its merge-check.sh passed"), and mesh/delivery success ("ready: it delivers once merged").