Add explicit pipeline configuration imports

docs/internal/configuration.md

@@ -0,0 +1,48 @@
+# Configuration Internals
+
+User-visible fields, defaults, and selection behavior belong in the
+[Configuration Reference](../config.md). 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.