Add named pipeline profile composition

docs/config.md

@@ -59,6 +59,10 @@ remote state with an unsafe legacy identity must be migrated before use.
   root-only `composition.imports` list. Imported files contribute fields to one
   logical pipeline document; they do not override fields supplied by the root
   or another import.
+- A root pipeline may declare named profiles. Exactly one profile is selected
+  by an option-aware caller or by `composition.default_profile`; a caller's
+  explicit selection takes precedence. Declaring profiles without either form
+  of selection is an error.
 - Configured timeout and retry-delay durations must be positive. An omitted
   artifact timeout continues to inherit its configured Scriptorium timeout.
 - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
@@ -72,15 +76,22 @@ remote state with an unsafe legacy identity must be migrated before use.
   - local (`audio_dir` or `audio_files`), or
   - S3 (`audio_s3.prefix`).
 
-### Pipeline imports
+### Pipeline composition
 
-Large pipeline configurations may be split into explicitly named fragments:
+Large pipeline configurations may be split into explicitly named fragments and
+may declare one overlay per selectable profile:
 
 ```yaml
 composition:
   imports:
     - config/storage.yml
     - config/integrations.yaml
+  default_profile: production
+  profiles:
+    production:
+      overlay: profiles/production.yml
+    testing:
+      overlay: profiles/testing.yml
 
 campaigns:
   root: /usr/local/share/narratio/campaigns
@@ -100,6 +111,30 @@ name the full field path and every source that claimed it. The assembled YAML is
 then decoded against the normal strict pipeline schema and defaults are applied
 once.
 
+Profile names are case-sensitive, non-empty, trimmed, and cannot contain
+control characters. If `profiles` is present, it must contain at least one
+entry and every entry must contain only an `overlay` path. An explicit profile
+selection overrides `default_profile`; unknown and explicitly empty selections
+fail. Narratio never selects the first profile implicitly and does not read a
+profile selection from the environment.
+
+Every declared overlay is resolved relative to the root pipeline directory and
+must satisfy the same confined regular-YAML-file rules as an import. Narratio
+parses every declared overlay even when it is not selected, then applies only
+the selected one. Maps merge recursively, overlay scalars replace base scalars,
+and overlay lists replace base lists completely. Explicit `false`, zero, empty
+lists, and empty maps remain meaningful. YAML null cannot delete a value, and
+kind changes are rejected. Profiles cannot inherit from or stack with other
+profiles, and overlays cannot import files or declare profiles.
+
+After composition, Narratio strictly decodes the result, applies centralized
+defaults once, resolves ordinary paths, and computes a deterministic effective
+configuration digest. The digest represents the normalized, secret-free
+runtime pipeline mapping; it excludes composition declarations, source
+provenance, profile identity, and raw environment secret values. Equivalent
+effective mappings therefore have the same digest regardless of how fields are
+split among the root and imports.
+
 An imported field has the same meaning it would have in a monolithic root
 pipeline. In particular, ordinary relative pipeline paths continue to resolve
 from the root pipeline directory, not from the importing fragment's directory.
@@ -192,6 +227,8 @@ Rules:
 | Field | Type | Required | Default / Rule |
 | --- | --- | --- | --- |
 | `composition.imports[]` | list of strings | No | explicit additive pipeline fragments relative to the root pipeline directory; `.yml` or `.yaml` regular files only |
+| `composition.default_profile` | string | Conditional | selected when profiles exist and no caller explicitly selects one; must name a declared profile |
+| `composition.profiles.<name>.overlay` | string | Conditional | required for every declared profile; one confined `.yml` or `.yaml` overlay relative to the root pipeline directory |
 | `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
 | `pipeline.workspace.cleanup_after_publish` | bool | No | `false` |
 | `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |