131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
|
---
|
|||
|
|
id: ATLAS-WP-0004
|
|||
|
|
type: workplan
|
|||
|
|
title: "Effective-config explain and graph"
|
|||
|
|
domain: infotech
|
|||
|
|
repo: config-atlas
|
|||
|
|
status: ready
|
|||
|
|
owner: codex
|
|||
|
|
topic_slug: custodian
|
|||
|
|
created: "2026-06-26"
|
|||
|
|
updated: "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`](../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 <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)
|
|||
|
|
|
|||
|
|
```task
|
|||
|
|
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`](../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: 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
|
|||
|
|
|
|||
|
|
```task
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
```task
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
```task
|
|||
|
|
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`:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
make fix-consistency REPO=config-atlas
|
|||
|
|
```
|
|||
|
|
</content>
|