config-atlas/workplans/ATLAS-WP-0004-explain-and-graph.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated

id	type	title	domain	repo	status	owner	topic_slug	created	updated
ATLAS-WP-0004	workplan	Effective-config explain and graph	infotech	config-atlas	ready	codex	custodian	2026-06-26	2026-06-26

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 §6 and realizes PRD FR-5 and FR-7 (specs/ProductRequirementsDocument.md). The configuration knowledge graph reuses the State Hub relationship store rather than building a new graph database (docs/ecosystem-boundaries.md §2.5; 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 <surface-id> 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)

id: ATLAS-WP-0004-T01
status: todo
priority: high

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.

• 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

id: ATLAS-WP-0004-T02
status: todo
priority: high

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

id: ATLAS-WP-0004-T03
status: todo
priority: medium

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

id: ATLAS-WP-0004-T04
status: todo
priority: medium

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

id: ATLAS-WP-0004-T05
status: todo
priority: medium

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:

make fix-consistency REPO=config-atlas