# Feature 0020: Adopt Notarius v0.8.1 in the Standalone Role

Status: done

## Summary

Update the standalone Notarius role from v0.7.1 to v0.8.1, expose the new
PromptKit transient-retry setting, and document the ConfigKit overlay rename.
This is the third feature in the agreed
[application upgrade sequence](../application-upgrade-sequence.md).

## Problem or Opportunity

Notarius v0.8.0 renamed configuration selection to `--config-overlay` and
`overlays/<name>.yml`, removing the previous flag and lookup directory. It also
introduced configurable provider transport retries. v0.8.1 updates ConfigKit
and PromptKit to v0.4.2 and v0.11.2 without further intentional configuration or
subprocess-contract changes.

The standalone role currently renders schema version 5, supports native imports
and caller-supplied pipelines, and leaves profile assets externally managed.
Those boundaries remain appropriate. The suite, however, still uses the old
downstream selector; its application and dependency pins must not advance yet.

## Scope

- Default the standalone role to Notarius v0.8.1.
- Expose `promptkit.transient_retries` through one nullable role variable.
- Verify existing imports, pipeline composition, profile-source settings, and
  cache configuration remain compatible with the target release.
- Update standalone compatibility guidance and focused offline tests.
- Record the reviewed role revision for later coordinated suite integration.

## Non-goals

- Updating suite, collection, consumer, or other application-role pins.
- Migrating suite-owned testing files or Narratio's downstream selector.
- Deploying arbitrary overlay or LLM-profile assets in the generic role.
- Choosing D&D model, retry, timeout, or credential policy.
- Automatic renames, compatibility aliases, cache deletion, forced extraction,
  or production validation tasks.
- Upstream application changes, live inference, or operational deployment.

## Target End State

### Installation and Configuration

`notarius_version` defaults to `v0.8.1`. Configuration remains schema version 5.
Preserve existing build, dependency, path, and owner/group/mode interfaces.
The existing Go selection remains unchanged.

Add `notarius_promptkit_transient_retries: null`, documented and declared as an
optional integer in argument specifications. When non-null, serialize it as
`promptkit.transient_retries`. Include it in the parent-section condition so a
retry-only configuration renders correctly. Null means omit the field; zero
disables additional transient attempts. Do not copy PromptKit's default into
role defaults, add a second retry mechanism, or reinterpret existing module
and validator retry settings.

Keep all existing supported native configuration variables. Preserve caller
mapping/list composition and omission of unset optional settings. The role does
not resolve, inspect, or rewrite caller-owned profile or overlay files.

### Overlay Migration Guidance

Document `--config-overlay` and the conventional `overlays/` directory for
operators invoking the new application. The old `--config-profile` and ConfigKit
`profiles/` lookup no longer work. This does not rename PromptKit LLM-profile
sources: `notarius_promptkit_profile_dir`, `notarius_promptkit_profile_file`,
pipeline `llm_profile`, and `--llm-profile` retain their separate meanings.

Caller-owned configuration overlay files must be migrated by their owner. In
this workspace the D&D suite owns its testing overlay, so that migration belongs
to final integration together with Narratio's new selector. Do not add generic
file-moving tasks or broaden this feature to fix the old suite in place.

### Retry and Checkpoint Compatibility

Explain that transport retries are additional attempts per generation and are
separate from pipeline/validator retries. Omission inherits upstream behavior;
operators may explicitly select zero. Later suite planning will review combined
retry and timeout budgets rather than copying old values mechanically.

Document v0.8.1's changed profile-source checkpoint identity: old matching
checkpoint identities are not reused, while source-keyed chunk plans and
published output are unaffected. Leave cache lifecycle with Notarius and do not
delete data or force Narratio stages as part of installing the role.

## Repository Ownership

- `ansible-role-notarius`: version default, optional retry field, argument
  specification, template, documentation, and repository-local tests.
- Workspace: feature roadmap, staged plan, progress, and independent review.
- Notarius application: read-only tagged configuration/release contracts.
- Pipeline, collection, consumer, other roles, and assets remain unchanged.

## Constraints and Settled Decisions

Follow the [Ansible house style](../../ansible.md),
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
[upgrade sequence](../application-upgrade-sequence.md). Use v0.8.1's contract,
including the intervening v0.8.0 migration notes, not assumptions from a newer
application checkout.

Retain meaningful tests that explicitly install v0.7.0 to prove caller-selected
version behavior. Leave the new retry field unset in those older-version cases;
do not change them merely because the role default advances.

## Simplest Viable Implementation

Update the application version and add one optional variable, argument-spec
entry, and conditional template field. Extend the existing integration fixture
with explicit retry zero and native configuration inspection. No new production
tasks, state probes, compatibility framework, or role-managed assets are needed.

## Rationale and Alternatives

The role manages persistent configuration; application invocation owns overlay
selection. Adding an overlay-selection variable or file-migration tasks here
would confuse those responsibilities. Documenting the breaking invocation
change and coordinating it later preserves independently usable roles and the
existing suite compatibility set.

## Acceptance Criteria

- The default role installs v0.8.1, and native offline validation accepts the
  baseline and representative managed configurations.
- Null retry selection is omitted; explicitly supplied zero is rendered and
  visible through native effective-configuration inspection. A retry-only
  configuration produces its enclosing PromptKit section.
- Existing useful coverage for native import/pipeline composition, profile
  configuration, cache settings, selected application version, and supplied Go
  executable remains valid. Do not add a comprehensive upstream schema matrix.
- Immediate repeat convergence reports no changes. Tests assert supplied values
  and role outcomes, not today's version/catalog defaults or module postconditions.
- Documentation accurately distinguishes configuration overlays from LLM
  profiles and describes retry/checkpoint upgrade consequences.
- Syntax/lint and repository integration checks pass without live provider
  calls or operational-host access.
- Suite, collection, and consumer pins stay unchanged; the reviewed standalone
  revision is recorded for final integration.

## Dependencies and Follow-up Work

Implementation and independent review are complete. Git history preserves the
completed staged plan. Narratio v3 standalone adoption is next. Final integration
owns the coordinated overlay/credential/configuration migration and public suite
dependency updates. No open product decision is required for this narrow scope.

## Implementation Evidence

- Standalone role commits: `b1b922c` (v0.8.1 default and optional retry
  interface), `380b6a3` (integration coverage), and `6aef48b` (upgrade
  guidance). No production tasks or suite dependencies changed.
- Syntax check and production-profile lint passed. `bash -n` and the local
  integration harness passed with native offline configuration validation,
  rendered/effective retry checks, older-version and supplied-Go behavior,
  import and pipeline composition, and clean immediate repeats. Role and
  workspace whitespace checks passed.
- Independent review of all three role commits found no required remediation
  or unjustified strengthening of requirements. Syntax, production-profile
  lint, shell syntax, whitespace checks, and installed v0.8.1 native
  configuration validation passed again during review. The review used the
  recorded successful integration run rather than rerunning its host-mutating
  scenarios. No remediation document was changed.
- Reviewed standalone revision: `6aef48b`. Narratio adoption and coordinated
  suite migration remain separate follow-up work; suite pins are unchanged.

## Upstream References

- [v0.8.1 configuration](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md)
- [v0.8.0 migration notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
- [v0.8.1 release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md)