narratio/docs/internal/configuration.md

Configuration Internals

User-visible fields, defaults, and selection behavior belong in the Configuration Reference. This document describes the internal pipeline-loading boundary implemented by internal/config.

Pipeline Loading

LoadPipeline assembles and validates a pipeline in this order:

1. Parse the root YAML into a presence-aware composition tree. The tree retains source names, full field paths, node kinds, declaration order, and explicit zero, false, empty-map, and empty-list values.
2. Remove the root-only composition envelope and validate its explicit imports list.
3. Open each import relative to the root pipeline directory through the confined regular-file boundary. Imports must use a .yml or .yaml extension and cannot traverse, use symlinks, repeat a file, import the root, or contain another composition envelope.
4. Additively merge the root body and imports. Distinct map leaves compose; repeated scalar or list paths and node-kind disagreements are conflicts.
5. Emit deterministic canonical YAML and strictly decode it into PipelineConfig.
6. Apply pipeline defaults once, then resolve ordinary relative pipeline paths from the root pipeline file.

This ordering preserves monolithic configuration behavior. Moving a field to an imported fragment changes its source ownership, not its path base, default, or schema semantics.

Diagnostics And Runtime Metadata

Syntax, duplicate-key, composition, conflict, and schema failures include the relevant source name and full field path. Additive conflicts report every claiming source so operators can repair the split without repeatedly rediscovering additional conflicts.

The loaded pipeline retains private runtime metadata for the absolute root path, ordered imports, contributing sources, and field ownership. This metadata does not participate in YAML decoding or alter the public configuration model.

Test Surfaces

composition_test.go protects the presence and merge algebra independently of the public schema. pipeline_composition_test.go exercises explicit imports, confinement, conflicts, strict decoding, metadata, and root-relative path behavior through LoadPipeline. Other configuration tests continue to protect defaults and validation after assembly.