ansible-workspace-dnd/docs/roadmap/features/0003-notarius-source-installation-and-configuration.md

# Feature 0003: Notarius Source Installation and Configuration

Status: done

## Summary

Provide a small, independently usable `rakestraw.notarius` role that installs
Notarius from a pinned Git tag, builds its executable on the managed host, and
manages its versioned YAML configuration. Reuse the established module-driven
application-role pattern while leaving D&D pipeline policy to the suite-level
role.

## Problem or Opportunity

At feature selection, the `ansible-role-notarius` repository contained only
its initial placeholder files. Notarius is one of the five required pipeline
applications and needed an independently usable installation and
native-configuration role before the suite role could compose it with
Seriatim, Audita, and the remaining applications.

Seriatim and Audita have established the preferred source-build architecture.
Notarius can use the same concise task flow, with only its native configuration
and build contract differing.

## Governing Policies

- [The Ansible house style](../../ansible.md) governs the role implementation,
  its public configuration variables, and its template behavior.
- [The testing house style](../../testing.md) governs repository-local
  validation. Tests exercise role-owned behavior through the public interface
  without snapshotting current defaults, tracing task implementation, or
  rechecking postconditions owned by trusted Ansible modules.

## Scope

- Implement `ansible-role-notarius` as a conventional standalone role.
- Support Ubuntu 26.04 on native `amd64` and `arm64` hosts.
- Install Git and the official Go Snap with classic confinement when build
  dependency management is enabled.
- Default the Go Snap channel to `1.26/stable`.
- Check out immutable Notarius tag `v0.6.0` by default under the root-owned
  path `/usr/local/src/notarius`.
- Build Notarius with its upstream release build contract and install the
  native executable at `/usr/local/bin/notarius`.
- Rebuild when the Git checkout changes or the binary is absent.
- Converge the installed binary to `root:root` ownership and mode `0755`.
- Manage a versioned Notarius YAML configuration at
  `/usr/local/etc/notarius/config.yml`, owned by `root:root` with mode `0644`.
- Default the managed configuration to the minimal valid mapping
  `{"version": 4}`, allowing Notarius's built-in defaults to govern behavior.
- Expose native configuration through field-specific role variables. Give the
  required schema version a concrete default and make every optional setting
  nullable so omitted settings remain owned by Notarius.
- Keep defaults, argument specifications, README, metadata, dependency
  declaration, and focused local tests consistent with this contract.

## Non-goals

- A D&D pipeline definition, module selection, LLM profile, concurrency
  policy, output paths, cache policy, or other suite-specific configuration.
- A raw mapping for the complete configuration document, a template override,
  or competing configuration interfaces.
- Role defaults copied from Notarius merely to reproduce the application's
  built-in defaults in YAML.
- Decomposing the open-ended `pipelines` map into role variables for every
  possible pipeline, step, lane, binding, validator, option, or reference.
- API keys, secret values, environment files, or another secret-delivery
  mechanism.
- PromptKit profiles or other externally maintained prompt content.
- Creation or management of the `narratio` account, operator groups, campaign
  data, runtime output, debug, cache, checkpoint, or transcript directories.
- Installation or configuration of another pipeline application.
- Services, scheduling, removal behavior, or pipeline composition.
- Prebuilt release artifacts or cross-compilation.
- Production execution of Notarius to validate the build or configuration.
- Detection of out-of-band binary modification, compiler changes, or fixed
  build-command changes.
- Build fingerprints, checksums, sidecar state, staged replacement, manual Git
  cleanup, or special recovery for malformed or adversarial host state.
- A shared build helper role or dedicated platform-matrix infrastructure.

## Target End State

On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with defaults
installs or confirms Git and Go, checks out Notarius `v0.6.0` at
`/usr/local/src/notarius`, builds `/usr/local/bin/notarius`, and writes
`/usr/local/etc/notarius/config.yml`. Source and installed files have the
stated root ownership and permissions, and the configuration contains
`version: 4`.

When a caller sets an optional configuration variable, the corresponding
native field appears in the correct YAML section. Null fields are absent, as
are parent sections with no selected descendants. Explicit false, zero, empty
string, empty collection, and other non-null values are rendered and left to
Notarius's native validation. `notarius_pipelines` represents the native
open-ended `pipelines` field as one mapping rather than attempting to mirror
its extensible internal schema in Ansible variables. Callers may define
pipeline-map fragments in separate inventory files and compose them into the
final value with ordinary Ansible/Jinja expressions.

