2026-08-30 12:33:43 +00:00
|
|
|
# Configuration Internals
|
|
|
|
|
|
2026-11-17 22:42:53 +00:00
|
|
|
User-visible fields, defaults, discovery, and selection belong in the
|
|
|
|
|
[Configuration Reference](../config.md). This document describes the
|
2026-11-20 06:41:59 +00:00
|
|
|
`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.
|