From f1f71d8cdfdc2b86f2fedea1eb45d078856d0328 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 4 Oct 2026 15:25:48 +0000 Subject: [PATCH] Document native configuration inheritance --- docs/config.md | 38 ++++++++++++++++--- docs/internal/configuration.md | 18 +++++++-- docs/policy/architecture.md | 11 +++++- docs/roadmap/implementation.md | 2 +- examples/README.md | 6 ++- .../production-testing/overlays/testing.yml | 1 + internal/config/load_validate_test.go | 12 ++++++ 7 files changed, 75 insertions(+), 13 deletions(-) diff --git a/docs/config.md b/docs/config.md index c8440f6..7a420e8 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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: ` 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.`: | `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 `_` and generated output paths must not collide with explicit artifacts or another generated artifact. Families diff --git a/docs/internal/configuration.md b/docs/internal/configuration.md index adb8121..b5d08a4 100644 --- a/docs/internal/configuration.md +++ b/docs/internal/configuration.md @@ -13,7 +13,8 @@ pipeline-loading boundary implemented by `internal/config`. exact `default` selections use the base; named overlays use the fixed `overlays/.yml` convention. 2. ConfigKit parses the root and declared imports, additively merges base - sources, applies only the selected overlay, and strictly decodes the result. + sources, applies only the selected overlay, resolves native sibling + inheritance, and strictly decodes the result. 3. The definition resolver applies recorded entry-level and inherited defaults, runs deterministic domain normalization, records derived publish destinations, and resolves ordinary paths relative to the root pipeline file. @@ -44,8 +45,10 @@ download retain that exact pipeline object and its private provenance. Removing a temporary downloaded session file therefore cannot invalidate the resolved pipeline or campaign context. -Campaign and session files use independent ConfigKit definitions with imports -and overlays disabled. Campaign files normally load directly from their source; +Campaign and session files use independent single-source ConfigKit definitions +with imports and selected overlays disabled; native sibling inheritance remains +available within each document. Canonical-party input follows the same +single-source rule. Campaign files normally load directly from their source; session files are first read through the 8 MiB bounded-read boundary because the application must reject unresolved template placeholders before passing an exact byte snapshot to ConfigKit. Local and remotely downloaded session bytes then use @@ -132,6 +135,15 @@ for core pipeline/session rules, external adapters, publish/storage, Notarius, Scriptorium, and shared scalar/path checks. These are package-local ownership boundaries rather than extension points or a general validation framework. +ConfigKit supplies composition, inheritance, presence, typed-secret, and +provenance mechanics; Narratio supplies the domain rules applied to the +effective decoded entries. There is no separate authoring-history acceptance +gate: contributors and declaration history remain inspection evidence, not an +additional validity condition. +The [configuration reference](../config.md#pipeline-imports-and-overlays) +documents sibling syntax, reserved-key migration, and the operator-visible +inspection behavior. + Validation is read-only, fails fast, and does not define which of several independent invalid fields is reported first. Map-backed declarations are nevertheless traversed deterministically. Reusable domain normalization is an diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 30f01e1..ff71ae2 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -172,15 +172,22 @@ or other non-regular conflict into a successful restore. ## Configuration -Configuration is strict, explicit, centralized, and operator-oriented. +Configuration is strict, explicit, centralized, and operator-oriented. ConfigKit +owns input loading, assembly, sibling inheritance, presence tracking, typed +secrets, and provenance. Narratio owns configuration-domain meaning and +fail-fast validation of the effective configuration. - YAML decoding rejects unknown fields. - Defaults are centralized and testable. -- Empty configured values do not silently replace meaningful defaults. +- Defaults apply only to absent fields. Explicit false, zero, empty, and null + values remain present and are evaluated by Narratio's domain rules. - Validation rejects invalid configuration before stage execution where practical. - Root-owned imports and one selected overlay resolve deterministically through the configuration owner; commands do not implement their own merge rules. +- Native ConfigKit metadata and supported resolution callbacks provide presence, + inheritance, and provenance information without a parallel loading or + ownership system. - Canonical party rosters are campaign-owned. Their derived players projection and concrete character-family artifacts are resolved before runtime stages or adapters receive configuration. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3a35ea3..1ac1fee 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -261,7 +261,7 @@ rewrite adapters or duplicate those tests simply because input can be inherited. Complete when resolved values, not source layout or secret bytes, determine effective comparison, and inherited credentials obey the existing safe boundary. -## Stage 6: Align policy, document inheritance, and maintain an example +## Stage 6: Align policy, document inheritance, and maintain an example [x] Purpose: make the adopted behavior understandable and usable without expanding Narratio's configuration surface. diff --git a/examples/README.md b/examples/README.md index f9c3083..532012f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -16,8 +16,10 @@ in the [configuration reference](../docs/config.md). one family per `artifact-families/.yml`, and the fixed `overlays/testing.yml` overlay. Production values live in the base. The bundle demonstrates an input-only artifact dependency, two character families - sharing the campaign party, and a testing-only disabled artifact. Inspect it - offline with: + sharing the campaign party, and a testing-only disabled artifact. The testing + overlay's `testing_notes` artifact inherits the recap prompt, inputs, and + testing profile while retaining its disabled status and separate output path. + Inspect it offline with: ```sh narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml diff --git a/examples/production-testing/overlays/testing.yml b/examples/production-testing/overlays/testing.yml index 4cb1dda..891222b 100644 --- a/examples/production-testing/overlays/testing.yml +++ b/examples/production-testing/overlays/testing.yml @@ -9,6 +9,7 @@ scriptorium: player_handout: profile_id: testing-placeholder testing_notes: + extends: session_recap enabled: false output_path: artifacts/testing-notes.md artifact_families: diff --git a/internal/config/load_validate_test.go b/internal/config/load_validate_test.go index fe5ee75..42d249d 100644 --- a/internal/config/load_validate_test.go +++ b/internal/config/load_validate_test.go @@ -442,6 +442,18 @@ func TestExamplesLoadAndValidate(t *testing.T) { if !exists || artifact.Enabled { t.Fatalf("testing-only disabled artifact = %#v", artifact) } + recap := cfg.Pipeline.Scriptorium.Artifacts["session_recap"] + if artifact.PromptID != "dnd.session_recap" || + artifact.PromptID != recap.PromptID || + artifact.ProfileID != recap.ProfileID || + artifact.ProfileID != "testing-placeholder" || + !reflect.DeepEqual(artifact.Inputs, recap.Inputs) || + artifact.Inputs["transcript"].Source != "narratio.transcript.final_trimmed" { + t.Fatalf("testing notes did not inherit the testing recap prompt, profile, and inputs: notes=%#v recap=%#v", artifact, recap) + } + if artifact.OutputPath != "artifacts/testing-notes.md" || artifact.OutputPath == recap.OutputPath { + t.Fatalf("testing notes output path = %q, want its distinct override", artifact.OutputPath) + } } }) }