Document the native CLI and migration workflows

This commit is contained in:
2026-11-20 06:41:59 +00:00
parent faa8cb5822
commit 0e9cbc9c2a
16 changed files with 633 additions and 672 deletions

View File

@@ -2,100 +2,94 @@
User-visible fields, defaults, discovery, and selection belong in the
[Configuration Reference](../config.md). This document describes the
`internal/config` loading and resolution boundary.
`internal/config` loading and derivation boundary established by
[ADR 0003](../adr/0003-assign-configuration-ownership.md).
## Pipeline Loading
## Typed Configuration Handoff
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.
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.
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.
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.
## Loaded Context Resolution
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).
`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.
## Invocation Acquisition
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.
`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.
## Inspection And Provenance
`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.
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.
## Native Inspection
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.
`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.
## Canonical Party Domain
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.
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).
## Canonical Party And Derived Catalog
## Validation Ownership
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.
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.
`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.
## Artifact Family Resolution
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).
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.
## Safe Persistence And Semantic Resume
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.
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.