diff --git a/docs/releases/v2.1.0.md b/docs/releases/v2.1.0.md new file mode 100644 index 0000000..b536205 --- /dev/null +++ b/docs/releases/v2.1.0.md @@ -0,0 +1,70 @@ +# 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](../config.md), the +[Notarius integration contract](../integrations/notarius.md), and +[Artifact Development Workflows](../operations.md#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.