narratio/docs/releases/v2.0.0.md

Narratio v2.0.0

Narratio v2.0.0 replaces its configuration infrastructure with ConfigKit, simplifies the supported release platforms, and makes artifact definitions and their effective dependency graph directly inspectable.

Summary

Pipeline roots now use ConfigKit v0.1.2 for strict YAML loading, explicit imports, fixed-path named profiles, provenance, defaults, and typed credential references. The recommended production layout keeps production values in the base, defines each ordinary artifact and artifact family in its own imported file, and keeps testing changes in profiles/testing.yml.

Configured-artifact inputs now create their dependency edges automatically. narratio config artifacts reports the finalized concrete catalog, including generated party-family members, without loading a session or initializing runtime adapters.

Compatibility

This is a breaking configuration and platform release. There is no runtime fallback for the retired Narratio composition/profile catalog, pipeline.secrets or secrets.env_dir, credential _env fields, or the previous YAML presence/default behavior. Defaults apply only to absent values; explicit empty, zero, false, and null values retain their typed meaning and may fail Narratio domain validation.

The maintained binaries are Linux amd64, Linux arm64, and macOS arm64. Windows and macOS amd64 builds are no longer produced or supported. Existing v1 release notes remain historical descriptions of their releases.

Inspection commands still avoid session, manifest, workspace, adapter, and remote-service activity, but they are not credential-free loaders: every explicit typed credential reference in the selected effective configuration must resolve; references replaced or removed by that profile need not resolve. Pipelines containing artifact families also require a campaign so the canonical party can be expanded. config show is a secret-safe review projection, not a promised reloadable authoring file.

Upgrade

Migrate each operational bundle before running v2:

1. Replace old composition syntax with root-owned configkit.imports. Imports are additive base sources; they do not override one another.
2. Fold the old production overlay into the base pipeline. Move testing changes to profiles/testing.yml; compare the two independent resolutions with narratio config diff default testing.
3. Follow the maintained examples/production-testing layout: one explicit artifact entry per artifacts/<key>.yml and one family entry per artifact-families/<key>.yml. The map key, not the filename, is the stable artifact identity.
4. Move credential files to an untracked secrets/ directory beside pipeline.yml, or pass --secrets-dir. Rename S3 fields to access_key_id and secret_access_key, and rename the Audita field to llm_api_key.
5. For static S3 credentials, configure both S3 references (commonly OBJECT_STORAGE_KEY_ID and OBJECT_STORAGE_KEY) and make them resolvable. To use instance roles, workload identity, shared SDK files, or another AWS SDK discovery provider, omit both references. A partial pair is invalid.
6. Remove a depends_on entry when it only duplicates a narratio.artifact.<key> input. Keep explicit entries that express ordering without supplying the upstream output as an input.
7. Review ConfigKit's stricter explicit-value/null semantics and correct values that previously acquired defaults after being explicitly empty. Do not use config show output as a source migration mechanism.
8. Run config validate, config show, config sources, and config artifacts with the same profile, campaign, and secrets selection intended for runtime. Resolve the campaign-owned party whenever families are present.
9. Update deployment and download automation to one of the three maintained platform assets before removing the v1 binary.

The configuration reference, CLI reference, and maintained examples are the canonical detailed guides.

Changes

• Adopted ConfigKit v0.1.2 across pipeline, campaign, session, and party loading while keeping Narratio domain validation and post-campaign expansion explicit.
• Added ConfigKit imports and fixed profiles/<name>.yml pipeline overlays, unified safe effective show/diff/digest projection, and source provenance.
• Added invocation-scoped ConfigKit secrets-directory bootstrap and typed S3 and Audita credential references without exposing resolved values.
• Inferred, normalized, and validated configured-artifact input dependencies as part of the one concrete graph consumed by analyze planning and resume logic.
• Added config artifacts with stable concrete identities, definition sources, effective dependencies, and generated family/party provenance.
• Added the maintained production-base/testing-overlay artifact authoring layout.
• Reduced release assets and active platform support to Linux amd64/arm64 and macOS arm64.