Document the native CLI and migration workflows
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user