eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify scheduled provenance and history ordering

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-20 01:05:34 +00:00
parent 0d841d9d73
commit 31e10af9cb
2 changed files with 26 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/config.md
View File

@@ -429,14 +429,15 @@ sequence records replacement at the sequence path; history does not imply
identity-based merging across tiers.
A mapping assembled from the selected file and imports has one composite base origin
whose locations retain source traversal order. A mapping also visited by an overlay
has an overlay-layer composite origin with the lower contributing locations followed
by the overlay location; an empty mapping is still an explicit container even though
it contributes no children. Resolution origins are synthetic: they have layer
whose locations follow [scoped assembly order](#explicit-imports), not source-record
acquisition order. A mapping also visited by an overlay has an overlay-layer
composite origin with the lower contributing locations followed by the overlay
location; an empty mapping is still an explicit container even though it contributes
no children. Resolution origins are synthetic: they have layer
`resolution`, no fabricated file location, and a `derived_default` or `normalization`
operation. Reasons and dependency paths retain first occurrence order with duplicates
removed. Source records remain ordered as selected source, depth-first imports, the
selected overlay, then synthetic CLI records in supplied order.
removed. Source records and IDs retain [acquisition order](#explicit-imports),
including the underlay ordering described in [layered loading](#layered-loading).
Inheritance adds no acquired source or precedence layer. `Origin.Inheritance`
lists concrete transfers from contributor paths through destinations, with
@@ -499,9 +500,11 @@ historical path. Its effective value and each chronological before/after value a
`ValueSnapshot` records containing deterministic YAML text rather than mutable Go or
parser values. `Present=false` with empty YAML means absence or deletion; explicit
null is present and renders as `null`. The history starts with the canonical typed
application-default or Go-zero baseline, then includes only relevant base sources in
traversal order, the selected overlay, supplied CLI records, and audited net
resolution operations. Structural inheritance events appear after source replay
application-default or Go-zero baseline, followed by relevant underlay and main-tier
contributions in precedence order, the selected overlay, supplied CLI records,
and audited net resolution operations. Within each strict tier, replay follows
[scoped assembly order](#explicit-imports), not source-record acquisition order.
Structural inheritance events appear after source replay
and before typed reconciliation, including consumed or canceled `extends` input
and equal-valued child replacements. Overlapping parent/child resolution records
are rendered
@@ -819,11 +822,11 @@ completed configuration.
An empty mapping contributes no child definitions. Two empty mappings compose, and
an empty mapping neither clears nor conflicts with another mapping's children.
Shared mapping containers retain all contributing value locations as their composite
base origin. A conflict reports the first claim as its primary location and every
remaining claim as related locations, in deterministic source and declaration
traversal order. Traversal order never authorizes replacement. Composition clones
the resulting tree and its ordered claim records rather than mutating or aliasing an
input document.
base origin. A conflict reports the first claim in
[scoped assembly order](#explicit-imports) as its primary location and every
remaining claim as related locations in the same order. Assembly order never
authorizes replacement. Composition clones the resulting tree and its ordered
claim records rather than mutating or aliasing an input document.
## Selected overlays

11
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# Import Integration Correctness Audit
Status: in progress; finding 1 complete, findings 2 and 3 remain.
Status: in progress; findings 1 and 2 complete, finding 3 remains.
Reviewed tree: `91db99b` (including the six completed fixes through `5747ec4`).
Scope: import discovery/defaults and shared dependency-ready scheduling, including
@@ -63,7 +63,7 @@ glob, symlink, and cycle tests passed, as did `./scripts/check.sh`,
`go test -race -count=1 ./...`, and `git diff --check`. The original public
reproduction now succeeds for all selectors.
## 2. [ ] P2 — Describe scheduled provenance and history order consistently
## 2. [x] P2 — Describe scheduled provenance and history order consistently
Owner: [configuration contract](../config.md), especially layered metadata
around lines 431–439, historical explanation around lines 501–504, and strict
@@ -96,6 +96,13 @@ DFS behavior or introduce an independent provenance ordering rule. Existing
scheduled-placement and import-order tests already cover the main mechanics;
check the revised wording against the public cases above.
Completed: composite-origin, explanation-history, and conflict-location wording
now links to scoped assembly order and distinguishes it from source acquisition.
The descriptions retain precedence-tier order and item-local scope boundaries.
No scheduler or provenance implementation changed. Verified the public composite
origin/history and conflict reproductions, existing scheduled-placement and main/
underlay ordering tests, local documentation links, and `git diff --check`.
## 3. [ ] P3 — Qualify the empty-path inspection exception by requiredness
Owner: [import inspection contract](../config.md#explicit-imports), around lines