5.5 KiB
Configuration Internals
User-visible fields, defaults, discovery, and selection belong in the
Configuration Reference. This document describes the
internal/config loading and derivation boundary established by
ADR 0003.
Typed Configuration Handoff
Pipeline, campaign, session, and party loaders retain their actual typed ConfigKit results. ConfigKit owns imports, overlay composition, inheritance, presence, typed secrets, and native source/history evidence. Narratio's supported definition callbacks complete configuration-owned defaults, normalization, resource resolution, and validation before handoff. Consumers read completed values without mutation.
Session definitions receive selected-campaign defaults before loading finishes. Recorded resolution preserves explicit empty/null/false/zero behavior and truthful dependencies. Campaign, session, and previous-session assertions run against resolved values in native validation callbacks. Standalone document renderers preserve materialization semantics without providing a second inspection authority.
Resource resolution consults native entry origins and source contexts. A usable effective source supplies the base, otherwise the main source and then captured invocation directory provide the fallback. Explicit CLI paths use the invocation directory. See resource rules.
Invocation Acquisition
internal/app/configuration_acquisition.go owns lazy invocation selections and
acquired context. Exact sources and effective-identity assertions are
complementary. App acquisition needs no campaign or party for expansion;
campaign acquisition needs no session. Session acquisition loads campaign
context when required for defaults. Explicit party acquisition does not require
a session. Credential bootstrap runs once per reached invocation after static
input checks.
LoadedPipelineCampaign retains one selected pipeline/campaign while local or
remote session resolution proceeds. Only absence permits remote fallback;
access, decoding, and identity failures retain their causes. Remote acquisition
prefers authored session-root input and uses the committed prepared snapshot
only when authored input is absent. Temporary materialization retains object
provenance and releases resources on success or failure. Read-only acquisition
creates no runtime workspace, execution lock, restore state, or stage adapter.
Native Inspection
configuration_commands.go adapts actual results with ckconfig.FromConfigKit.
Native show, sources, explain/history, validation, and comparisons consume that
result's values and evidence. There is no flattened replacement snapshot,
synthetic source reconciliation, or generated family catalog in app inspection.
Comparison sides load independently using each side's normal defaults and
selectors. App-only overrides pass through native selection into ConfigKit;
they remain invocation-local. Field overrides are unavailable to domain
execution/planning and other scopes. Shared bootstrap does not imply shared
overridden results. Public inspection and error paths preserve typed-secret
redaction and credential reference metadata. Load failures retain native errors
and source evidence; domain commands use ckconfig.AdaptDiagnostics for their
presentation without rewriting diagnostic records.
Canonical Party And Derived Catalog
File-backed party loading supports imports; contextless ParseParty accepts
bytes. The definition checks the main version and effective roster. Native
source coordinates establish roster order, favoring each child's declaration.
A deterministic renderer materializes canonical party YAML. The selected roster
supplies both the players projection and concrete family members, including when
an explicit party file replaces the campaign default.
ArtifactCatalog carries derived artifacts, family/member origins, resolved
dependencies, and expanded publication outputs separately from pipeline values.
Family declarations remain in the typed pipeline result. Derivation sorts
family keys and character IDs, substitutes {character_id} in outputs,
resolves closed member variables, and checks key/output collisions and domain
dependencies. Member-artifact inputs become ordinary concrete artifact sources;
family publish declarations become ordinary publication actions. No family
wildcard matcher is added to runtime publication.
Catalog listing, planning, stage execution, artifact inspection, fingerprinting, and previous-session requirements consume the same derived products. Validation of these products belongs to domain derivation rather than app inspection. External roster shape belongs in the party contract.
Safe Persistence And Semantic Resume
Preparation materializes standalone campaign/session/party/players inputs and a secret-safe pipeline projection. The projection preserves credential names, family declarations, numeric values, and null/empty distinctions. It is a persistence service, not a fabricated native result. An effective digest is informational; resume compares result-affecting semantic evidence from the same concrete products used by execution. Source arrangement, provenance, and overlay labels alone do not invalidate work.
Focused configuration/application fixtures cover imports, defaults, selected rosters, independent comparisons, override isolation, secret-safe persistence, and unchanged completed configuration across domain derivation and execution.