ansible-role-audita/README.md

# Ansible Role: Audita

Installs and configures [Audita](https://gitea.maximumdirect.net/eric/audita)
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
facts and uses privilege escalation on tasks that install dependencies or
manage root-owned application state.

## Variables

Every invocation requires caller-supplied `audita_backends` and
`audita_llm_proposal_profile`. Neither has a role default.

```yaml
audita_version: v2.0.1
audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
audita_source_dir: /usr/local/src/audita
audita_binary_path: /usr/local/bin/audita
audita_manage_build_dependencies: true
audita_go_snap_channel: 1.26/stable
audita_go_binary: /snap/bin/go
audita_config_path: /usr/local/etc/audita/config.yml
audita_config_owner: root
audita_config_group: root
audita_config_directory_mode: "0755"
audita_config_file_mode: "0644"
audita_config_version: 2
audita_profiles_dir: null
audita_pipeline_modules: null
audita_output_schema: null
audita_llm_validation_profile: null
audita_llm_transient_retries: null
audita_llm_repair_attempts: null
audita_llm_operation_timeout: null
audita_validation_max_prompt_tokens: null
audita_chunking_target_sections: null
audita_chunking_max_section_tokens: null
audita_chunking_min_section_tokens: null
audita_normalization_max_segment_gap: null
audita_normalization_ellipsis_gap: null
audita_normalization_max_segment_duration: null
audita_normalization_max_segment_tokens: null
audita_thresholds_glossary: null
audita_thresholds_homophones: null
audita_thresholds_spoken_word: null
audita_thresholds_grammar: null
audita_context_description: null
audita_reporting_enabled: null
audita_reporting_stdout_dir: null
audita_diagnostics_debug: null
audita_diagnostics_work_dir: null
```

When `audita_manage_build_dependencies` is `false`, Git and the executable
selected by `audita_go_binary` must already be available. Otherwise, the role
installs Git with APT and the classic Go Snap from `audita_go_snap_channel`.

The checkout is authoritative: local source changes are discarded while
selecting `audita_version`. The role builds Audita directly to
`audita_binary_path` using `audita_go_binary`, `CGO_ENABLED=0`, `GOWORK=off`,
`GOTOOLCHAIN=local`, `-trimpath`, and release linker metadata. It rebuilds when
the checkout changes or the binary is absent. The source tree is recursively
owned by `root:root`; the binary is `root:root` mode `0755`.

The configuration variables map directly to Audita's version-2 YAML fields.
`audita_backends` and `audita_llm_proposal_profile` are required caller inputs;
the role has no defaults for them. Callers own the selected PromptKit profile
files. Every optional variable defaults to `null`; null values and their empty
parent sections are omitted, allowing Audita to retain ownership of its built-in
defaults. `audita_config_version` always renders as `version` and defaults to
`2`. The role manages `audita_config_path | dirname` and the resulting file
with the `audita_config_owner`, `audita_config_group`,
`audita_config_directory_mode`, and `audita_config_file_mode` inputs. The
standalone defaults are `root:root`, directory mode `0755`, and file mode
`0644`. Composing roles may override these generic configuration inputs for
their own deployment policy.

Backend `credential` values are explicit environment-variable reference names,
not secret values. Every surviving reference must resolve to a nonempty value
when Audita loads configuration, including references on unselected backends.
An omitted or null credential permits unauthenticated local use. The role does
not supply secret values, start a service, or probe profiles during convergence.

## Migrating from the version-1 role

This revision renders version-2 configuration only. Existing version-1 users
can retain the previous role revision while planning a coordinated migration.
The old fields have no compatibility aliases:

| Previous role inputs | Version-2 destination |
| --- | --- |
| `audita_llm_{proposal,validation}_base_url` | `audita_backends.<id>.endpoint`; both selections may share one backend. |
| `audita_llm_{proposal,validation}_api_key_env` | `audita_backends.<id>.credential`, an explicit environment-variable name. |
| `audita_concurrency_{total_llm,proposal_llm,validation_llm}` | `audita_backends.<id>.concurrency` and optional `queue_capacity`; capacity is shared by roles using that backend. |
| `audita_llm_{proposal,validation}_model` | Model in caller-owned PromptKit profile files, selected by `audita_llm_proposal_profile` and optional `audita_llm_validation_profile`. |
| `audita_llm_{proposal,validation}_timeout` | Per-attempt `timeout_seconds` in profile files; `audita_llm_operation_timeout` separately bounds a logical call. |
| `audita_llm_{proposal,validation}_max_retries` | `audita_llm_transient_retries` and `audita_llm_repair_attempts` are separate native budgets; old values do not map directly. |
| Three `audita_normalization_*` gap/duration values | Same role variables, now numeric seconds rather than duration strings. |
| `audita_diagnostics_retention` | Removed; use `audita_diagnostics_debug` and `audita_diagnostics_work_dir` for v2 debug behavior. Reporting uses `audita_reporting_enabled` and `audita_reporting_stdout_dir`. |

Omitting `audita_llm_validation_profile` lets Audita inherit the proposal
selection. `audita_llm_operation_timeout` is a Go duration string, while
normalization times are numbers. See the tagged
[v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
and [configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
for exact validation and precedence rules.

## Example

Inventory can supply the required choices for a local backend:

```yaml
# host_vars/audita_host.yml (caller-owned)
audita_backends:
  local:
    endpoint: http://127.0.0.1:11434/v1
    credential: null
audita_llm_proposal_profile: local-proposal
```

The caller also supplies `profiles/local-proposal.yaml` beside the managed
configuration, or selects another directory with `audita_profiles_dir`:

```yaml
# profiles/local-proposal.yaml (caller-owned)
id: local-proposal
backend: local
model: replace-with-an-available-local-model
timeout_seconds: 30
```

Choose a model available at the selected endpoint. These profile files must
exist before invoking Audita, but need not exist before applying the role.
The role neither deploys them nor selects a ConfigKit overlay.

```yaml
- hosts: audita_hosts
  roles:
    - role: ansible-role-audita
```

## Validation

The integration driver installs pinned collection dependencies, runs syntax
checking and ansible-lint, and applies the role with local fixture backends and
caller-owned profiles. It checks the temporary configuration with native
`config validate` and the effective settings and profiles views, then requires
clean repeated convergence. It also tests a caller-supplied Go executable with
dependency management disabled after removing the managed binary. The fixture
configuration and sibling `profiles/` directory live under the script's private
temporary root, which cleanup removes. The role still mutates the local managed
source checkout and binary; an existing system configuration is not replaced.
These offline checks do not establish provider connectivity, runtime report
behavior, or compatibility with the unchanged D&D suite:

```sh
tests/integration
```