69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# ADR 0015: Share Dependency-Ready Ordering Across Imports and Inheritance
|
|
|
|
## Status
|
|
|
|
Accepted. Implemented behavior is described in the
|
|
[configuration contract](../config.md#explicit-imports) and
|
|
[internal import overview](../internal/imports.md).
|
|
|
|
## Date
|
|
|
|
2026-10-19
|
|
|
|
## Context
|
|
|
|
Imports and sibling inheritance both resolve relationships between configuration
|
|
contributions. Their existing resolvers use different traversal rules, making
|
|
ordering depend on which mechanism expresses a dependency. Ordering affects
|
|
sequence contributions, provenance, and diagnostics, so a consistent rule is
|
|
part of ConfigKit's configuration model.
|
|
|
|
The resolvers also serve distinct purposes. Imports strictly compose sources;
|
|
inheritance overlays a child on its resolved parent after source assembly.
|
|
Item-local contributions and nested inheritance introduce scope boundaries that
|
|
resolution must preserve.
|
|
|
|
## Decision
|
|
|
|
ConfigKit owns one shared dependency-ready scheduler for imports and sibling
|
|
inheritance. Both resolvers use Kahn's algorithm with a stable ordering key,
|
|
selecting the smallest currently eligible node after its dependencies have
|
|
completed. The shared scheduler owns eligibility, deterministic tie-breaking,
|
|
and dependency-cycle identification. Each resolver owns construction of its
|
|
dependency relationships and application of its domain operations.
|
|
|
|
Apply the common scheduling rule within the scopes where dependencies are
|
|
available. Complete item-local contributions before item placement and resolve
|
|
enclosing inheritance before relationships in the resulting nested scopes.
|
|
Source discovery supplies the import graph; the scheduler determines resolution
|
|
order.
|
|
|
|
Strict composition, inheritance overlay, and precedence tiers retain their
|
|
existing ownership and meanings under [ADR 0001](0001-separate-composition-and-overlay.md).
|
|
The lifecycle and scope decisions in
|
|
[ADR 0009](0009-sibling-inheritance.md) continue to govern inheritance. Import
|
|
admission retains its cycle and repeated-source rules.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Deterministic depth-first postorder.** Keeps dependency branches together,
|
|
but gives traversal branch selection an additional role in ordering.
|
|
- **Dependency rounds.** Groups nodes by readiness rounds, but delays newly
|
|
eligible nodes until the current round finishes.
|
|
- **Descending longest-path depth.** Prioritizes the furthest dependencies,
|
|
but adds distance from the root as an ordering policy.
|
|
- **Separate resolver algorithms.** Allows local specialization, but leaves
|
|
consumers and maintainers with different rules for analogous dependencies.
|
|
|
|
## Consequences
|
|
|
|
Both resolvers follow one deterministic ordering model and share responsibility
|
|
for maintaining that model. Resolver-specific scopes, combination semantics,
|
|
and source-admission rules remain explicit at their integration boundaries.
|
|
|
|
Independent branches may interleave as nodes become eligible. Adopting this
|
|
rule changes existing traversal-dependent sequence positions and reporting
|
|
order, requiring coordinated review of source assembly, provenance, and
|
|
inheritance behavior. The configuration contract owns the implemented ordering
|
|
details.
|