Document the Notarius overlay upgrade

README.md

@@ -8,7 +8,7 @@ root-owned application state.
 ## Variables
 
 ```yaml
-notarius_version: v0.7.0
+notarius_version: v0.8.1
 notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
 notarius_source_dir: /usr/local/src/notarius
 notarius_binary_path: /usr/local/bin/notarius
@@ -23,6 +23,7 @@ notarius_config_file_mode: "0644"
 notarius_config_version: 5
 notarius_promptkit_profile_dir: null
 notarius_promptkit_profile_file: null
+notarius_promptkit_transient_retries: null
 notarius_promptkit_local_backend_endpoint: null
 notarius_promptkit_local_backend_concurrency_limit: null
 notarius_configkit_imports: null
@@ -71,6 +72,36 @@ PromptKit profile values identify profile sources or a local backend endpoint;
 they never contain credentials. Supply any credential environment variables
 outside this role.
 
+`notarius_promptkit_transient_retries` renders
+`promptkit.transient_retries` when set. The null default omits it so Notarius
+retains its native retry behavior; integer `0` disables additional eligible
+transient transport attempts. These are additional attempts per generation for
+eligible transient provider failures, separate from pipeline and validator
+retries. Review combined retry and timeout budgets for a deployment rather
+than treating these settings as interchangeable. See the tagged
+[v0.8.0 migration notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
+and [v0.8.1 configuration reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md).
+
+## Upgrading to v0.8.1
+
+Notarius v0.8.0 replaced ConfigKit configuration selection via
+`--config-profile` and `profiles/<name>.yml` with `--config-overlay` and
+`overlays/<name>.yml`. Callers own their overlay files and application
+invocations; this role does not migrate files or select an overlay. The D&D
+suite's testing file and Narratio's downstream selector will be migrated
+together during coordinated suite integration, not by this standalone role.
+
+Configuration overlays are distinct from PromptKit LLM profiles.
+`notarius_promptkit_profile_dir` and `notarius_promptkit_profile_file` still
+select LLM-profile sources, while pipeline `llm_profile` and `--llm-profile`
+still select an LLM profile. Those names and meanings are unchanged.
+
+The v0.8.1 PromptKit dependency refresh changes profile-source checkpoint
+identity, so old checkpoints with the previous identity are not reused.
+Source-keyed chunk plans and published output are unaffected. Installing the
+role does not delete caches or force processing stages; see the tagged
+[v0.8.1 release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md).
+
 ## Example
 
 ```yaml
@@ -86,8 +117,9 @@ syntax checking and production-profile lint, and exercises the default CLI and
 native configuration validation before requiring clean repeated convergence.
 It verifies an explicitly selected Notarius release, combines missing-binary
 recovery with a caller-supplied Go executable while dependency management is
-disabled, and covers one representative configuration with null omission,
+disabled, and checks null omission and explicit zero transport retries in
-intentional falsey values, caller-side pipeline composition through a
+rendered and effective configuration. A representative configuration also
+covers intentional falsey values, caller-side pipeline composition through a
 test-owned ConfigKit import, and native validation and inspection. It mutates
 only the managed source, binary, configuration, a test-owned imported fragment,
 and a private temporary directory, then restores the default deployment during

defaults/main.yml

@@ -1,5 +1,5 @@
 ---
-notarius_version: v0.7.0
+notarius_version: v0.8.1
 notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
 notarius_source_dir: /usr/local/src/notarius
 notarius_binary_path: /usr/local/bin/notarius
@@ -14,6 +14,7 @@ notarius_config_file_mode: "0644"
 notarius_config_version: 5
 notarius_promptkit_profile_dir: null
 notarius_promptkit_profile_file: null
+notarius_promptkit_transient_retries: null
 notarius_promptkit_local_backend_endpoint: null
 notarius_promptkit_local_backend_concurrency_limit: null
 notarius_configkit_imports: null

meta/argument_specs.yml

@@ -48,6 +48,9 @@ argument_specs:
       notarius_promptkit_profile_file:
         type: str
         required: false
+      notarius_promptkit_transient_retries:
+        type: int
+        required: false
       notarius_promptkit_local_backend_endpoint:
         type: str
         required: false

templates/config.yml.j2

@@ -3,7 +3,7 @@ version: {{ notarius_config_version }}
 configkit:
   imports: {{ notarius_configkit_imports | to_json }}
 {% endif %}
-{% if notarius_promptkit_profile_dir is not none or notarius_promptkit_profile_file is not none or notarius_promptkit_local_backend_endpoint is not none or notarius_promptkit_local_backend_concurrency_limit is not none %}
+{% if notarius_promptkit_profile_dir is not none or notarius_promptkit_profile_file is not none or notarius_promptkit_transient_retries is not none or notarius_promptkit_local_backend_endpoint is not none or notarius_promptkit_local_backend_concurrency_limit is not none %}
 promptkit:
 {% if notarius_promptkit_profile_dir is not none %}
   profile_dir: {{ notarius_promptkit_profile_dir | to_json }}
@@ -11,6 +11,9 @@ promptkit:
 {% if notarius_promptkit_profile_file is not none %}
   profile_file: {{ notarius_promptkit_profile_file | to_json }}
 {% endif %}
+{% if notarius_promptkit_transient_retries is not none %}
+  transient_retries: {{ notarius_promptkit_transient_retries | to_json }}
+{% endif %}
 {% if notarius_promptkit_local_backend_endpoint is not none or notarius_promptkit_local_backend_concurrency_limit is not none %}
   local_backend:
 {% if notarius_promptkit_local_backend_endpoint is not none %}

tests/integration

