Document and benchmark sibling inheritance

docs/adr/0009-sibling-inheritance.md

@@ -0,0 +1,76 @@
+# ADR 0009: Resolve Sibling Inheritance After Source Assembly
+
+## Status
+
+Accepted and implemented. The [configuration contract](../config.md#sibling-inheritance)
+owns current behavior; the [implementation plan](../roadmap/implementation.md)
+records the delivery sequence.
+
+## Date
+
+2026-09-29
+
+## Context
+
+Named configuration mappings often share settings while retaining individual
+overrides. ConfigKit already distinguishes strict composition of independent
+source contributions from recursive overlay between explicit precedence tiers.
+Doing another untracked merge in applications would lose omission, source
+context, and historical explanation information. A shared structural operation
+must preserve the same presence and provenance model as the rest of loading.
+
+Inheritance also interacts with source precedence, nested namespaces, version
+ownership, and secrets. Resolving it before source assembly would validate
+superseded references and copy values that a later tier should replace. Fully
+resolving nested relationships inside a reusable parent would bind them to the
+wrong sibling scope when copied into a child.
+
+## Decision
+
+Reserve `extends` as a built-in input key on mappings. A string names one exact
+sibling mapping; null cancels the relationship. Complete source acquisition,
+strict composition, selected overlay, and CLI precedence first. Then resolve
+each effective relationship in the parser-independent document tree, before
+typed defaults and decoding. A child recursively overlays its own payload on
+its resolved parent using the existing mapping-combination rules. This creates
+neither a source tier nor a configurable merge strategy.
+
+Resolve enclosing sibling chains before nested relationships. Reuse memoized
+parent templates with unresolved nested instructions; evaluate those instructions
+at each destination. Preserve original source applications separately from
+structural transfer/control evidence. Effective origins carry concrete
+source-to-destination derivation, and inspection projects relevant inheritance
+events between source replay and typed reconciliation. Inherited input counts as
+explicit presence, while direct replacement retains its own effective origin.
+
+The existing main-input version check remains at its original point. Reject
+structural contributions or directive consumption affecting its protected path.
+Classify sensitivity at corresponding source and destination paths and retain
+historical redaction. Secret references remain unresolved input until the
+existing lookup point. Keep all machinery behind the root-owned public facade.
+
+## Alternatives considered
+
+- **Application-owned inheritance after `Load`.** Leaves every consumer to
+  recreate ordering, presence, provenance, error reporting, and redaction after
+  ConfigKit has already declared a result complete.
+- **Resolve each source before precedence assembly.** Makes superseded
+  references active and can copy a parent definition before higher-priority
+  input finishes changing it.
+- **Resolve nested relationships in a cached parent subtree.** Shares more
+  ready-made output but binds nested sibling lookups to the parent's scope,
+  giving incorrect values at a child destination.
+- **Registered collections, configurable keywords, or multiple-parent merge
+  modes.** Increase public setup and semantic branches without a requirement
+  that warrants diverging from one structural rule.
+
+## Consequences
+
+Consumers can load a configuration once and inspect direct, inherited,
+defaulted, and application-derived values through the existing result surfaces.
+`extends` is no longer an ordinary application field, so existing configurations
+using that key as data must migrate. Expanding many children can materialize
+substantially more output than the input contains; projection and retained-history
+budgets bound that work without charging copies as newly acquired sources.
+Applications still own domain validation, entry selection, and runtime resource
+use.

docs/config.md

@@ -54,7 +54,8 @@ The current lifecycle is:
 ```text
 validate options → parse the selected source → traverse/compose enabled imports
   → build schema → check the optional application version → apply a selected overlay
-  → apply explicit CLI overrides → create and clone defaults → strictly decode
+  → apply explicit CLI overrides → expand sibling inheritance
+  → create and clone defaults → strictly decode
   → recorded application resolution
   → resolve typed secret references → semantic validation → classify secrets
   → snapshot configuration and metadata
@@ -152,6 +153,57 @@ The maintained [layered consumer example](consumers/README.md#native-filesystem-
 shows a main host file, two underlay tiers, embedded defaults, a mapping source,
 and explicit resource access without a second configuration pass.
 
+### Sibling inheritance
+
+Any input mapping may declare `extends: name` to inherit from the mapping named
+`name` among its immediate siblings. Names are exact keys, including the empty
+string; lookup does not search ancestor or unrelated scopes. The document root
+and a sequence-element mapping have no sibling namespace for their own string
+relationship, though mappings nested inside them can have one. An `extends`
+value of null cancels a relationship without looking up a parent. Other value
+types, missing or non-mapping parents, and cycles fail the load with value-free
+diagnostics.
+
+`extends` is reserved structural input across ordinary and layered loads, every
+source kind, imports, selected overlays, and explicit CLI overrides. It is
+consumed before typed decoding and need not appear in the application's Go
+types. Applications previously using `extends` as an ordinary YAML field must
+rename that key and its field. No collection registration or keyword setup is
+required.
+
+ConfigKit completes strict composition within tiers and precedence assembly
+between tiers before resolving relationships. An omitted `extends` retains a
+lower-priority relationship; `extends: null` cancels it while preserving the
+child's own settings. Superseded references are historical evidence, not active
+relationships to validate. Each child recursively overlays its own settings
+over its resolved parent: explicit zero, false, empty string, sequence, and
+null values replace inherited values, while mappings combine recursively.
+The child retains its key. All effective relationships resolve, including
+entries the application may never select for execution. Partial parent
+definitions undergo normal typed decoding and application-owned validation,
+not a special structural exemption.
+
+Enclosing relationships resolve first. Nested instructions carried by a parent
+are then resolved separately at each destination, so a child's nested sibling
+override can change an inherited nested relationship. Typed defaults and
+application-derived values do not start another inheritance pass. Inherited
+input counts as explicit presence for `Metadata.IsExplicit`,
+`Resolution.IsExplicit`, and absence-based resolver defaults, even for false,
+zero, empty, or null input. `Origin.Inheritance` distinguishes it from a direct
+declaration with concrete source, destination, and controlling directive paths.
+A direct child replacement has its own effective origin; displaced ancestry
+remains inspectable in history. An inherited relative resource keeps the
+declaring source's passive `SourceContext`, not the child's directory.
+
+The optional schema-version checker still runs once against the main input at
+its original point. Inheritance cannot add, replace, or consume the protected
+version path; an unrelated relationship inside an enclosing mapping does not
+invalidate an unchanged version. Expansion uses the decoded projection
+node/depth limits without charging copied values as acquired sources;
+retained evidence uses the existing history-node limit. See the
+[consumer example](consumers/README.md#named-sibling-inheritance) for one-load
+usage.
+
 ### Source resource contexts
 
 `Result.SourceContext(id)` and callback-scoped `Resolution.SourceContext(id)`
@@ -222,8 +274,9 @@ successful result. Callback panics remain programming failures.
 `Result.Metadata` describes every final canonical path. Queries retain explicit
 key/index distinctions using actual effective and historical container shapes;
 only parsed numeric tokens are resolved contextually. A descendant that never
-existed is not historical merely because an atomic ancestor was replaced. Exact surviving input paths
-are explicit and have a base or overlay origin; omitted paths have a default origin.
+existed is not historical merely because an atomic ancestor was replaced. Exact
+surviving direct or inherited input paths are explicit and retain their source
+layer and derivation; omitted paths have a default origin.
 An explicit parent mapping does not make omitted children explicit. Null state and
 available source coordinates are retained. `History` records the Go-zero or application
 default baseline followed by exact base or overlay definitions, including
@@ -238,8 +291,9 @@ domain ownership rules remain application responsibilities. The method's Go
 documentation in [metadata.go](../metadata.go) defines enumeration and path-ordering
 details.
 
-History is chronological: a path can have a synthetic default record, its exact base
-definition, an overlay replacement, and a recorded resolution operation. A descendant
+History is chronological: a path can have a synthetic default record, its exact
+base definition, an overlay replacement, structural inheritance, and a recorded
+resolution operation. A descendant
 query uses the ancestor's path for a whole-container or whole-sequence replacement;
 the descendant can therefore retain history after `Lookup` stops reporting it as
 effective. Equal-valued input is still an explicit base definition, while a derived
@@ -255,6 +309,15 @@ operation. Reasons and dependency paths retain first occurrence order with dupli
 removed. Source records remain ordered as selected source, depth-first imports, the
 selected overlay, then synthetic CLI records in supplied order.
 
+Inheritance adds no acquired source or precedence layer. `Origin.Inheritance`
+lists concrete transfers from contributor paths through destinations, with
+each step's controlling `extends` path and location. `History` retains source
+applications at their original paths and projects parent contributions, child
+replacements, and consumed controls at destination paths after source assembly
+and before typed decoding. `HistoricalPaths` includes consumed directives and
+displaced inherited descendants. A control can have history even when `Lookup`
+reports it absent. Queries return detached records.
+
 ### Secret classification and effective rendering
 
 Secret classification combines `configkit:"secret"` field tags with the optional
@@ -270,6 +333,11 @@ Propagation reaches a fixed point, so record/map iteration order does not affect
 result and dependency cycles terminate. A dependency on a classified descendant or
 on a container that contains one is treated conservatively as sensitive. Applications
 must classify secret-producing transformations whose dependencies are not recorded.
+Inherited value and control paths link source and destination classifications
+through chains and nested copies; unrelated sibling fields are not classified
+merely because another field is secret. Displaced historical evidence remains
+redacted. Secret references are copied only as unresolved names; credential
+lookup stays after decoding and application resolution.
 
 `Result.WriteEffective` writes the frozen resolved snapshot as deterministic redacted
 YAML. Mappings sort by decoded key string, sequences retain order, indentation is two
@@ -304,7 +372,10 @@ parser values. `Present=false` with empty YAML means absence or deletion; explic
 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
 traversal order, the selected overlay, supplied CLI records, and audited net
-resolution operations. Overlapping parent/child resolution records are rendered
+resolution operations. Structural inheritance events appear after source replay
+and before typed reconciliation, including consumed or canceled `extends` input
+and equal-valued child replacements. Overlapping parent/child resolution records
+are rendered
 as one net subtree event with combined reasons and dependencies, rather than
 pretending that the recorded assignments ran in lexical order. Explicit equal
 writes remain visible. When input replay
@@ -556,8 +627,8 @@ input document.
 `[a-zA-Z0-9_-]+`; they are not paths. The empty name and exact lowercase name
 `default` select no overlay, and `overlays/default.yml` is never loaded implicitly.
 Every other name resolves only to `<configuration-root>/overlays/<name>.yml`, with
-no extension fallback, case normalization, inheritance, or overlay stack. A selected
-missing overlay is an error.
+no extension fallback, case normalization, inheritance between overlay files,
+or overlay stack. A selected missing overlay is an error.
 
 The overlay is a separately policy-validated YAML mapping. It is loaded after the
 base import graph is composed and its schema version is checked, but before defaults

docs/consumers/README.md

@@ -17,6 +17,7 @@ sanitized shapes using only ConfigKit and the Go standard library:
 | Seriatim-like | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
 | Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
 | Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
+| Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
 
 The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
 executable examples and ordinary tests. It contains no private application data,
@@ -50,6 +51,22 @@ both without redefining their syntax. ConfigKit overlays are configuration overl
 they do not select or replace an application's LLM, model, pipeline, report, or
 execution profile concepts.
 
+## Named sibling inheritance
+
+[`LoadPresets`](../../examples/consumers/inheritance.go) loads the maintained
+[`presets.yml`](../../examples/consumers/testdata/inheritance/presets.yml) in one
+call. `custom` inherits `enabled: false` from `base`, while its nested
+`settings.primary` changes the inherited `settings.secondary` result at the
+custom destination. The application struct has no `extends` field; ConfigKit
+consumes the relationship before strict typed decoding.
+
+The [executable example](../../examples/consumers/consumers_test.go) reads
+`Metadata.IsExplicit` for the inherited false value, then follows
+`Origin.Inheritance` back to the parent path while `Origin.Locations` identifies
+the declaring source. Applications still choose which preset to execute and
+validate domain meaning. The [configuration contract](../config.md#sibling-inheritance)
+owns exact lookup, precedence, cancellation, and migration rules.
+
 ## Native filesystem and layered input
 
 [`LoadBundled`](../../examples/consumers/layered.go) keeps the simple `Load` shape:
@@ -150,6 +167,7 @@ focused behavioral owner:
 | Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
 | `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
 | Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
+| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
 | Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |
 
 The package-level import-boundary test covers the consumer examples too: supported

docs/development.md

@@ -83,8 +83,9 @@ and current facade ownership belongs to the [component overview](internal/overvi
 The completed filesystem-source and underlay roadmap, original feature request,
 implementation plan, and resolved remediation record are preserved in Git history
 at `b604aa1` under `docs/roadmap/`. Current behavior belongs to the
-[configuration contract](config.md#layered-loading). Named-entry inheritance is
-separate proposed work in its [roadmap](roadmap/named-inheritance.md).
+[configuration contract](config.md#layered-loading). Built-in sibling
+inheritance is now part of the [configuration contract](config.md#sibling-inheritance);
+its [roadmap](roadmap/named-inheritance.md) preserves the design background.
 
 The completed overlay rename plan and release-workflow simplification record are
 preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay
@@ -141,6 +142,7 @@ code changes. Use the component overview to find the corresponding implementatio
 | File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
 | Native filesystem and mapping sources | [Native acquisition](../internal/engine/native_filesystem_test.go), [filesystem facade](../facade_filesystem_test.go), [mapping facade](../facade_mapping_test.go) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` |
 | Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` |
+| Sibling inheritance, provenance, history, sensitivity | [Expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` |
 | Layered loading and source equivalence | [Grouped lifecycle](../internal/engine/load_request_test.go), [layered facade](../facade_layered_test.go), [equivalence](../facade_equivalence_test.go) | `go test ./internal/engine -run '^TestGrouped'`, `go test . -run '^TestFacadeLayered'`, and `go test . -run '^TestEquivalentSourceForms'` |
 | Schema, defaults, projection, cloning | [Schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
 | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
@@ -149,6 +151,7 @@ code changes. Use the component overview to find the corresponding implementatio
 | Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [bootstrap](../internal/engine/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
 | Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native and layered examples](../examples/consumers/layered_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
 | Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
+| Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
 | Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestLocalDocumentationLinks\|TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
 | Development and release checker behavior | [Shell regression](../release_check_test.go) | `go test . -run 'TestCheckScripts\|TestDevelopmentCheck'` |
 | Guarded release publication and recovery | [Publication regression](../release_publish_test.go) | `go test . -run '^TestReleasePublication'` |

docs/internal/overview.md

@@ -8,8 +8,9 @@ private state; public signatures and fields do not expose engine types.
 Implemented component owners:
 
 - `internal/engine` owns host and native-filesystem source acquisition,
-  grouped strict composition and recursive precedence assembly, schema
-  inspection, decoding, lifecycle coordination, callback auditing,
+  grouped strict composition, recursive precedence assembly, and destination-local
+  sibling inheritance before typed decoding. It also owns schema
+  inspection, lifecycle coordination, callback auditing,
   provenance/history, passive source-context retention, secret resolution and
   bootstrap, and safe inspection rendering. It never imports the root package.
 - Root `Source`, `Filesystem`, `Input`, `Underlay`, `Path`, `Secret`, records,
@@ -22,7 +23,8 @@ Implemented component owners:
   public engine bridge methods.
 - `internal/document` owns the parser-independent ordered tree and cloning.
   `internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
-- Engine mechanism tests own source, composition, decoding, callback, provenance,
+- Engine mechanism tests own source, composition, inheritance, decoding,
+  callback, provenance,
   source-context, secret, history, rendering, and bootstrap behavior. Root tests
   own public API compatibility, facade integration, documentation links, and
   dependency/public boundary checks. Consumer examples remain under
@@ -39,4 +41,6 @@ semantics. The [consumer adoption guide](../consumers/README.md) owns applicatio
 guidance. The [architecture policy](../policy/architecture.md) owns contributor
 boundaries, and [ADR 0006](../adr/0006-public-facade.md) records the facade
 decision. See the [development guide](../development.md) for validation commands
-and [release procedure](../release.md) for source-candidate gates.
+and [release procedure](../release.md) for source-candidate gates. [ADR
+0009](../adr/0009-sibling-inheritance.md) records why inheritance is a built-in
+post-assembly structural operation.

docs/policy/architecture.md

@@ -169,6 +169,15 @@ rules and opt-in version ownership, remain part of the configuration contract. C
 semantics do not require identical acquisition or lifetime behavior from every
 source kind.
 
+After source precedence is complete, built-in sibling `extends` relationships
+resolve structurally in the same parser-independent representation, using the
+existing recursive overlay rules. This adds neither an acquired source nor a
+consumer registration mechanism. Enclosing relationships precede nested
+destination-local resolution; typed defaults, application resolution, and
+secret lookup retain their existing lifecycle roles. The [configuration
+contract](../config.md#sibling-inheritance) owns the exact syntax and presence
+rules, and [ADR 0009](../adr/0009-sibling-inheritance.md) records the rationale.
+
 ConfigKit must define supported YAML semantics explicitly rather than inherit
 parser defaults. Processing order and diagnostics must be deterministic for the
 same inputs and options. Invalid input must not produce a successful usable

docs/roadmap/deferred.md

@@ -15,7 +15,8 @@ The following remain deliberately excluded:
 
 - automatic `conf.d` discovery;
 - remote imports, arbitrary providers, and additional configuration formats;
-- custom merge strategies, sequence merging, and reset operators;
+- custom merge strategies, sequence merging, reset operators, multiple-parent
+  inheritance, and cross-scope references;
 - named overlay inheritance;
 - parser-specific or custom structural-decoding extension APIs;
 - generic dynamic-subtree conversion and module-registry APIs;
@@ -28,7 +29,6 @@ Applications may build their own validate, effective-value, source, bootstrap, a
 explanation commands around the library. Broadening these boundaries requires
 concrete consumer evidence, compatibility review, and an explicit design change.
 
-Built-in sibling inheritance using `extends` is proposed in the
-[named-inheritance roadmap](named-inheritance.md), based on the
-[downstream request](feature-request-promptkit-inheritance.md). It is not yet
-implemented and is distinct from inheritance between selected overlay files.
+Built-in sibling inheritance using `extends` is implemented as described in the
+[configuration contract](../config.md#sibling-inheritance). It is distinct from
+inheritance between selected overlay files, which remains excluded above.

docs/roadmap/implementation.md

@@ -314,6 +314,15 @@ not a full duplication of every mechanism test. Run `./scripts/check.sh` and
 
 ## Stage 8 — Validate scaling and complete documentation
 
+**Completed 2026-09-29.** Benchmarks cover chains, shared-parent width, nested
+destinations, replacements, and full inspected loads. Skipping repeated scope
+assembly when no immediate relationship exists reduced measured work while a
+single boundary clone preserves caller-input ownership. The maintained preset
+example, configuration contract, consumer guidance, internal navigation,
+architecture/deferred scope, and ADR 0009 now describe the implemented feature.
+`./scripts/check.sh`, `go test -race ./...`, and the focused benchmarks passed.
+No release was tagged or published.
+
 Add focused benchmarks beside assembly/underlay benchmarks: long chains, wide
 shared-parent scopes, nested destination expansion, and replacements. Evaluate
 allocations/work against input, materialized output, and retained history,

docs/roadmap/named-inheritance.md

@@ -1,7 +1,8 @@
 # Built-In Sibling Configuration Inheritance
 
-Status: agreed feature design; not implemented. This document defines the intended
-end state. The [implementation plan](implementation.md) defines execution steps.
+Status: implemented. The [configuration contract](../config.md#sibling-inheritance)
+owns current behavior. This document preserves the agreed design and its
+baseline; the [implementation plan](implementation.md) records completed work.
 
 ## Purpose and priorities
 
@@ -23,7 +24,7 @@ reduced consumer configuration infrastructure. Computational efficiency matters
 within those goals: resolve shared ancestors once and account for the size of
 materialized results and retained history. Avoid an unconditional O(n) promise.
 
-## Current baseline
+## Baseline at design time
 
 Baseline: `b604aa167b684525f0d5d806d9c4267824151ee4`, after the filesystem-source
 and underlay implementation and its remediation.