# ADR 0019: Keep Configuration Discovery Explicit and Inside Loading

## Status

Accepted.

## Date

2026-10-24

## Context

Applications often need a small ordered convention for choosing a main
configuration file. Keeping that choice entirely in each application repeats
path selection and file-loading plumbing. Moving the convention into ConfigKit
without an explicit declaration would make ordinary loads search paths that a
consumer did not choose, obscuring both precedence and filesystem access.

ConfigKit already owns synchronous source acquisition, parsing, composition,
decoding, validation, and inspection. A selected host file can therefore enter
that lifecycle as the existing file source, preserving its source identity,
resource context, and diagnostics. Optional exhaustion can use the same absent
main lifecycle as an explicitly absent source.

## Decision

Consumers choose and order the main-file conventions they want to use. They may
describe literal paths, directory filename groups, and supported directory
presets, and may mark the complete search as required. Search descriptions are
explicit inputs to loading; no preset or convention is activated implicitly.

During synchronous loading, ConfigKit resolves the description to one real host
file or to absence before parsing. The selected file follows the existing source
acquisition and processing rules. A selected-file access, parse, version,
composition, decode, or validation failure is terminal and does not resume the
search. Optional exhaustion shares the absent-main lifecycle; required
exhaustion reports a missing-source diagnostic. No candidate-attempt history is
added to public metadata.

This keeps convention choice with applications while moving repeated selection
and loading plumbing into the library's established lifecycle. It preserves
explicit control, ordinary source behavior, and complete-on-return ownership.

## Alternatives Considered

- **Keep all search and fallback loading in each application.** This preserves
  consumer ownership but repeats the file-selection and load coordination that
  ConfigKit already owns, and risks divergent handling of selected-file errors.
- **Search conventional locations implicitly during every load.** This reduces
  setup, but activates filesystem access and precedence the consumer did not
  select and makes ordinary source behavior less predictable.
- **Return candidate paths for the application to load one by one.** This keeps
  selection outside the load lifecycle and encourages repeated complete loads,
  potentially rerunning defaults, callbacks, and validation during fallback.

## Consequences

The public search description must be immutable and root-owned, with private
engine conversion and selection. The contract documents candidate ordering,
selection, exhaustion, context, and provenance; the API declaration documents
the public symbols. Dynamic bases and file availability are observed when each
load consumes the description. Applications remain responsible for selecting
conventions and for their schema and domain requirements.

The [configuration contract](../config.md) will own implemented behavior, the
[component overview](../internal/overview.md) will describe implementation
ownership, and the [implementation plan](../roadmap/implementation.md) tracks
delivery progress.