Add safe historical configuration explanations

This commit is contained in:
2026-09-06 22:14:54 +00:00
parent d4ec8607d1
commit 6ef240b1a0
17 changed files with 1032 additions and 141 deletions

View File

@@ -1365,7 +1365,43 @@ Acceptance:
## Stage 19 — Expose safe historical-value explanation
Status: pending.
Status: complete.
Completion evidence (2026-09-06):
- Added detached `ValueSnapshot`, `ValueChange`, `SecretReferenceInfo`, and
`Explanation` records plus `Result.Explain` and `Result.WriteExplanation` in
[`explain.go`](../../explain.go). Effective/default/domain values use canonical
typed projection; base/profile/CLI events preserve policy-validated input, with
explicit absent, null, equal-write, replacement, and deletion states.
- Extended composition, profile, and CLI handling to retain immutable applications
in traversal/precedence order. Explanation replays those applications on demand
with mapping recursion and atomic sequence replacement, then applies the existing
audited resolution subtree deltas. This reconstructs container and descendant
histories without a full retained tree per field, including superseded input that
could not decode into the final destination type.
- Applied tag, predicate, and dependency-cycle sensitivity across final and
historical application paths before snapshot projection. Snapshots recursively
redact classified descendants, resolved `Secret` metadata retains only successful
effective environment names, and classified references omit that annotation.
Shared immutable nodes count once toward a fixed 4,000,000-node retained-history
budget; excess fails safely with `explain.limit_exceeded`.
- Added deterministic human rendering with canonical quoted pointer paths, effective
and composite source locations/labels, representation labels, chronological
before/after YAML, reasons, dependencies, and secret lookup attribution. Unknown
paths write nothing; writer errors and short writes propagate. Added executable
`ExampleResult_Explain` and moved normative behavior to the
[current explanation contract](../config.md#historical-value-explanation), keeping
bootstrap reporting explicitly separate.
- Added focused coverage in [`explain_test.go`](../../explain_test.go) for the
imported-default/profile sequence 4 → 8 → 1, CLI and normalization, equal writes,
removed paths, parent replacement, composite mappings, atomic sequences,
superseded invalid input, null/empty values, successful and classified references,
historical/dependency-cycle canaries, returned-record mutation, deterministic and
failing writers, structural-sharing budgets, and an end-to-end secrets-bootstrap/
load/explain flow. Verified `go test ./...`, `go test -race ./...`, `go vet ./...`,
`go build ./...`, `go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on
linux/amd64. No deviations were required; consumer ergonomics remain later work.
Read: [explanation contract](initial.md#historical-value-explanation), redaction
rules, and history bounds above.