102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
# Configuration Internals
|
|
|
|
User-visible fields, defaults, discovery, and selection belong in the
|
|
[Configuration Reference](../config.md). This document describes the
|
|
`internal/config` loading and resolution boundary.
|
|
|
|
## Pipeline Loading
|
|
|
|
Commands bootstrap secrets once before loading, then select an explicit file or
|
|
native required discovery. ConfigKit loads typed defaults, source-root imports,
|
|
and the selected overlay, resolves inheritance, and strictly decodes the
|
|
result. Narratio applies recorded defaults, normalization, resource resolution,
|
|
and effective-domain validation. The selected root, source contexts, metadata,
|
|
and authoring result are retained for provenance. Family expansion and checks
|
|
requiring the campaign occur after campaign and party resolution.
|
|
|
|
Resource resolution consults native entry origins and source contexts before
|
|
normalization. An effective source supplies the base when usable; otherwise the
|
|
main source, then the captured invocation directory, is the fallback. Explicit
|
|
CLI file references use the invocation directory. Derived values record their
|
|
dependencies. See the [configuration reference](../config.md#pipeline-imports-and-overlays)
|
|
for the resource classifications and native authoring contract.
|
|
|
|
## Loaded Context Resolution
|
|
|
|
`LoadedPipelineCampaign` carries the selected pipeline and campaign into local
|
|
or remote session resolution. Local campaign, session, and party loads enable
|
|
imports through their own ConfigKit definitions; only the pipeline selects an
|
|
overlay. Native optional search distinguishes an absent local session from an
|
|
invalid selected file. Remote session bytes have no incidental download-directory
|
|
context, and retain object provenance. Effective session strings are checked for
|
|
unresolved template tokens, and campaign/session identity and stable-input rules
|
|
remain Narratio-owned.
|
|
|
|
Campaign and session loaders retain detached document values after their own
|
|
resolution. The session document is captured before campaign defaults are copied
|
|
into runtime session state. Configuration-owned renderers produce standalone
|
|
campaign and session YAML, preserving omitted session overrides. Prepare uses
|
|
those renderers and canonical party rendering for materialization and resume
|
|
comparison.
|
|
|
|
## Inspection And Provenance
|
|
|
|
Read-only inspection shares production pipeline and campaign selection without
|
|
session discovery, workspace initialization, adapters, or manifest access. After
|
|
applicable campaign and family resolution, a safe typed final-domain DTO contains
|
|
concrete artifacts and generated publish rules. It stores credential reference
|
|
names rather than typed secrets. A defaults-backed native result freezes this
|
|
DTO without resolving credentials again; `WriteEffective` supplies show and
|
|
prepared pipeline YAML, and deterministic JSON of the same DTO supplies the
|
|
versioned semantic digest. Resolved resources participate in that digest, while
|
|
source layout and secret values do not.
|
|
|
|
Authoring results separately supply native origins, source histories, and empty
|
|
optional-import evidence to source and artifact inspection. Family and party
|
|
context identifies generated entries without reparsing sources. Diff fully
|
|
resolves each side against the same selected campaign and party, then uses
|
|
ConfigKit `Diff` on the safe snapshots. The command presents native JSON Pointer
|
|
paths and safe compact values.
|
|
|
|
## Canonical Party Domain
|
|
|
|
File-backed party loading enables imports; `ParseParty` accepts contextless bytes.
|
|
The shared definition checks the main document's version and Narratio validates
|
|
the effective character roster. Native acquisition order and source coordinates
|
|
establish roster order, favoring each child's own declaration. A deterministic
|
|
renderer writes standalone canonical party YAML from that roster; the players
|
|
projection and family expansion use the same resolved roster. The external format
|
|
is defined in the [party contract](../integrations/party.md).
|
|
|
|
## Validation Ownership
|
|
|
|
ConfigKit owns composition, inheritance, presence, typed-secret resolution, and
|
|
provenance. Narratio owns validation and normalization of effective domain
|
|
values. Source histories are inspection evidence, not an additional acceptance
|
|
gate. Focused configuration and application tests exercise imports, resource
|
|
contexts, snapshots, secret-safe inspection, party resolution, and materialized
|
|
inputs through the production boundaries.
|
|
|
|
## Artifact Family Resolution
|
|
|
|
Pipeline loading retains `scriptorium.artifact_families` as a resolution-only
|
|
declaration. Once campaign party resolution establishes a canonical roster,
|
|
configuration expands families in sorted family-key and character-ID order
|
|
into ordinary `ScriptoriumArtifactConfig` values. The expansion owns the narrow
|
|
`{character_id}` output substitution, closed member-variable selectors, key and
|
|
output collision checks, and the runtime-only family-origin catalog. It then
|
|
removes family declarations from `ScriptoriumConfig`, runs ordinary Scriptorium
|
|
validation, and refreshes the effective pipeline digest. Stages and adapters
|
|
therefore receive only concrete artifact maps.
|
|
|
|
The catalog retains sorted family member keys plus family/character/source
|
|
origins and the typed dependency/publish declarations for their later owners.
|
|
`member_dependencies` add corresponding ordinary concrete dependencies, while
|
|
the family-only `narratio.member_artifact.<family>` input form is rewritten to
|
|
the matching ordinary configured-artifact source. The catalog records those
|
|
resolved dependency and input identities with their declaring family and party
|
|
member. No member-artifact source is registered as a runtime policy source.
|
|
An enabled family publish declaration expands to ordinary configured-artifact
|
|
publish rules before the existing publish and lock validators run. Runtime
|
|
publication consequently receives no family wildcard or special matcher.
|