narratio/docs/releases/v2.1.0.md

Narratio v2.1.0

This release adds explicit Notarius credential forwarding and cache reuse, with predictable forced regeneration and clearer artifact-development guidance.

Summary

Narratio can pass one typed API-key reference to Notarius and opt into reuse of its accepted execution checkpoints. Stable, verified reference snapshots allow unchanged references to retain their cache identity across Narratio invocations. Configuration loading now uses ConfigKit v0.3.0.

Compatibility

The new notarius.llm_api_key, notarius.resume, and notarius.chunk_cache fields are optional. Existing v2 configuration needs no schema migration. Configured credential references must resolve during configuration loading, even when extraction will not execute; omitted references add no requirement.

Forced extraction now omits Notarius checkpoint loading and requests chunk-plan refresh. This includes regenerate-artifacts, which remains an alias for a forced run from extract through analyze. analyze continues to force analysis only, preserving extraction results and transcripts.

Notarius v0.7.0 is the tested cache integration baseline, not an unconditional minimum-version gate. The executable must support the flags selected for the invocation, including --chunk_cache refresh for forced extraction. Reference bindings retain the contract introduced in Notarius v0.6.0. Receipt and artifact schemas are unchanged; reused producers may report zero production attempts.

Supported release platforms remain Linux amd64/arm64 and best-effort macOS arm64. macOS validation is cross-compilation, not native runtime testing.

Upgrade

No special migration is required for existing v2 configuration. To use the new features:

• Declare notarius.llm_api_key with the environment-variable name expected by the deployed Notarius profile, supplying its value through the existing environment or secrets-directory mechanism.
• Enable checkpoint recording in Notarius configuration before setting Narratio's notarius.resume: true. Prefer explicit persistent Notarius cache roots for service deployments. An optional notarius.chunk_cache overrides its ordinary chunk-plan policy.
• Expect an initial checkpoint miss when moving from old run-local reference paths to stable session snapshots. No migration or deletion of old caches is required. Force refreshes the current input's plan, not the whole cache.
• Use narratio analyze SESSION for analysis-only iteration, and narratio regenerate-artifacts SESSION when extraction should also be rebuilt.

See Configuration, the Notarius integration contract, and Artifact Development Workflows for current details.

Changes

• Upgraded ConfigKit from v0.1.2 to v0.3.0 and isolated pipeline-discovery tests from machine configuration.
• Added optional typed Notarius credentials, exact-name environment delivery, safe configuration projections, and captured-stream redaction for custom names.
• Added Notarius resume and chunk-cache controls with force taking precedence.
• Added verified, content-addressed session reference snapshots that survive ordinary run cleanup without becoming published artifacts.
• Preserved relative-workspace support for snapshot delivery and confinement.
• Kept credentials and cache-policy controls outside extract's semantic resume identity, so operational changes alone do not invalidate completed results.
• Added an opt-in real Notarius integration test using a local provider to verify reuse, partial-failure recovery, and forced refresh without paid calls.