2.9 KiB
ADR 0015: Share Dependency-Ready Ordering Across Imports and Inheritance
Status
Accepted.
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. The lifecycle and scope decisions in ADR 0009 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.