ansible-role-notarius/README.md

# Ansible Role: Notarius

Installs and configures [Notarius](https://gitea.maximumdirect.net/eric/notarius)
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
facts and uses privilege escalation only for dependency installation and
root-owned application state.

## Variables

```yaml
notarius_version: v0.8.1
notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
notarius_source_dir: /usr/local/src/notarius
notarius_binary_path: /usr/local/bin/notarius
notarius_manage_build_dependencies: true
notarius_go_snap_channel: 1.26/stable
notarius_go_binary: /snap/bin/go
notarius_config_path: /usr/local/etc/notarius/config.yml
notarius_config_owner: root
notarius_config_group: root
notarius_config_directory_mode: "0755"
notarius_config_file_mode: "0644"
notarius_config_version: 5
notarius_promptkit_profile_dir: null
notarius_promptkit_profile_file: null
notarius_promptkit_transient_retries: null
notarius_promptkit_local_backend_endpoint: null
notarius_promptkit_local_backend_concurrency_limit: null
notarius_configkit_imports: null
notarius_pipelines: null
notarius_concurrency_total_llm: null
notarius_concurrency_stage_workers_extract: null
notarius_output_directory: null
notarius_cache_chunk_plans_mode: null
notarius_cache_chunk_plans_directory: null
notarius_cache_checkpoints_enabled: null
notarius_cache_checkpoints_directory: null
notarius_debug_directory: null
```

When `notarius_manage_build_dependencies` is `false`, Git and the executable
selected by `notarius_go_binary` must already be available. Otherwise, the role
installs Git with APT and the classic Go Snap from `notarius_go_snap_channel`.
It checks out `notarius_version` authoritatively, builds `./cmd/notarius`
directly to `notarius_binary_path`, and rebuilds only when that checkout changes
or the binary is absent. The source tree is recursively owned by `root:root`;
the binary is `root:root` mode `0755`.

Configuration variables map directly to Notarius's versioned YAML fields.
Every optional value defaults to `null`, so it and any empty parent section are
omitted and Notarius retains ownership of its built-in defaults. The role always
emits `notarius_config_version` as `version`. It manages
`notarius_config_path | dirname` and the resulting file with
`notarius_config_owner`, `notarius_config_group`,
`notarius_config_directory_mode`, and `notarius_config_file_mode`. The
standalone defaults are `root:root`, directory mode `0755`, and file mode
`0644`; composing roles may override this generic configuration interface.
`notarius_pipelines` is the native mapping supplied by the caller; the role
does not merge or rewrite it. For example, inventory can compose fragments in
the ordinary way:

```yaml
notarius_pipelines: "{{ notarius_pipeline_group_one | combine(notarius_pipeline_group_two) }}"
```

`notarius_configkit_imports` is the complete native ConfigKit import list. It
is caller-owned composition input: the role renders it into the root document
but does not create or merge imported fragments. Relative import paths resolve
from the managed root configuration directory.

PromptKit profile values identify profile sources or a local backend endpoint;
they never contain credentials. Supply any credential environment variables
outside this role.

`notarius_promptkit_transient_retries` renders
`promptkit.transient_retries` when set. The null default omits it so Notarius
retains its native retry behavior; integer `0` disables additional eligible
transient transport attempts. These are additional attempts per generation for
eligible transient provider failures, separate from pipeline and validator
retries. Review combined retry and timeout budgets for a deployment rather
than treating these settings as interchangeable. See the tagged
[v0.8.0 migration notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
and [v0.8.1 configuration reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md).

## Upgrading to v0.8.1

Notarius v0.8.0 replaced ConfigKit configuration selection via
`--config-profile` and `profiles/<name>.yml` with `--config-overlay` and
`overlays/<name>.yml`. Callers own their overlay files and application
invocations; this role does not migrate files or select an overlay. The D&D
suite's testing file and Narratio's downstream selector will be migrated
together during coordinated suite integration, not by this standalone role.

Configuration overlays are distinct from PromptKit LLM profiles.
`notarius_promptkit_profile_dir` and `notarius_promptkit_profile_file` still
select LLM-profile sources, while pipeline `llm_profile` and `--llm-profile`
still select an LLM profile. Those names and meanings are unchanged.

The v0.8.1 PromptKit dependency refresh changes profile-source checkpoint
identity, so old checkpoints with the previous identity are not reused.
Source-keyed chunk plans and published output are unaffected. Installing the
role does not delete caches or force processing stages; see the tagged
[v0.8.1 release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md).

## Example

```yaml
- hosts: notarius_hosts
  roles:
    - role: ansible-role-notarius
```

## Validation

The repository-local integration suite installs its pinned collection, runs
syntax checking and production-profile lint, and exercises the default CLI and
native configuration validation before requiring clean repeated convergence.
It verifies an explicitly selected Notarius release, combines missing-binary
recovery with a caller-supplied Go executable while dependency management is
disabled, and checks null omission and explicit zero transport retries in
rendered and effective configuration. A representative configuration also
covers intentional falsey values, caller-side pipeline composition through a
test-owned ConfigKit import, and native validation and inspection. It mutates
only the managed source, binary, configuration, a test-owned imported fragment,
and a private temporary directory, then restores the default deployment during
cleanup.

```sh
tests/integration
```