Plan the standalone Audita version 2 upgrade
This commit is contained in:
182
docs/roadmap/features/0019-audita-v2-adoption.md
Normal file
182
docs/roadmap/features/0019-audita-v2-adoption.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Feature 0019: Adopt Audita v2.0.1 in the Standalone Role
|
||||
|
||||
Status: ready
|
||||
|
||||
## Summary
|
||||
|
||||
Replace the standalone Audita role's version-1 configuration interface with
|
||||
Audita v2.0.1's native interface. Keep provider and D&D policy outside the
|
||||
generic role. This is the second feature in the agreed
|
||||
[application upgrade sequence](../application-upgrade-sequence.md).
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
The role currently installs Audita v0.9.1 and renders version-1 configuration.
|
||||
Audita v2 requires version-2 YAML, named backends, and selected PromptKit
|
||||
profiles. Old per-role endpoint/model/credential/concurrency settings no longer
|
||||
apply. A version-only update would produce an unusable deployment.
|
||||
|
||||
Unlike the previous minimal configuration, a valid v2 configuration requires
|
||||
at least one backend and a proposal profile whose file exists. The generic role
|
||||
must not invent a provider, endpoint, model, or credential to meet that contract.
|
||||
The caller-input boundary is settled below.
|
||||
|
||||
## Scope
|
||||
|
||||
- Default to Audita v2.0.1 and configuration version 2.
|
||||
- Replace retired public configuration variables with native v2 settings.
|
||||
- Preserve still-supported domain controls and inventory composition.
|
||||
- Document the breaking role-variable migration and caller prerequisites.
|
||||
- Adapt offline integration tests to real v2 configuration/profile fixtures.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Updating pipeline, collection, or consumer application/dependency pins.
|
||||
- Choosing D&D models, endpoints, credentials, concurrency, or retry budgets.
|
||||
- Compatibility shims, automatic v1 conversion, or a dual-schema template.
|
||||
- Live inference, operational deployment, report ingestion, service management,
|
||||
or runtime configuration validation tasks.
|
||||
- Imports: Audita deliberately disables ConfigKit imports. Do not add an import
|
||||
variable merely because other applications expose one.
|
||||
- Automatically provisioning secret values or selecting runtime overlays.
|
||||
|
||||
## Target End State
|
||||
|
||||
### Installation and Schema
|
||||
|
||||
`audita_version` defaults to `v2.0.1`; `audita_config_version` defaults to `2`.
|
||||
Retain the existing source checkout, conditional Go build, dependency management,
|
||||
configuration location, and owner/group/mode interfaces. Go 1.26 remains suitable.
|
||||
The role renders v2 only; selecting an older application does not translate its
|
||||
configuration. Operators needing v1 retain the previous role revision.
|
||||
|
||||
### Public Configuration Interface
|
||||
|
||||
Use these field-specific variables; optional settings default to null and are
|
||||
omitted, allowing Audita to own defaults. Serialize native values and preserve
|
||||
intentional zero, false, empty strings, and empty collections where supported.
|
||||
|
||||
| Role variable | Native field | Ownership |
|
||||
| --- | --- | --- |
|
||||
| `audita_profiles_dir` | `profiles_dir` | Optional caller profile location |
|
||||
| `audita_backends` | `backends` | Caller-supplied native mapping |
|
||||
| `audita_llm_proposal_profile` | `llm.proposal_profile` | Caller-selected required profile |
|
||||
| `audita_llm_validation_profile` | `llm.validation_profile` | Optional; omission inherits proposal |
|
||||
| `audita_llm_transient_retries` | `llm.transient_retries` | Optional native retry budget |
|
||||
| `audita_llm_repair_attempts` | `llm.repair_attempts` | Optional native repair budget |
|
||||
| `audita_llm_operation_timeout` | `llm.operation_timeout` | Optional duration string |
|
||||
| `audita_validation_max_prompt_tokens` | `validation.max_prompt_tokens` | Optional batching control |
|
||||
| `audita_reporting_enabled` | `reporting.enabled` | Optional report policy |
|
||||
| `audita_reporting_stdout_dir` | `reporting.stdout_dir` | Optional report destination |
|
||||
| `audita_diagnostics_debug` | `diagnostics.debug` | Optional debug policy |
|
||||
|
||||
Retain existing variables for modules, output schema, chunking, normalization,
|
||||
thresholds, context description, and diagnostics work directory. Normalization
|
||||
gap/duration fields now represent numeric seconds, not duration strings.
|
||||
Argument specifications must accept the native integer/fractional values without
|
||||
turning them into quoted strings in YAML. Do not add a duration-conversion layer.
|
||||
|
||||
Remove the old `audita_llm_{proposal,validation}_{base_url,model,api_key_env,timeout,max_retries}`,
|
||||
`audita_concurrency_{total_llm,proposal_llm,validation_llm}`, and
|
||||
`audita_diagnostics_retention` interfaces from defaults, templates, argument
|
||||
specifications, and current examples. Document their replacements rather than
|
||||
silently interpreting them under different semantics or adding deprecation probes.
|
||||
|
||||
The backend mapping carries endpoint, credential reference, concurrency, and
|
||||
queue capacity using Audita's schema. Inventory can compose it with ordinary
|
||||
Jinja expressions. Credential values stay outside the role; every surviving
|
||||
backend reference must be available when Audita loads configuration, even when
|
||||
that backend is not selected. Do not introduce separate per-role secret variables.
|
||||
|
||||
Null role variables mean omission, not literal YAML null. In particular, omit
|
||||
an unset validation profile so Audita can inherit the proposal selection.
|
||||
Backend mapping values retain native semantics, including a null credential.
|
||||
|
||||
### Profile and Overlay Ownership
|
||||
|
||||
Callers provide `audita_backends` and `audita_llm_proposal_profile`; neither has
|
||||
a fabricated concrete default. Callers also deploy the selected profile files
|
||||
before invoking Audita. `audita_profiles_dir` may be supplied or omitted to use
|
||||
Audita's conventional sibling `profiles/` directory. Keep profile documents and
|
||||
ConfigKit `overlays/` content caller-owned in this feature.
|
||||
|
||||
The later suite feature will own its D&D profile assets and coordinate their
|
||||
deployment with Narratio's new external Audita configuration contract. The role
|
||||
does not start processing or validate file availability during convergence.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
- `ansible-role-audita`: generic installation/configuration interface, migration
|
||||
documentation, and local tests.
|
||||
- Workspace: roadmap, active plan, progress, and review evidence.
|
||||
- Audita application: read-only tagged schema, migration, and profile contracts.
|
||||
- Other applications/roles, assets, pipeline, collection, and consumer: 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). The suite continues to
|
||||
use its old compatible role/application set until final integration; Narratio v2
|
||||
must not be accidentally paired with Audita v2 through a changed suite pin.
|
||||
|
||||
Old timeouts and retries do not map one-to-one to profile per-attempt timeouts,
|
||||
logical-operation deadlines, transport retries, and structural repair. Expose
|
||||
native controls without choosing replacement tuning for the D&D suite here.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
Update the version/schema defaults and replace the single configuration template's
|
||||
retired sections with native v2 sections. Align argument specifications and the
|
||||
README. Keep ordinary file/template/source/build tasks. Use the existing test
|
||||
harness with caller-owned local backend/profile fixtures; add no state assembly,
|
||||
profile resolver, migration command, or production probe.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The role installs v2.0.1 and renders native v2 configuration from supplied
|
||||
backend/profile choices and optional settings.
|
||||
- Native offline validation and effective-settings/profile inspection accept
|
||||
representative configuration with an externally supplied profile and local
|
||||
fixture endpoint; no provider request is needed.
|
||||
- Tests cover supplied mapping composition, omission/inherited validation
|
||||
selection, representative numeric seconds, and meaningful zero/false values.
|
||||
Avoid a comprehensive schema matrix or assertions of current upstream defaults.
|
||||
- Existing useful build and clean-repeat coverage remains. Immediate repeated
|
||||
role convergence reports no changes; do not test module postconditions.
|
||||
- Documentation explains required caller inputs and the breaking variable/schema
|
||||
migration, linking Audita for full field and report semantics.
|
||||
- No suite, collection, or consumer pins change. Completion records the reviewed
|
||||
standalone role revision for the final integration feature.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
Native backend mappings and named profiles preserve Audita's ownership instead
|
||||
of reproducing per-role endpoint/model settings in Ansible. A dual-schema role
|
||||
would add maintenance and ambiguity without a selected requirement; retaining
|
||||
the previous role revision is the simpler boundary for old deployments.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
The caller-input decision is approved. The staged implementation plan is at
|
||||
[implementation.md](../implementation.md). After review and closeout, Notarius adoption is
|
||||
next. D&D backend/profile assets, tuning migration, testing overlays, credential
|
||||
lists, and coordinated deployment belong to the later integration feature.
|
||||
|
||||
## Settled Caller-Input Decision
|
||||
|
||||
The user approved required `audita_backends` and `audita_llm_proposal_profile`
|
||||
inputs through the ordinary role argument interface, with caller-owned profile
|
||||
files. Do not give these variables null or fabricated defaults. A no-input role
|
||||
invocation is no longer valid; examples and tests supply explicit choices.
|
||||
Role-managed profile definitions are not part of this feature.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
|
||||
## Upstream References
|
||||
|
||||
- [v2.0.1 configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
|
||||
- [v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
|
||||
- [v2.0.1 release](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/releases/v2.0.1.md)
|
||||
Reference in New Issue
Block a user