# 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.