Files
narratio/docs/internal/configuration.md

96 lines
5.3 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 derivation boundary established by
[ADR 0003](../adr/0003-assign-configuration-ownership.md).
## 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. Identity and previous-session assertions are separate
request checks against completed values. 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](../config.md#pipeline-imports-and-overlays).
## 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.
## 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](../integrations/party.md).
## 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.