Skip to content

docs: record ADR keeping graph queries as validate-on-read#40

Merged
lesnik512 merged 1 commit into
mainfrom
docs/keep-graph-query-as-validator
Jul 12, 2026
Merged

docs: record ADR keeping graph queries as validate-on-read#40
lesnik512 merged 1 commit into
mainfrom
docs/keep-graph-query-as-validator

Conversation

@lesnik512

Copy link
Copy Markdown
Member

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:

  • The gate and emit operate at different scopes, so a shared "compute the graph once" artifact cannot span them. validate(compose) is target-agnostic; _plan is 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.
  • The independent recompute is the accepted price of parse-don't-validate (2026-07-10) — validate and emit are independent readers with no shared computed model. Threading a graph reintroduces the coupling that ADR declined.
  • Query-as-validator is the "validate owns emit shapes" pattern (2026-07-10.01). Splitting the raise out of the queries would leave emit's reader non-validating — emit_script(malformed_dict) would crash instead of raising UnsupportedComposeError.

The only ADR-neutral change (deduping depends_on within _plan) is marginal and partial (startup_order normalizes 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

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.
@lesnik512 lesnik512 merged commit 0b23d03 into main Jul 12, 2026
6 checks passed
@lesnik512 lesnik512 deleted the docs/keep-graph-query-as-validator branch July 12, 2026 19:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant