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

Clarify final identity validation and overlay semantics

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 00:16:53 +00:00
parent 57edb8ec19
commit 25cf7ce05c
3 changed files with 18 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/config.md
View File

@@ -971,7 +971,9 @@ and typed decoding. Overlay bytes, nodes, and source records count toward the sa
aggregate limits as base inputs. Its canonical path must remain within the configured aggregate limits as base inputs. Its canonical path must remain within the configured
root and must not duplicate a file already present in the base graph. root and must not duplicate a file already present in the base graph.
Overlay is intentionally distinct from strict composition: Collection destinations follow the
[collection operation and presence rules](#strict-document-composition) above.
The following table describes ordinary overlay behavior elsewhere:
| Existing lower node | Incoming overlay node | Result | | Existing lower node | Incoming overlay node | Result |
| --- | --- | --- | | --- | --- | --- |
@@ -980,9 +982,10 @@ Overlay is intentionally distinct from strict composition:
| Mapping | Mapping | Recurse by mapping key | | Mapping | Mapping | Recurse by mapping key |
| Any other pair of present nodes | Any other pair of present nodes | Replace the entire lower node | | Any other pair of present nodes | Any other pair of present nodes | Replace the entire lower node |
Scalars, sequences, and null are atomic. Thus an overlay sequence replaces rather Under these ordinary rules, scalars, sequences, and null are atomic. An overlay
than extends a base sequence, `[]` clears it, null is an explicit replacement, and sequence replaces rather than extends a base sequence, `[]` clears it, null is an
cross-kind replacement is allowed when the final application schema accepts it. explicit replacement, and cross-kind replacement is allowed when the final
application schema accepts it.
Replacing a subtree removes all displaced descendants from effective presence and Replacing a subtree removes all displaced descendants from effective presence and
origin data; history retains the displaced definitions and identifies the parent origin data; history retains the displaced definitions and identifies the parent
replacement. Surviving overlay paths have overlay origins, while recursively shared replacement. Surviving overlay paths have overlay origins, while recursively shared

8
docs/roadmap/remediation.md
View File

@@ -348,7 +348,13 @@ English wording or exposing identity values.
## 10. Remove Stale Public Contract Descriptions — P2 ## 10. Remove Stale Public Contract Descriptions — P2
Status: [ ] Open. Status: [x] Complete.
Completion: the public definition comment now describes final registered-identity
validation and its shape/lifetime boundaries. Selected-overlay prose explicitly
separates ordinary replacement from collection policy and links to the canonical
operation/presence tables. Verified against the implementation, local-link tests,
and `git diff --check`; no runtime behavior changed.
Owners: [`Definition.SequenceIdentities`](../../lifecycle.go), lines 18–21, and Owners: [`Definition.SequenceIdentities`](../../lifecycle.go), lines 18–21, and
the [selected-overlay contract](../config.md#selected-overlays). the [selected-overlay contract](../config.md#selected-overlays).

6
lifecycle.go
View File

@@ -17,8 +17,10 @@ type Definition[T any] struct {
Secret func(Path) bool Secret func(Path) bool
// SequenceIdentities declares the scalar fields used to combine records and // SequenceIdentities declares the scalar fields used to combine records and
// resolve record inheritance at selected sequence destinations. Registration // resolve record inheritance at selected sequence destinations. Registration
// errors are reported before source acquisition. These constraints do not yet // errors are reported before source acquisition. Before successful return,
// validate identities introduced by defaults, CLI overrides, or callbacks. // matching final sequences are also checked, including values from defaults,
// CLI overrides, and application resolution. Schema and validation govern
// path existence and shape; later caller mutations are outside this guarantee.
SequenceIdentities []SequenceIdentity SequenceIdentities []SequenceIdentity
} }