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
|
`--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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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:
|
||||||
|
|||||||
@@ -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)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user