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

11
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# Import Integration Correctness Audit # 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`). Reviewed tree: `91db99b` (including the six completed fixes through `5747ec4`).
Scope: import discovery/defaults and shared dependency-ready scheduling, including 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 `go test -race -count=1 ./...`, and `git diff --check`. The original public
reproduction now succeeds for all selectors. 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 Owner: [configuration contract](../config.md), especially layered metadata
around lines 431–439, historical explanation around lines 501–504, and strict 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; scheduled-placement and import-order tests already cover the main mechanics;
check the revised wording against the public cases above. 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 ## 3. [ ] P3 — Qualify the empty-path inspection exception by requiredness
Owner: [import inspection contract](../config.md#explicit-imports), around lines Owner: [import inspection contract](../config.md#explicit-imports), around lines