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

Implement strict document composition

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-06 20:26:57 +00:00
parent a0cd0977ee
commit 3257b2124c
8 changed files with 438 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/roadmap/initial.md
View File

@@ -450,28 +450,24 @@ origin is a resolution operation, with input origins retained separately.
## Composition and overlay
Composition combines the main file and explicitly imported fragments as peers.
Repeated semantic definitions are errors, even when their values are equal.
Both conflicting locations must be reported. Prefer mappings keyed by stable
identifiers when entries need to be contributed independently.
Strict base composition is implemented and now owned by the
[current configuration contract](../config.md#strict-document-composition).
Intentional profile overlay remains target behavior. Its exhaustive operation table
is below; “value” includes scalar, sequence, mapping, and null, while absent means no
node rather than null.
The following table is exhaustive by node category. “Value” includes scalar,
sequence, mapping, and null. Absent means no node, not null.
| Existing/lower node | Incoming/higher node | Overlay |
| --- | --- | --- |
| Absent | Absent | Absent |
| Absent | Value | Incoming |
| Value | Absent | Existing |
| Mapping | Mapping | Recurse by key |
| Any other pair of present nodes | Any other pair of present nodes | Replace entire existing node |
| Existing/lower node | Incoming/higher node | Strict composition | Overlay |
| --- | --- | --- | --- |
| Absent | Absent | Absent | Absent |
| Absent | Value | Incoming | Incoming |
| Value | Absent | Existing | Existing |
| Mapping | Mapping | Recurse by key | Recurse by key |
| Any other pair of present nodes | Any other pair of present nodes | Collision | Replace entire existing node |
Two empty mappings compose successfully. An empty mapping contributes no child
changes to an existing mapping; it does not clear that mapping. A mapping can
replace a lower scalar, sequence, or null during overlay, subject to the final
schema. Sequences are atomic: two definitions collide in composition and the
higher sequence replaces the entire lower sequence in an overlay. `[]` clears a
sequence. There is no append, union, index merge, or mapping-clear operator.
A mapping can replace a lower scalar, sequence, or null during overlay, subject to
the final schema. Sequences are atomic and the higher sequence replaces the entire
lower sequence in an overlay. `[]` clears a sequence. There is no append, union,
index merge, or mapping-clear operator.
Replacing a parent must not leave effective metadata for removed children.
Sequence histories describe whole-sequence replacement; index origins refer to