1.9 KiB
ADR 0022: Bind Companion Contexts After Main Selection
Status
Accepted.
Date
2026-11-09
Context
Applications choose a main-file search and may also declare companion imports and a selected overlay. The main directory is only known after discovery, so supplying every dependent context before loading duplicates selection or requires a preliminary load. ADR 0019 keeps main discovery explicit and inside loading.
Decision
Extend layered loading to bind application-declared non-file underlays to the resolved main context after acquisition. An explicit underlay context overrides the binding, and an explicit fallback or require-base option controls absence. Selected layered overlays choose an explicit context, the resolved main context, or a fallback in that order. Derived and fallback lookup use the context base; the inherited root continues to bound containment. Ordinary and explicit overlay lookup retain their established root-relative behavior.
Applications remain responsible for choosing searches, import declarations, and overlay names. Selection failures are terminal; no second search or application context callback is introduced.
Alternatives Considered
- Require applications to discover the main file separately. This repeats discovery and may run a complete load more than once.
- Implicitly scan conventional companion directories. This would impose application-specific conventions without an explicit declaration.
- Add only a relative file constructor. This would not cover mapping or bytes sources with existing import, placement, and composition rules.
Consequences
The load owns the resolved binding and keeps namespace, containment, source identity, and handle lifetime in the existing acquisition lifecycle. A missing base skips optional imports while preserving the declaring payload; required imports and require-base retain explicit failures. The configuration contract and public declarations describe the observable rules.