docs: record ADR rejecting a structural-key registry#39
Merged
Conversation
Architecture-review candidate 3 proposed folding the 20 structural keys into a uniform registry. The structural keys span six distinct emit shapes and share no interface, so such a registry is a false seam that would scatter cohesive logic (depends_on/graph, dns/pod, secrets/stores) behind Any-typed callbacks. STRUCTURAL_KEYS holds no behavior -- the only duplication is the key-name list, which the snapshot/disjoint tests already guard. The narrow name single-sourcing was also weighed and declined for now; the ADR names it as the designated move should a revisit trigger fire.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Records the outcome of architecture-review candidate 3 ("close the split-brain key registry") as an ADR. No code change.
Conclusion: the split is essential. The 20 structural keys span six distinct emit shapes (slot-occupiers, project_dir flag-producers, healthcheck, graph keys, pod-level aggregated, document-scoped) and share no interface — so a uniform structural registry would be a false seam that scatters cohesive logic (
depends_on↔graph,dns↔pod,secrets↔stores,deploy↔resources) behindAny-typed callbacks.STRUCTURAL_KEYSholds no behavior (deletion test); the only duplication is the key-name list, already guarded by the snapshot/disjoint tests.The narrow name single-sourcing (deriving the gate's accept-list from per-module declared key sets) was also weighed and declined for now — it distributes six small sets + import edges to remove a minor, test-guarded duplication. The ADR names it as the designated revisit path should a trigger fire (a third reader of the key set, or a cluster of new keys sharing one new shape), so future reviews reach for single-sourcing, never the registry.
planning/decisions/2026-07-12-reject-structural-key-registry.md