Document native configuration inheritance

This commit is contained in:
2026-10-04 15:25:48 +00:00
parent 39af6ef941
commit f1f71d8cdf
7 changed files with 75 additions and 13 deletions

View File

@@ -116,8 +116,8 @@ remote state with an unsafe legacy identity must be migrated before use.
`--profile` is no longer accepted for Narratio pipeline selection. Explicit
imports from a directory named `profiles` remain valid.
- Campaign, session, and canonical-party documents are strict single-source
ConfigKit schemas. They do not enable imports, overlays, or `configkit`
directives.
ConfigKit schemas. They support sibling inheritance but do not enable imports,
selected overlays, or `configkit` directives.
- 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.
@@ -175,13 +175,37 @@ every map path, including artifact and artifact-family entries, so distinct
fields of one entry can compose across imports. Narratio validates the resulting
effective entry using its ordinary domain rules.
After base sources are composed and the selected overlay is applied, ConfigKit
resolves native sibling inheritance before typed decoding. Any mapping may use
`extends: <sibling-key>` to inherit from an exact key in the same enclosing map;
lookup does not search parent maps or unrelated scopes. The child keeps its own
key and overlays its explicit fields on the resolved parent. Mappings combine
recursively, while explicit scalar, list, false, zero, empty, and null values
remain the child's values. Parent entries remain ordinary configuration entries
and must satisfy Narratio's normal effective-domain validation; inheritance does
not create templates exempt from domain rules. Inherited explicit input counts
as present for absence-based defaults.
Use [`config sources`](./cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
to inspect native effective contributors and inheritance origins; composite
artifact definitions may report multiple source paths.
The key `extends` is reserved structural input wherever ConfigKit is used,
including pipeline roots, imported files, selected overlay values, dynamic
artifact IDs, prompt-variable mappings, campaigns, sessions, and canonical-party
inputs. Rename any existing ordinary-data key named `extends`;
there is no opt-in or automatic conversion. See the pinned [ConfigKit v0.5.0
configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance)
for exact lookup, composition, presence, and provenance semantics.
Overlay names are case-sensitive and use ConfigKit's safe fixed-path naming
rules. Only the selected overlay is opened; a malformed unselected overlay does
not affect a base or different-overlay load. Maps merge recursively, overlay
scalars replace base scalars, and overlay lists replace base lists completely.
Explicit `false`, zero, empty strings, empty containers, and null values remain
explicit inputs and are not refilled by defaults. Overlays cannot inherit,
stack, import files, or declare another ConfigKit control section.
explicit inputs and are not refilled by defaults. Overlay files cannot inherit
from or stack on other overlay files, import files, or declare another ConfigKit
control section. Values in the selected overlay may use native sibling
`extends` directives; those relationships resolve after overlay application.
During ConfigKit loading, Narratio applies fresh typed defaults, recorded
entry-level defaults and normalization, read-only file-local validation, and
@@ -631,7 +655,11 @@ For each `pipeline.scriptorium.artifact_families.<name>`:
| `output_path_pattern` | string | Yes | safe path beneath `artifacts/` with exactly one `{character_id}` token and no other brace syntax |
| `member_vars` | map | No | maps an ordinary Scriptorium variable name to a supported canonical character selector |
| `member_dependencies` | list | No | unique family keys; each generated member depends on the corresponding generated member of each listed family |
| `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) expanded into concrete publish outputs when enabled |
| `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) validated against effective `pipeline.publish` settings and expanded into concrete publish outputs when enabled |
An enabled family publish declaration is validated against the effective
`pipeline.publish` configuration, including its defaults; it does not require
an explicit `publish.enabled` declaration in the same source file.
Generated keys are `<family>_<character_id>` and generated output paths must
not collide with explicit artifacts or another generated artifact. Families