generated from coulomb/repo-seed
tegwick
1866505ba4
Some checks failed
validate-registry / validate (push) Has been cancelled
Phase 2 (ATLAS-WP-0003): read-only discovery connectors reusing repo-scoping's scanner/candidate/approval pipeline — connector contract, repo-scoping fact ingestion, git-config scanner, feature-control flag connector, stale/unowned detection. Phase 3 (ATLAS-WP-0004): effective-config explain + knowledge graph — static override-path resolver, config explain tool, config-typed edges to the State Hub graph, blast-radius view, determinism tests. File-first per ADR-001; state_hub ids to be written by fix-consistency. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
|