10 KiB
Feature 0019: Adopt Audita v2.0.1 in the Standalone Role
Status: done
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.
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, testing house style, MVP roadmap, and upgrade sequence. 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
Git history preserves the completed staged plan. 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.
Completion and Review Evidence
Completed in role commits 6137ff2, 52f67fe, and c3dd59f. Implementation
reported passing integration tests with native v2 validation, offline profile
inspection, mapping composition, omission, numeric seconds, falsey values,
build/recovery coverage, and clean repeated convergence.
Independent review found no code-quality issues, implementation gaps, or unnecessarily strengthened requirements needing remediation. Independent Ansible syntax, production-profile lint, shell syntax, whitespace, and focused template checks passed. The review used recorded native/integration results without rerunning the host-mutating suite.
No production tasks were added. Profile files remain caller-owned, and suite, collection, and consumer pins remain unchanged. No operational deployment or paid inference was performed as part of this review.