From 3c0700b5323293d44e3b1e67a50074d82d7a3bff Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 14:55:03 +0000 Subject: [PATCH] Document the Narratio v3 upgrade --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index deeb0ca..d523bb9 100644 --- a/README.md +++ b/README.md @@ -131,9 +131,7 @@ falsey values are preserved. `narratio_publish_outputs`, `narratio_notarius_references`, `narratio_notarius_outputs`, `narratio_scriptorium_artifacts`, and `narratio_scriptorium_artifact_families` are complete native caller values, so callers may compose them before assigning -them and the role does not merge or rewrite them. Credential lists contain -environment-variable names only; credential values remain outside this role -and are the caller's responsibility. The optional +them and the role does not merge or rewrite them. The optional `narratio_notarius_config_overlay` selects a Notarius ConfigKit overlay without coupling it to Narratio's own overlay name. The optional `narratio_notarius_resume` and `narratio_notarius_chunk_cache` settings expose Narratio's native extraction @@ -142,12 +140,65 @@ cache policy. ConfigKit imports and selected overlays are externally managed, and this role does not install the downstream applications, campaign content, or suite policy. -Narratio v3 removes the old Audita tuning, report, retention, and singular-key -role variables. It also replaces `narratio_notarius_llm_api_key` with -`narratio_notarius_credentials` and renames -`narratio_notarius_config_profile` to `narratio_notarius_config_overlay`. -Existing deployments that cannot migrate these inputs should retain their -previous Narratio role pin. +## Upgrading from Narratio v2 + +Narratio v3 removes these role variables and their native fields: +`narratio_audita_llm_api_key`, `narratio_audita_base_url`, +`narratio_audita_model`, `narratio_audita_total_llm_concurrency`, +`narratio_audita_proposal_llm_concurrency`, +`narratio_audita_validation_model`, +`narratio_audita_validation_llm_concurrency`, +`narratio_audita_work_dir_retention`, and `narratio_audita_report`. +Replace `narratio_notarius_llm_api_key` with the list-valued +`narratio_notarius_credentials`; rename `narratio_notarius_config_profile` to +`narratio_notarius_config_overlay`. Existing deployments that cannot migrate +these inputs should retain their previous role pin. See the tagged +[v3.0.0 release notes](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md). + +`narratio_audita_credentials` and `narratio_notarius_credentials` are lists of +environment-variable or secret-reference **names**, never credential values. +Callers supply nonempty values through Narratio's run environment or supported +secret source. Narratio resolves configured names when loading a pipeline, +including when the downstream stage will be skipped. Audita v2 needs names for +every credential in its configured backends, even backends not selected by the +current profiles; Notarius names must match its selected provider profiles. +The role does not inspect downstream files or resolve secrets. Null omits a +list or selector, `[]` emits an explicit empty list, and `""` emits an explicit +empty selector. A Narratio overlay replaces a credential list rather than +appending to it. + +Audita v2 owns its configuration, backend/model definitions, PromptKit profiles, +reporting, and debug policy. Configure it independently before using polish; +the role does not generate downstream files or guess replacements for the +removed tuning fields. The Audita overlay, proposal profile, and validation +profile selectors are independent of each other and Narratio's selected +overlay. The Notarius `config_overlay` selector is likewise independent; null +adds no downstream selection, while empty, `default`, and named strings are +passed to Notarius unchanged. Selected downstream features require compatible +Audita and Notarius executables; this role adds no version gate. See the tagged +[Audita](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/audita.md) +and [Notarius](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/notarius.md) +integration contracts. + +For Narratio itself, replace `--profile` with `--overlay` and move selected +`profiles/.yml` files to `overlays/.yml` beside the pipeline root. +Explicit ConfigKit imports from a directory named `profiles` remain valid; +PromptKit LLM-profile files are a separate concept. Notarius's renamed +`config_overlay` selects its own `overlays/` files, replacing its retired +configuration-profile selection. The D&D suite's testing file and selector +migrate later with coordinated suite integration, not in this generic role. + +Before opening an affected existing session, follow the tagged +[manifest migration procedure](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md#migrating-manifest-overlay-provenance): +back up the local manifest and change only +`effective_config.selected_profile` to `selected_overlay` (or remove the +retired informational member), preserving local progress and checkpoints. +Immutable remote snapshots are not edited in place. For named Notarius +selectors, the renamed field changes extraction resume evidence: the next +applicable run regenerates extraction with normal dependent invalidation. +Omitted/base selection does not gain invalidation solely from the rename. +The role performs no manifest migration, cache cleanup, or blanket forced +reruns. ## Example @@ -167,10 +218,11 @@ pipeline through Narratio as its application account and requires immediate clean repeated convergence. It explicitly selects `v2.1.0` and checks native version output, then combines missing-binary recovery with a caller-supplied Go executable while dependency management is disabled. A representative pipeline -checks null omission, falsey values, caller-composed native collections, and -the native Notarius credential-reference, `resume`, and chunk-cache fields -before native validation and a clean repeat. The suite restores the baseline -deployment during cleanup. +checks null omission, falsey values, caller-composed native collections, +credential-name lists, downstream selectors, and the native Notarius `resume` +and chunk-cache fields. It validates named and explicit-empty configurations +offline and requires clean repeats. The suite restores the baseline deployment +during cleanup. ```sh tests/integration