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

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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
ATLAS-WP-0004	workplan	Effective-config explain and graph	infotech	config-atlas	finished	codex	custodian	2026-06-26	2026-06-27	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 §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: 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.

• 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: 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

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

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

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:

make fix-consistency REPO=config-atlas