--- id: ATLAS-WP-0004 type: workplan title: "Effective-config explain and graph" domain: infotech repo: config-atlas status: finished owner: codex topic_slug: custodian created: "2026-06-26" updated: "2026-06-27" state_hub_workstream_id: "fbfdbf2b-ca6b-450e-a654-a61c5939f068" --- # Effective-config explain and graph Turn the registry into the **read-first control-plane MVP**: given a key, show its layer path, what overrides what, its owner, its consumers, and its blast radius — **statically, from source links, without reading any live value**. This is **Phase 3** of [`specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md) §6 and realizes PRD FR-5 and FR-7 ([`specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md)). The configuration knowledge graph reuses the **State Hub** relationship store rather than building a new graph database ([`docs/ecosystem-boundaries.md`](../docs/ecosystem-boundaries.md) §2.5; [`research/configuration-control-plane.md`](../research/configuration-control-plane.md) §5). **Depends on:** ATLAS-WP-0002 (entries carry `sources[].role` and `relations`). Benefits from, but does not require, ATLAS-WP-0003 (connectors enrich coverage). **Hard boundary:** this renders the effective-config *path* only. Resolving the actual effective *value* is out of scope (delegated downstream); `feature-flag` surfaces link to feature-control and are never re-resolved here. **Exit condition:** `config explain ` emits an ordered override path with winning layer, what it overrode, validating schema, and owner; config-typed edges are expressible to the State Hub graph; a blast-radius view lists affected consumers. **Sequencing:** T01 (resolver) → T02 (CLI) and T05 (tests); T03 (graph edges) → T04 (blast-radius). T01 and T03 may start in parallel. ## Effective-config path resolver (static) ```task id: ATLAS-WP-0004-T01 status: done priority: high state_hub_task_id: "cee293aa-b407-4b97-a462-b67d7aa0f170" ``` Result 2026-06-27: Added `tools/effective_config.py` — a pure, deterministic resolver that orders a surface's `sources[]` by canonical L0-L9 layer rank and emits the override path (contributing layers, winning layer, what each overrode, validator, owner). Renders the PATH only, never a value; non-layer roles (feature-control-key) are listed as linked authority. Verified order-independent (8x shuffle -> identical path). Implement a static resolver that, from a surface's `sources[]` (with layer `role`), the L0–L9 ordering, and the explicit merge rules, produces the **override path**: ordered contributing layers, the winning layer, what each overrode, the validating schema, and the owner — never a live value. Honors non-overridable guardrails. See the `config explain` shape in [`wiki/ConfigLayering.md`](../wiki/ConfigLayering.md). - **Acceptance:** given a surface with ordered sources, the resolver returns a deterministic, order-independent override path with owner + validator refs and no resolved value. ## `config explain` tool ```task id: ATLAS-WP-0004-T02 status: done priority: high state_hub_task_id: "5d66a8c1-74bd-4c6f-9ea6-839e884ad103" ``` Result 2026-06-27: Added `tools/config_explain.py` and `make explain SURFACE=...`. Renders the resolver output (layer path, overrides, winning layer, validator, owner, consumers, secret refs) for any `surface.*` id. Verified on all 4 seeded surfaces; no values or secret values appear in output. Documented in `.claude/rules/stack-and-commands.md`. Add a `tools/` command (e.g. `config_explain.py`) that takes a `surface.*` id and renders the resolver output as the human/agent-readable `config explain` view. Reuse the existing `tools/` + Makefile pattern (`make explain SURFACE=...`). - **Acceptance:** `config explain surface.infotech.state-hub.api-config` prints the ordered layer path, overrides, validator, owner, and consumers. ## Config knowledge graph edges to State Hub ```task id: ATLAS-WP-0004-T03 status: done priority: medium state_hub_task_id: "7b16eaa0-f5e1-4ff3-809d-729b312fd154" ``` Result 2026-06-27: Added `tools/config_graph.py` + `make graph`/`graph-query`. Emits config-typed edges (consumed_by/overrides/depends_on_secret/related_to) to `registry/indexes/graph.yaml` (10 nodes, 10 edges) — queryable by surface id in both directions. config-atlas owns edge semantics; the State Hub owns storage (artifact is hub-ingestible). A `--check` staleness gate runs in `make validate`. Emit config-typed edges (`consumed_by`, `overrides`, `depends_on_secret`, `related_to`) from surface entries to the **State Hub** relationship/graph model, contributing the config semantics of each edge while the hub stores topology (PRD FR-7; ecosystem-boundaries §2.5). Do not build a separate graph store. - **Acceptance:** declared edges from the seed surfaces are expressed to the State Hub without duplicating its store; edges are queryable by surface id. ## Blast-radius / dependency view ```task id: ATLAS-WP-0004-T04 status: done priority: medium state_hub_task_id: "57e085c7-25e8-4e2d-bb3e-43b82e351aa9" ``` Result 2026-06-27: Added `tools/blast_radius.py` + `make blast-radius`. For a surface it lists direct consumers, transitively-dependent surfaces (cycle-safe), referenced secrets, owner, and a fan-out risk band. Verified: state-hub config is high risk (fan-out 4); leaf surfaces lower. Build a view that, for a given surface, traverses the graph to list affected consumers, dependent surfaces, and referenced secrets — the `config key → service → tenant → feature → secret → owner` chain from research §5. Supports change-risk reasoning before a change. - **Acceptance:** for a surface, the view lists downstream consumers and dependent surfaces; a change to a high-fan-out surface is visibly higher risk. ## Resolver determinism tests ```task id: ATLAS-WP-0004-T05 status: done priority: medium state_hub_task_id: "77b19d5f-f55c-48bb-8129-ba1478e47223" ``` Result 2026-06-27: Added `tests/test_effective_config.py` (6 tests) proving the override path is order-independent (16x shuffle), the winner is the most-specific layer, and no schema default / live / secret value leaks into explain output. Wired into `make validate` and CI (`validate-tests`). Add tests proving the override path is deterministic and order-independent (consistent with the merge-rule and CUE-unification rationale, research §3.3), and that no live or secret value ever appears in explain output. Wire into the CI gate (`make validate`). - **Acceptance:** tests pass in CI; an explain output containing a literal value or secret fails the test. --- After workplan or registry file updates, sync from `~/state-hub`: ```bash make fix-consistency REPO=config-atlas ```