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

@@ -58,16 +58,16 @@ Configured definitions are always registered. Without an explicit selection,
the effective analyze set contains enabled definitions. With `--artifacts`, the
exact named configured definitions become the effective set for that invocation,
regardless of their `enabled` value. The effective-set resolver itself does not
expand dependencies. Configuration has already materialized the sorted union of
explicit ordering edges and configured-artifact input edges, and the analyze
expand dependencies. Shared domain catalog derivation has materialized the sorted
union of explicit ordering edges and configured-artifact input edges, and the analyze
work planner closes targets over that one concrete prerequisite graph.
Availability is separate from executability. Configuration may normalize a
Availability is separate from executability. Invocation selection normalizes a
family selection into its concrete generated members before this resolver runs.
The effective set retains optional family
and character origin metadata, but its keys, catalog sources, and runtime
lookups remain concrete configured-artifact identities.
Family publish policies are likewise expanded into ordinary configured-source
publish rules during configuration resolution.
publish actions during domain catalog derivation.
Configured outputs, including non-executable prerequisites, become available
only when the versioned analyze state identifies a current result whose source,
contract, canonical configured path, size, and checksum match a confined

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.

View File

@@ -373,4 +373,4 @@ where the last session transition can require operator interpretation.
- Transcribe speaker state: `internal/manifest/transcribe_state.go`
- Package tests: `internal/manifest/*_test.go`
- Assembled execution behavior: `internal/app/runner_test.go`,
`internal/app/run_stage_test.go`
`internal/app/run_selection_test.go`

View File

@@ -16,7 +16,8 @@ cmd/narratio -> internal/app -> configuration and production composition
-> manifests and artifact resolution -> durable local/remote output
```
The executable delegates process behavior to the application boundary. The
The executable supplies signal-aware context and caller-owned streams to the
native CommandKit application boundary. The
application resolves configuration, composes concrete collaborators, acquires
session safety controls, and runs commands. Pipeline commands execute the
canonical stage sequence through adapter interfaces, while manifests record
@@ -26,8 +27,10 @@ The pipeline runner follows one explicit invocation lifecycle: inspect bounded
prerequisites without mutation, prepare the workspace layout, acquire one
session lock, load or create the authoritative session manifest, compose only
the collaborators needed by the selected range, execute each selected stage in
order, and then return the summary. Cleanup, when selected, is the ordinary
final stage rather than runner finalization work.
order, finalize terminal state, release resources, and return a possibly partial
summary with preserved failure causes. Narrow terminal local persistence detaches
cancellation; active work retains the canceled operation context. Cleanup, when
selected, is the ordinary final stage rather than runner finalization work.
The lock remains held from manifest initialization through finalization, and a
failed stage or required manifest save prevents later stages from starting.
@@ -36,8 +39,8 @@ failed stage or required manifest save prevents later stages from starting.
| Area | Implemented owners | Responsibility |
| --- | --- | --- |
| Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. |
| Configuration | [`internal/config`](configuration.md) | ConfigKit-backed pipeline imports and overlays, canonical party and family expansion, strict YAML loading, defaults, normalization, session templating, and validation. |
| Application orchestration | `internal/app` | Native CommandKit declarations/reporting, lazy configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. |
| Configuration | [`internal/config`](configuration.md) | Typed ConfigKit results and lifecycle defaults, imports/overlays, canonical party loading, separate catalog/player/publication derivation, session templating, and validation. |
| Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
| External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
| Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. |
@@ -45,7 +48,7 @@ failed stage or required manifest save prevents later stages from starting.
| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. |
| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
| Logging | `internal/logging` | Small Narratio-owned diagnostic/progress interface adapted to the invocation reporter. |
The application boundary composes concrete implementations. Stages depend on
Narratio-level contracts; external transport and SDK details remain in
@@ -137,4 +140,4 @@ before changing behavior.
The stage registry is implemented in `internal/stage/placeholders.go` and its
ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
force, failure, and invalidation behavior is exercised in
`internal/app/runner_test.go` and `internal/app/run_stage_test.go`.
`internal/app/runner_test.go` and `internal/app/run_selection_test.go`.

View File

@@ -53,7 +53,7 @@ Supported source families:
manifest record and durable output pass the configured-artifact evidence
contract; an incidental or stale canonical file is unavailable.
- validates selected artifact dependency order (cycle-safe topo ordering).
- consumes only the concrete dependency graph finalized by configuration;
- consumes only the concrete dependency graph derived in the shared domain catalog;
planning, prerequisite closure, execution, reuse, invalidation, and semantic
evidence do not infer a second graph from inputs.
- resolves required/optional inputs per artifact source definition into an

View File

@@ -39,9 +39,9 @@ stage non-resumable. A failure is recorded against cleanup; publish remains
succeeded and remote current state is unchanged. On a later normal full run,
valid upstream stages are skipped and cleanup is retried without republishing.
`narratio publish` selects publish only and never invokes cleanup. A bounded run
`narratio run SESSION --stage publish` selects publish only and never invokes cleanup. A bounded run
through `notify` or any earlier endpoint also excludes it. Operators may run
`narratio run-stage cleanup <session_id>` directly; missing, failed, malformed,
`narratio run <session_id> --stage cleanup` directly; missing, failed, malformed,
or identity-mismatched publication evidence fails before deletion.
## Implementation And Tests

View File

@@ -129,7 +129,7 @@ evidence does not replace those safety checks.
The commit boundary and cleanup authorization are normative architecture invariants; see
[Architecture](../policy/architecture.md#publish-commit-boundary).
Publish never deletes local state. The standalone `publish` command selects
Publish never deletes local state. `run SESSION --stage publish` selects
only this stage; a full run selects notify and cleanup afterward.
## Related Contracts And Tests

View File

@@ -72,7 +72,7 @@ The canonical cleanup stage:
republishing.
Manual cleanup uses the same root-confined deletion mechanism. Invocation
syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
syntax and exact deletion scope belong in [CLI](../cli.md#session-clean) and
[Operations](../operations.md#cleanup).
## Invariants