An immediate second application reports no changes. A changed Git checkout or
missing binary causes one build; configuration changes converge independently
through the ordinary `ansible.builtin.template` operation.

Repository-local tests exercise the real role through its public variables.
They use the default invocation only as a smoke test, explicitly select
immutable `v0.5.0` to prove version selection, exercise missing-binary recovery
with a caller-supplied Go executable, and render one representative
configuration covering null omission, intentional falsey values, and
caller-side pipeline composition. Application-native commands verify the
selected release and configuration validity, and immediate repeated
applications verify convergence.

## Repository Ownership

- `ansible-role-notarius` owns the role implementation, public interface,
  configuration serialization, metadata, dependency declaration, README, and
  repository-local validation.
- `../notarius` is the read-only authority for build, CLI, and configuration
  contracts.
- `rakestraw-ansible` is a read-only style and deployment-policy reference.
- `ansible-role-dnd-pipeline` will later own the D&D-specific configuration
  supplied through the standalone role's field-specific variables.
- `ansible-workspace-dnd` owns this roadmap, the eventual staged plan, and
  aggregate status.
- All other repositories remain unchanged.

## Constraints and Settled Decisions

- The selected release is tag `v0.6.0`, which resolves to commit
  `77ae132e5609916da40dcd4fcc749c000a63cbac`.
- The release declares Go 1.25.5. The suite-standard Go Snap channel remains
  `1.26/stable` and satisfies that requirement.
- The upstream release build uses package `./cmd/notarius`, `CGO_ENABLED=0`,
  `GOWORK=off`, `GOTOOLCHAIN=local`, `-trimpath`, and linker flag
  `-X gitea.maximumdirect.net/eric/notarius/internal/buildinfo.Override=<version>`.
- `notarius --version` prints `notarius <version>`. This is test evidence, not
  an additional production rebuild trigger or post-build convergence task.
- Notarius configuration schema version 4 explicitly supports a document
  containing only `version: 4`, with omitted values supplied by application
  defaults.
- `notarius_config_version` names the schema version so `notarius_version`
  remains unambiguously the selected application release.
- Optional configuration variables are declared with YAML null defaults.
  Template conditions use `is not none`, and parent mappings are emitted only
  when at least one descendant is non-null.
- The native `pipelines` field is exposed as the nullable
  `notarius_pipelines` mapping. It is one field-specific variable, not a raw
  mapping for the complete document; the role serializes its value without
  defining a parallel schema for pipeline internals.
- Pipeline composition belongs to the caller. For example, inventory may
  define `notarius_pipeline_group_one` and `notarius_pipeline_group_two` as
  mappings and set `notarius_pipelines` to
  `{{ notarius_pipeline_group_one | combine(notarius_pipeline_group_two) }}`.
  The role accepts and renders the resulting mapping without its own merge or
  precedence mechanism.
- Strings and mappings are serialized with Ansible or Jinja filters rather
  than hand-written YAML quoting.
- `notarius config validate --config <path>` validates a managed configuration
  without requiring a pipeline selection. It is used only by tests.
- Configuration discovery uses an explicit CLI path, then `NOTARIUS_CONFIG`,
  then `/usr/local/etc/notarius/config.yml`; the role manages the installed
  default path.
- Configuration contains no secrets by default. Consumers arrange any secret
  environment variables outside this feature.
- Tasks that install dependencies or manage root-owned state use task-level
  `become: true`.
- `community.general` supplies Snap management and is pinned to version
  `13.3.0` in the role's collection requirements.
- Tag `v0.5.0` remains buildable with the same Go requirement, package, linker
  symbol, and configuration schema and is the explicit immutable release used
  for focused native version-selection coverage.

## Fixed Public Interface

Provide these installation variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `notarius_version` | `v0.6.0` | Git revision and release value supplied to the build |
| `notarius_repository_url` | `https://gitea.maximumdirect.net/eric/notarius.git` | Source repository |
| `notarius_source_dir` | `/usr/local/src/notarius` | Managed source checkout |
| `notarius_binary_path` | `/usr/local/bin/notarius` | Installed executable |
| `notarius_manage_build_dependencies` | `true` | Whether to install Git and Go |
| `notarius_go_snap_channel` | `1.26/stable` | Go Snap channel |
| `notarius_go_binary` | `/snap/bin/go` | Go executable used for the build |
| `notarius_config_path` | `/usr/local/etc/notarius/config.yml` | Managed configuration file |

