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 `--profile` is no longer accepted for Narratio pipeline selection. Explicit
imports from a directory named `profiles` remain valid. imports from a directory named `profiles` remain valid.
- Campaign, session, and canonical-party documents are strict single-source - Campaign, session, and canonical-party documents are strict single-source
ConfigKit schemas. They do not enable imports, overlays, or `configkit` ConfigKit schemas. They support sibling inheritance but do not enable imports,
directives. selected overlays, or `configkit` directives.
- Configured timeout and retry-delay durations must be positive. An omitted - Configured timeout and retry-delay durations must be positive. An omitted
artifact timeout continues to inherit its configured Scriptorium timeout. artifact timeout continues to inherit its configured Scriptorium timeout.
- Session files must be concrete; unresolved `{{ ... }}` placeholders fail load. - 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 fields of one entry can compose across imports. Narratio validates the resulting
effective entry using its ordinary domain rules. 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 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 rules. Only the selected overlay is opened; a malformed unselected overlay does
not affect a base or different-overlay load. Maps merge recursively, overlay not affect a base or different-overlay load. Maps merge recursively, overlay
scalars replace base scalars, and overlay lists replace base lists completely. scalars replace base scalars, and overlay lists replace base lists completely.
Explicit `false`, zero, empty strings, empty containers, and null values remain Explicit `false`, zero, empty strings, empty containers, and null values remain
explicit inputs and are not refilled by defaults. Overlays cannot inherit, explicit inputs and are not refilled by defaults. Overlay files cannot inherit
stack, import files, or declare another ConfigKit control section. 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 During ConfigKit loading, Narratio applies fresh typed defaults, recorded
entry-level defaults and normalization, read-only file-local validation, and 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 | | `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_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 | | `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 Generated keys are `<family>_<character_id>` and generated output paths must
not collide with explicit artifacts or another generated artifact. Families not collide with explicit artifacts or another generated artifact. Families

View File

@@ -13,7 +13,8 @@ pipeline-loading boundary implemented by `internal/config`.
exact `default` selections use the base; named overlays use the fixed exact `default` selections use the base; named overlays use the fixed
`overlays/<name>.yml` convention. `overlays/<name>.yml` convention.
2. ConfigKit parses the root and declared imports, additively merges base 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, 3. The definition resolver applies recorded entry-level and inherited defaults,
runs deterministic domain normalization, records derived publish destinations, runs deterministic domain normalization, records derived publish destinations,
and resolves ordinary paths relative to the root pipeline file. 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 a temporary downloaded session file therefore cannot invalidate the resolved
pipeline or campaign context. pipeline or campaign context.
Campaign and session files use independent ConfigKit definitions with imports Campaign and session files use independent single-source ConfigKit definitions
and overlays disabled. Campaign files normally load directly from their source; 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 session files are first read through the 8 MiB bounded-read boundary because the
application must reject unresolved template placeholders before passing an exact application must reject unresolved template placeholders before passing an exact
byte snapshot to ConfigKit. Local and remotely downloaded session bytes then use 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 Scriptorium, and shared scalar/path checks. These are package-local ownership
boundaries rather than extension points or a general validation framework. 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 Validation is read-only, fails fast, and does not define which of several
independent invalid fields is reported first. Map-backed declarations are independent invalid fields is reported first. Map-backed declarations are
nevertheless traversed deterministically. Reusable domain normalization is an nevertheless traversed deterministically. Reusable domain normalization is an

View File

@@ -172,15 +172,22 @@ or other non-regular conflict into a successful restore.
## Configuration ## 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. - YAML decoding rejects unknown fields.
- Defaults are centralized and testable. - 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 - Validation rejects invalid configuration before stage execution where
practical. practical.
- Root-owned imports and one selected overlay resolve deterministically through - Root-owned imports and one selected overlay resolve deterministically through
the configuration owner; commands do not implement their own merge rules. 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 - Canonical party rosters are campaign-owned. Their derived players projection
and concrete character-family artifacts are resolved before runtime stages and concrete character-family artifacts are resolved before runtime stages
or adapters receive configuration. or adapters receive configuration.

View File

@@ -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 Complete when resolved values, not source layout or secret bytes, determine
effective comparison, and inherited credentials obey the existing safe boundary. 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 Purpose: make the adopted behavior understandable and usable without expanding
Narratio's configuration surface. Narratio's configuration surface.

View File

@@ -16,8 +16,10 @@ in the [configuration reference](../docs/config.md).
one family per `artifact-families/<key>.yml`, and the fixed one family per `artifact-families/<key>.yml`, and the fixed
`overlays/testing.yml` overlay. Production values live in the base. The `overlays/testing.yml` overlay. Production values live in the base. The
bundle demonstrates an input-only artifact dependency, two character families bundle demonstrates an input-only artifact dependency, two character families
sharing the campaign party, and a testing-only disabled artifact. Inspect it sharing the campaign party, and a testing-only disabled artifact. The testing
offline with: 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 ```sh
narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml

View File

@@ -9,6 +9,7 @@ scriptorium:
player_handout: player_handout:
profile_id: testing-placeholder profile_id: testing-placeholder
testing_notes: testing_notes:
extends: session_recap
enabled: false enabled: false
output_path: artifacts/testing-notes.md output_path: artifacts/testing-notes.md
artifact_families: artifact_families:

View File

@@ -442,6 +442,18 @@ func TestExamplesLoadAndValidate(t *testing.T) {
if !exists || artifact.Enabled { if !exists || artifact.Enabled {
t.Fatalf("testing-only disabled artifact = %#v", artifact) 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)
}
} }
}) })
} }