156 lines
7.7 KiB
Markdown
156 lines
7.7 KiB
Markdown
# Feature 0020: Adopt Notarius v0.8.1 in the Standalone Role
|
|
|
|
Status: ready
|
|
|
|
## 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
|
|
|
|
The roadmap is approved; execution is defined in the
|
|
[implementation plan](../implementation.md). Narratio v3 standalone adoption
|
|
follows independent review and closeout. Final integration
|
|
owns the coordinated overlay/credential/configuration migration and public suite
|
|
dependency updates. No open product decision is required for this narrow scope.
|
|
|
|
## 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)
|