Provide these configuration variables:

| Variable | Default | Native field |
| --- | --- | --- |
| `notarius_config_version` | `4` | `version` |
| `notarius_promptkit_profile_dir` | `null` | `promptkit.profile_dir` |
| `notarius_promptkit_profile_file` | `null` | `promptkit.profile_file` |
| `notarius_promptkit_local_backend_endpoint` | `null` | `promptkit.local_backend.endpoint` |
| `notarius_promptkit_local_backend_concurrency_limit` | `null` | `promptkit.local_backend.concurrency_limit` |
| `notarius_pipelines` | `null` | `pipelines` |
| `notarius_concurrency_total_llm` | `null` | `concurrency.total_llm` |
| `notarius_concurrency_stage_workers_extract` | `null` | `concurrency.stage_workers.extract` |
| `notarius_output_directory` | `null` | `output.directory` |
| `notarius_cache_chunk_plans_mode` | `null` | `cache.chunk_plans.mode` |
| `notarius_cache_chunk_plans_directory` | `null` | `cache.chunk_plans.directory` |
| `notarius_cache_checkpoints_enabled` | `null` | `cache.checkpoints.enabled` |
| `notarius_cache_checkpoints_directory` | `null` | `cache.checkpoints.directory` |
| `notarius_debug_directory` | `null` | `debug.directory` |

The package, build flags, linker symbol, environment values, file ownership,
and modes are fixed implementation details. The selected version is both the
Git revision and the value supplied to the upstream linker flag.

Argument specifications type each value according to its native shape. The
role does not reproduce semantic relationships such as the mutual exclusion
of PromptKit profile sources or the requirement for a local-backend endpoint;
Notarius owns those constraints. The `notarius_pipelines` value is a mapping
whose nested structure is governed by Notarius's versioned configuration
contract.

## Simplest Viable Implementation

The expected implementation is approximately nine ordinary tasks in one
readable task file:

1. Assert Ubuntu 26.04 and architecture `x86_64` or `aarch64`.
2. Install Git with `ansible.builtin.apt`, including
   `cache_valid_time: 3600`, when dependency management is enabled.
3. Install the classic Go Snap from `notarius_go_snap_channel` with
   `community.general.snap` when dependency management is enabled.
4. Create source, binary, and configuration parent directories with one
   `ansible.builtin.file` loop.
5. Check out `notarius_version` with `ansible.builtin.git`, `force: true`, and
   register the module result.
6. Inspect whether `notarius_binary_path` exists with
   `ansible.builtin.stat`.
7. Run the upstream Go build through `notarius_go_binary` when the checkout
   changed or the binary is absent.
8. Converge recursive source ownership and binary ownership and mode with one
   item-driven `ansible.builtin.file` loop.
9. Render the field-specific configuration with one
   `ansible.builtin.template` task, conditionally emitting optional fields and
   parent sections at `notarius_config_path`.

Apply task-level privilege escalation only where required. Use `argv` for the
build command and put its two conditions directly on the build task. Do not
add a rebuild fact, handler, handler flush, executable discovery, compiler or
version interrogation, configuration assembly facts, preliminary
configuration probes, or post-operation validation to production tasks.

## Rationale and Alternatives

Notarius has the same installation mechanics as the completed Seriatim and
Audita roles: declarative dependency and checkout management surrounding one
imperative build command. Binary existence is the only state probe Ansible
needs because it controls whether that command must run.

Field-specific variables are the ordinary ergonomic interface for inventory
and composing roles. Nullable defaults expose and type that interface without
freezing Notarius's built-in defaults into Ansible. Conditional rendering
preserves the distinction between omission and an intentionally falsey value.

The pipeline definitions are the deliberate exception to leaf-level
variables. `pipelines` is itself an open-ended map whose nested keys depend on
registered modules and evolve with the application's native schema. Exposing
that native field as one nullable mapping keeps the interface practical while
still avoiding a raw complete-document mapping or merge semantics. The suite
role can later supply its maintained D&D pipeline through
`notarius_pipelines` and supply operating policy through the other variables.

