Add safe historical configuration explanations
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user