Files
narratio/docs/internal/configuration.md

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.