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

# Feature 0003: Notarius Source Installation and Configuration

Status: proposed

Planning note: the installation decisions are ready for review, but the
configuration interface was drafted before the nullable field-specific
convention was adopted. Revise that interface to follow
`docs/conventions.md` before approving this roadmap.

## 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

The `ansible-role-notarius` repository currently contains only its initial
placeholder files. Notarius is one of the five required pipeline applications
and needs an independently usable installation and native-configuration role
before the suite role can 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.

## 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.
- 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 separate Ansible variable for every Notarius configuration field.
- 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`.

An immediate second application reports no changes. A changed Git checkout or
missing binary causes one build; configuration changes converge independently
through the ordinary file-management module. Repository-local tests execute
the installed CLI to verify the selected build and validate the managed
configuration.

## 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 mapping interface.
- `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 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 is exposed as one complete mapping. The suite role will later
  supply the full D&D pipeline and operating policy through that boundary.
- 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`, commit
  `61436d7c186af57b06004e090ceac898e83cdb71`, remains buildable with the same
  Go requirement, package, linker symbol, and configuration schema and may be
  used for focused checkout-change coverage before restoring `v0.6.0`.

## Fixed Public Interface

| 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 |
| `notarius_config` | `{"version": 4}` | Complete versioned configuration mapping |

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.

## 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. Serialize `notarius_config` as YAML and manage `notarius_config_path` with
   `ansible.builtin.copy`.

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 preflight, 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.

A single configuration mapping preserves Notarius's strict native schema and
avoids duplicating a large, evolving configuration surface as role variables.
The minimal valid document keeps the standalone role useful without embedding
D&D policy. The suite role can later provide the maintained pipeline,
PromptKit profile selection, concurrency, state paths, and other integrated
values as one complete override.

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

- Unsupported distributions, Ubuntu releases, and architectures fail before
  application state is modified.
- Default execution on the local Ubuntu 26.04 host installs or confirms Git
  and Go and checks out tag `v0.6.0` at commit
  `77ae132e5609916da40dcd4fcc749c000a63cbac`.
- The role builds with the fixed upstream contract and installs
  `/usr/local/bin/notarius` as a regular file owned by `root:root` with mode
  `0755`.
- The managed source checkout is recursively owned by `root:root`.
- The default schema-version 4 configuration is installed at
  `/usr/local/etc/notarius/config.yml` as a regular file owned by `root:root`
  with mode `0644`.
- Repository-local tests receive `notarius v0.6.0` from the installed CLI and
  successfully validate the managed configuration.
- An immediate second role run reports no changes.
- A missing binary causes one rebuild followed by an unchanged run.
- A changed checkout causes one rebuild followed by an unchanged run.
- A configuration change updates only configuration state and does not rebuild
  the binary.
- Dependency opt-out accepts a caller-supplied `notarius_go_binary`.
- A play connecting as an ordinary sudo-capable user can apply the role without
  play-level privilege escalation.
- Defaults and argument specifications contain exactly the nine variables in
  the Fixed Public Interface.
- Production tasks contain no CLI validation, fingerprints, checksums, sidecar
  state, manual Git reset or clean commands, or probes before state already
  managed by APT, Snap, `file`, `git`, or `copy`.
- Syntax checking, production-profile ansible-lint, focused local convergence,
  CLI verification, configuration validation, and clean repeated runs pass.
- Role documentation describes actual behavior, dependency opt-out, the
  complete configuration mapping, privilege use, and integration-test effects.
- No repository other than `ansible-role-notarius` and the workspace control
  repository is modified.

## 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.

After this roadmap is approved, replace the pending notice at
`docs/roadmap/implementation.md` with a numbered staged Notarius implementation
plan. The pipeline role can select concrete `notarius_config` values after the
standalone interface is implemented and reviewed.

## 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 dedicated Ubuntu release and architecture test matrices.