This boundary also supports modular inventory. A consumer can keep one or
more pipeline mappings in separate `host_vars`, `group_vars`, or included
variable files and combine them when assigning `notarius_pipelines`. Because
the native value is a mapping keyed by pipeline ID, dictionary composition
uses Ansible's `combine` filter; list concatenation with `+` applies only to
list-valued data. The role receives the already composed native mapping and
does not need custom loading, merging, or precedence behavior.

Leaving optional variables undefined would produce the same minimal file but
would weaken interface documentation and argument validation. Section-level
dictionaries would be less ergonomic for ordinary inventory values. A raw
complete configuration mapping would force consumers to replace the required
version and unrelated sections together and would conflict with the workspace
convention of one field-specific interface.

Managing `/usr/local/etc/notarius/config.yml` follows the application's own
configuration discovery contract and aligns locally installed software with
its configuration.

## Acceptance Criteria

### Required Role Behavior

- The role rejects unsupported distributions, Ubuntu releases, and
  architectures before modifying application state.
- On a supported host, the role installs the selected Notarius source release
  with its upstream build contract. The default selection for this feature is
  tag `v0.6.0`, resolving to commit
  `77ae132e5609916da40dcd4fcc749c000a63cbac`.
- The role converges the source tree, binary, and configuration to the paths,
  ownership, and modes defined above using the responsible Ansible modules.
- The default template renders the minimal valid configuration containing the
  required schema version and leaves optional policy to Notarius.
- A non-null optional variable renders its corresponding native field. Null
  values and parent sections without a selected descendant are omitted;
  intentional falsey values are preserved.
- Independently defined inventory mappings can be combined into
  `notarius_pipelines`, and the resulting pipeline IDs and definitions are
  rendered without structural rewriting by the role.
- A changed checkout or missing binary causes the imperative build to run. An
  immediate repeated application with unchanged inputs reports no changes.
- Dependency opt-out accepts a caller-supplied `notarius_go_binary`.
- Tasks requiring elevated access use task-level privilege escalation, so the
  role does not require play-level escalation.
- Defaults, argument specifications, template behavior, and documentation
  remain aligned with the public interface without introducing a parallel raw
  configuration or template-override interface.
- Production tasks contain no role-private build state, redundant probes,
  application self-tests, or other behavior outside the selected invariants.
- No repository other than `ansible-role-notarius` and the workspace control
  repository is modified.

### Required Validation

- Syntax checking and production-profile ansible-lint pass.
- A default invocation provides a smoke test through the installed CLI and
  native configuration validator, followed immediately by a role application
  reporting no changes. The test does not assert that the role's current
  default release or complete default document remains unchanged.
- A focused version-selection case explicitly requests immutable tag `v0.5.0`
  and verifies that the installed CLI reports `notarius v0.5.0`.
- One recovery case removes the binary, disables dependency management,
  supplies a caller-selected Go executable, confirms that executable is used,
  and finishes with a clean repeated application.
- One representative configuration case verifies selected rendered values,
  selected omissions, intentional falsey values, and caller-side composition
  of two pipeline mappings. The native Notarius validator accepts the result,
  and an immediate repeated application reports no changes.
- Tests do not assert task names or order, individual task results, exact
  current defaults, complete configuration snapshots, public-variable counts,
  trusted-module file or package postconditions, or an exhaustive negative
  platform matrix.

## Dependencies and Follow-up Work

The managed host requires access to the Notarius Git repository, Ubuntu Snap
infrastructure, and Go module sources. Actual transcript processing also needs
a configured pipeline, input artifacts, PromptKit assets and endpoints, and
secret environment variables; those belong to consumers or later suite-level
work.

The role was implemented in `ansible-role-notarius` commits `287fc4a` and
`733a194`, then finalized by remediation commit `eb4f511`. Its complete
integration suite passes. The pipeline role can now supply its D&D definitions
through `notarius_pipelines` and select the other field-specific values.

## Potential Future Hardening

- Build into a temporary path before replacing the installed executable.
- Verify source signatures or release checksums.
- Detect compiler, build-command, or out-of-band binary changes.
- Validate configuration during production convergence.
- Manage a dedicated runtime account, secret environment, state paths,
  service, or schedule if later operating requirements select them.
- Add broader Ubuntu release and architecture test coverage only if future
  platform behavior warrants it.