@@ -41,6 +41,18 @@ validate_config() {
   "$binary_path" config validate --config "$config_path"
 }
 
+require_retry_zero() {
+  "$workspace_venv/bin/python" - "$1" <<'PY'
+import sys
+
+import yaml
+
+with open(sys.argv[1], encoding="utf-8") as stream:
+    config = yaml.safe_load(stream)
+assert config["promptkit"]["transient_retries"] == 0
+PY
+}
+
 cd "$repository_root"
 "$workspace_venv/bin/ansible-galaxy" collection install \
   -r collections/requirements.yml \
@@ -49,13 +61,34 @@ cd "$repository_root"
 "$workspace_venv/bin/ansible-lint" "$converge" "$prepare_import"
 
 baseline_log="$test_tmp/baseline.log"
-run_converge "$baseline_log"
+run_converge "$baseline_log" -e '{"notarius_promptkit_transient_retries": null}'
 "$binary_path" --version
 validate_config
+"$workspace_venv/bin/python" - "$config_path" <<'PY'
+import sys
+
+import yaml
+
+with open(sys.argv[1], encoding="utf-8") as stream:
+    config = yaml.safe_load(stream)
+assert "transient_retries" not in config.get("promptkit", {})
+PY
 baseline_repeat_log="$test_tmp/baseline-repeat.log"
-run_converge "$baseline_repeat_log"
+run_converge "$baseline_repeat_log" -e '{"notarius_promptkit_transient_retries": null}'
 require_clean_recap "$baseline_repeat_log"
 
+retry_config='{"notarius_promptkit_transient_retries":0}'
+retry_log="$test_tmp/retry.log"
+run_converge "$retry_log" -e "$retry_config"
+validate_config
+require_retry_zero "$config_path"
+retry_effective_config="$test_tmp/retry-effective-config.yml"
+"$binary_path" config effective --config "$config_path" > "$retry_effective_config"
+require_retry_zero "$retry_effective_config"
+retry_repeat_log="$test_tmp/retry-repeat.log"
+run_converge "$retry_repeat_log" -e "$retry_config"
+require_clean_recap "$retry_repeat_log"
+
 selected_release_log="$test_tmp/selected-release.log"
 run_converge "$selected_release_log" -e notarius_version=v0.7.0
 [[ "$("$binary_path" --version)" == 'notarius v0.7.0' ]]
@@ -85,7 +118,7 @@ require_clean_recap "$recovery_repeat_log"
 
 pipeline_group_one='{"dnd-session":{"llm_profile":"dnd-extraction","input":{"module":"seriatim"},"artifacts":{"spells":{"extract":{"module":"dnd/spells"},"normalize":{"module":"dnd/spells"}}}}}'
 pipeline_group_two='{"dnd-archive":{"llm_profile":"dnd-extraction","input":{"module":"seriatim"},"artifacts":{"spells":{"extract":{"module":"dnd/spells"},"normalize":{"module":"dnd/spells"}}}}}'
-representative_config="{\"notarius_pipeline_group_one\":$pipeline_group_one,\"notarius_pipeline_group_two\":$pipeline_group_two,\"notarius_configkit_imports\":[{\"path\":\"test-pipelines.yml\"}],\"notarius_promptkit_local_backend_endpoint\":\"http://localhost:8000/v1\",\"notarius_promptkit_local_backend_concurrency_limit\":0,\"notarius_cache_checkpoints_enabled\":false,\"notarius_cache_chunk_plans_mode\":\"bypass\",\"notarius_cache_chunk_plans_directory\":\"/tmp/notarius-cache/chunk-plans\",\"notarius_cache_checkpoints_directory\":\"/tmp/notarius-cache/checkpoints\",\"notarius_output_directory\":\"/tmp/notarius-output\",\"notarius_promptkit_profile_dir\":null,\"notarius_promptkit_profile_file\":null,\"notarius_debug_directory\":null}"
+representative_config="{\"notarius_pipeline_group_one\":$pipeline_group_one,\"notarius_pipeline_group_two\":$pipeline_group_two,\"notarius_configkit_imports\":[{\"path\":\"test-pipelines.yml\"}],\"notarius_promptkit_transient_retries\":0,\"notarius_promptkit_local_backend_endpoint\":\"http://localhost:8000/v1\",\"notarius_promptkit_local_backend_concurrency_limit\":0,\"notarius_cache_checkpoints_enabled\":false,\"notarius_cache_chunk_plans_mode\":\"bypass\",\"notarius_cache_chunk_plans_directory\":\"/tmp/notarius-cache/chunk-plans\",\"notarius_cache_checkpoints_directory\":\"/tmp/notarius-cache/checkpoints\",\"notarius_output_directory\":\"/tmp/notarius-output\",\"notarius_promptkit_profile_dir\":null,\"notarius_promptkit_profile_file\":null,\"notarius_debug_directory\":null}"
 "$ansible_playbook" -i "$inventory" "$prepare_import" -e "$representative_config"
 representative_log="$test_tmp/representative.log"
 run_converge "$representative_log" -e "$representative_config"
@@ -97,6 +130,8 @@ grep -Fq 'dnd-archive:' "$effective_config"
 grep -Fq 'mode: bypass' "$effective_config"
 grep -Fq 'enabled: false' "$effective_config"
 grep -Fq 'directory: /tmp/notarius-cache/chunk-plans' "$effective_config"
+require_retry_zero "$config_path"
+require_retry_zero "$effective_config"
 representative_repeat_log="$test_tmp/representative-repeat.log"
 run_converge "$representative_repeat_log" -e "$representative_config"
 require_clean_recap "$representative_repeat_log"