diff --git a/docs/adr/0009-sibling-inheritance.md b/docs/adr/0009-sibling-inheritance.md index deb6c07..8b2e788 100644 --- a/docs/adr/0009-sibling-inheritance.md +++ b/docs/adr/0009-sibling-inheritance.md @@ -3,8 +3,9 @@ ## Status Partially superseded by [ADR 0017](0017-collection-sequence-policy.md) for -sequence combination and [ADR 0018](0018-cli-after-structural-resolution.md) for -CLI-before-inheritance ordering. The remaining inheritance scope, ownership, and +sequence combination and the addition of identified-sequence sibling scopes, +and [ADR 0018](0018-cli-after-structural-resolution.md) for CLI-before-inheritance +ordering. Existing mapping-sibling scopes and the remaining ownership and inspection decisions remain accepted. The [configuration contract](../config.md#sibling-inheritance) owns implemented diff --git a/docs/adr/0017-collection-sequence-policy.md b/docs/adr/0017-collection-sequence-policy.md index 1e56336..8ddc063 100644 --- a/docs/adr/0017-collection-sequence-policy.md +++ b/docs/adr/0017-collection-sequence-policy.md @@ -7,8 +7,9 @@ Accepted. This supersedes the decisions about who declares identity and how sequences combine in [ADR 0014](0014-sequence-placement-and-composition.md), and the rule that inheritance always replaces sequences in -[ADR 0009](0009-sibling-inheritance.md). The existing source-placement and -inheritance-scope rules continue to apply. It also supersedes the whole-sequence +[ADR 0009](0009-sibling-inheritance.md). It also extends that ADR's sibling +scopes to identified sequences. Existing mapping-sibling scopes and source +placement continue to apply. It supersedes the whole-sequence precedence replacement rule in the proposed [ADR 0007](0007-source-backed-underlays.md). @@ -31,6 +32,9 @@ also need a way to require unique identities in the final loaded configuration. These rules must work consistently for imported records, inline sequences, overlays, and inheritance. +Records in a sequence may also share settings. Authors need to reuse those +settings through inheritance while keeping each record's own identity. + ## Decision ConfigKit manages identity and merge rules for each collection during loading. @@ -52,6 +56,20 @@ identity (`upsert`). Source layering and sibling inheritance use the same operations. For inheritance, the rules at the inheriting destination determine which operation applies. +An identified sequence is also a sibling scope for inheritance. A record may +inherit from one other record in the same sequence, selected by its complete +identity. Each record supplies its own identity before inheritance. The child +keeps that identity and combines its settings with the parent's other fields, +using the existing mapping and collection rules. Parents remain ordinary records +subject to normal validation. + +Resolve these relationships after source assembly, using the same dependency +ordering as mapping-sibling inheritance. Resolve nested relationships at each +inheriting destination. Preserve the assembled sequence order. Whole-record +upsert keeps its existing meaning; inheritance then uses the records that remain. +Typed defaults, CLI overrides, and application resolution follow the lifecycle +in [ADR 0018](0018-cli-after-structural-resolution.md). + An explicitly selected operation remains in effect at its destination until a higher layer changes it. When no explicit operation applies, use upsert if an identity definition is available; otherwise replace the whole sequence. Authors @@ -94,6 +112,10 @@ chooses how to store and track collection rules internally. - **Merge individual fields of records with matching identities.** Allows partial record updates, but adds rules for field conflicts and retained values. Replacing the whole record makes the update's scope clear. +- **Keep inheritance limited to mapping siblings.** Keeps parent lookup simpler, + but authors of sequence records must duplicate shared settings or applications + must implement inheritance themselves. Collection identity provides a way to + select a parent within the existing loading process. - **Check every YAML identity again at the end of loading.** Gives YAML declarations authority over values changed by defaults, CLI assignments, and application resolution. This extends the lifetime of those declarations; application @@ -112,6 +134,10 @@ which declarations still apply as records are replaced, copied, or moved to new positions. Lower-tier identity must be available before combining higher-tier contributions. +Record inheritance also requires parent lookup by identity and checking for +missing parents and cycles. Copied settings retain the same source, history, +and sensitivity information as mapping-sibling inheritance. + The configuration contract will define declaration syntax, identity comparison, omission and empty-value behavior, and diagnostics when the feature is implemented. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 6450189..1194a7b 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -260,12 +260,22 @@ Consistent combination semantics do not require identical acquisition or lifetim behavior from every source kind. Built-in sibling `extends` relationships resolve after source precedence in the -parser-independent document representation. Preserve their existing sibling -scopes and resolve enclosing relationships before nested destination-local -relationships. Mappings combine recursively; sequences use the inheriting -collection's policy. Inheritance remains built-in and creates no acquired source. +parser-independent document representation. Preserve existing mapping-sibling +scopes and allow an identified sequence to provide a sibling scope for its +records. A record may inherit from one parent in that sequence, selected by +complete identity. The child supplies and keeps its own identity while inheriting +the parent's other settings. Parents remain ordinary records subject to normal +validation. + +Use the shared dependency ordering and preserve assembled sequence order. +Resolve enclosing relationships before nested destination-local relationships. +Mappings combine recursively; sequences use the inheriting collection's policy. +Whole-record upsert replaces records during combination; explicit inheritance +uses the records that remain. Inheritance remains built-in and creates no +acquired source. [ADR 0009](../adr/0009-sibling-inheritance.md) records the -continuing scope and ownership decisions, with sequence combination revised by +original scope and continuing ownership decisions, with sequence combination +and identified-sequence inheritance defined by [ADR 0017](../adr/0017-collection-sequence-policy.md) and CLI ordering by [ADR 0018](../adr/0018-cli-after-structural-resolution.md).