Document native configuration inheritance
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -13,7 +13,8 @@ pipeline-loading boundary implemented by `internal/config`.
|
||||
exact `default` selections use the base; named overlays use the fixed
|
||||
`overlays/<name>.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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user