diff --git a/docs/roadmap/features/0003-notarius-source-installation-and-configuration.md b/docs/roadmap/features/0003-notarius-source-installation-and-configuration.md index 81445b4..33bce84 100644 --- a/docs/roadmap/features/0003-notarius-source-installation-and-configuration.md +++ b/docs/roadmap/features/0003-notarius-source-installation-and-configuration.md @@ -12,16 +12,25 @@ 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. +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. @@ -91,9 +100,16 @@ 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 select immutable `v0.5.0` explicitly before checking its native CLI -output, and validate the managed configuration. +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 @@ -271,53 +287,58 @@ 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 +### 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 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 configuration contains exactly `version: 4` and is installed at - `/usr/local/etc/notarius/config.yml`, owned by `root:root` with mode `0644`. -- Every optional field is absent when its variable is null, including parent - sections with no selected descendants. -- A representative configuration exercises every top-level section and - validates successfully with `notarius config validate`. -- Explicit falsey non-null values, including zero and false, are rendered - rather than omitted; semantic validity remains Notarius's responsibility. -- Repository-local tests explicitly select `v0.5.0`, receive `notarius v0.5.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 eight installation - variables and fourteen configuration variables in the Fixed Public - Interface. -- No raw `notarius_config` compatibility variable, template override, or - parallel configuration interface exists. +- 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. -- 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 `template`. -- 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, every - public configuration variable, null-as-omission behavior, the native - `pipelines` boundary and caller-side composition example, privilege use, and - integration-test effects. +- 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