From 25cf7ce05c19c7071d50e52c8c8f361224951281 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 24 Oct 2026 00:16:53 +0000 Subject: [PATCH] Clarify final identity validation and overlay semantics --- docs/config.md | 11 +++++++---- docs/roadmap/remediation.md | 8 +++++++- lifecycle.go | 6 ++++-- 3 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/config.md b/docs/config.md index 85c0466..a0b92b6 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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 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 | | --- | --- | --- | @@ -980,9 +982,10 @@ Overlay is intentionally distinct from strict composition: | Mapping | Mapping | Recurse by mapping key | | 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 -than extends a base sequence, `[]` clears it, null is an explicit replacement, and -cross-kind replacement is allowed when the final application schema accepts it. +Under these ordinary rules, scalars, sequences, and null are atomic. An overlay +sequence replaces rather than extends a base sequence, `[]` clears it, null is an +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 origin data; history retains the displaced definitions and identifies the parent replacement. Surviving overlay paths have overlay origins, while recursively shared diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 82c8a64..8bf8f05 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -348,7 +348,13 @@ English wording or exposing identity values. ## 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 the [selected-overlay contract](../config.md#selected-overlays). diff --git a/lifecycle.go b/lifecycle.go index 5bcfbeb..be533dc 100644 --- a/lifecycle.go +++ b/lifecycle.go @@ -17,8 +17,10 @@ type Definition[T any] struct { Secret func(Path) bool // SequenceIdentities declares the scalar fields used to combine records and // resolve record inheritance at selected sequence destinations. Registration - // errors are reported before source acquisition. These constraints do not yet - // validate identities introduced by defaults, CLI overrides, or callbacks. + // errors are reported before source acquisition. Before successful return, + // 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 }