Files
narratio/docs/internal/configuration.md

102 lines
5.7 KiB
Markdown
Raw Normal View History

# 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.