docs: record ADR keeping graph queries as validate-on-read#40
Merged
Conversation
Architecture-review candidate 4 flagged the graph query-as-validator smell (hostnames called at the gate for its raise then recomputed at emit; depends_on re-normalized at several sites). The recompute is inherent: the gate is target-agnostic while emit is target-scoped, so no shared graph can span them; independent readers are the accepted price of parse-don't-validate; and splitting the queries' raise from their normalization would regress the validate-owns-emit-shapes robustness. Declined with revisit triggers.
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
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 4 ("split the query from the gate in the graph", the Speculative one) as an ADR. No code change.
Conclusion: the query-as-validator pattern and the gate/emit recompute are the deliberate consequence of accepted decisions, not a defect:
validate(compose)is target-agnostic;_planis target-scoped (startup_order(services, target)). The gate can't compute the dependency closure without a target — cycle/unknown-dep detection is inherently target-scoped.validateand emit are independent readers with no shared computed model. Threading a graph reintroduces the coupling that ADR declined.emit_script(malformed_dict)would crash instead of raisingUnsupportedComposeError.The only ADR-neutral change (deduping
depends_onwithin_plan) is marginal and partial (startup_ordernormalizes independently anyway). Revisit triggers recorded: the gate becoming target-aware, or the graph walk profiling as a real hotspot.planning/decisions/2026-07-12-keep-graph-query-as-validator.md