ansible-workspace-dnd/docs/roadmap/features/0001-seriatim-source-installation.md

# Feature 0001: Seriatim Source Installation

Status: done

## Summary

Provide a small, independently usable `rakestraw.seriatim` role that installs
Seriatim from a pinned Git tag, builds the native executable on the managed
host, and converges idempotently. This revised specification replaces the
original overengineered implementation target and establishes the preferred
module-driven style for subsequent application roles.

## Problem or Opportunity

The current role reaches the basic deployment outcome, but it does so with
manual source cleanup, compiler parsing, build-input serialization, hashes,
checksums, sidecar state, path-shape recovery, and a large defensive test
matrix. Those mechanisms are disproportionate to the MVP and obscure the
simple job of checking out a repository, building one executable, and
installing it with known metadata.

Seriatim remains the right proving ground because it has no central
configuration file. Simplifying it before implementing another role prevents
the current design from becoming an accidental suite-wide pattern.

## Scope

- Simplify `ansible-role-seriatim` into concise, idiomatic Ansible.
- 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 the selected Seriatim version from its official Git repository,
  defaulting to immutable tag `v1.5.0`, under a root-owned
  `/usr/local/src/seriatim`.
- Build Seriatim using the fixed upstream release build contract and install
  it at `/usr/local/bin/seriatim`.
- Rebuild when the source checkout changes or the binary is absent.
- Converge the installed binary to `root:root` ownership and mode `0755`.
- Verify an explicitly selected immutable Seriatim version through the native
  CLI in repository-local integration tests.
- Keep the role interface, README, metadata, and focused local tests consistent
  with the simplified behavior.
- Remove obsolete build-state files and implementation machinery from the
  role repository. Existing build-state data on previously managed hosts does
  not need to be removed by the role.

## Non-goals

- Application configuration; Seriatim has no central configuration file.
- Creation or management of the `narratio` account or operator membership.
- Installation or configuration of any other pipeline application.
- Pipeline composition, campaign data, prompts, secrets, or scheduling.
- Installation from prebuilt release artifacts or removal behavior.
- Detecting rebuild needs from Go compiler changes, fixed build-command
  changes, or out-of-band modification of an existing binary.
- Build fingerprints, binary checksums, or persistent sidecar build state.
- Transactional replacement that preserves a previous executable after a
  failed local build.
- Automatic recovery from deliberately malformed paths, symbolic-link
  redirection, hostile source trees, or other adversarial host state.
- A shared build helper role or abstraction.
- Dedicated platform-matrix infrastructure beyond the approved local MVP
  proxy.

## Target End State

On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with default
variables installs Git and Go when requested, checks out Seriatim `v1.5.0`
under a root-owned `/usr/local/src/seriatim`, and installs a native executable at
`/usr/local/bin/seriatim`. The executable is owned by `root:root`, has mode
`0755`, and reports `seriatim version v1.5.0`.

An immediate second application makes no changes. A changed Git checkout or a
missing binary causes one build. The following application is again unchanged.

The role trusts `apt`, `community.general.snap`, `file`, and `git` to provide
their documented idempotence and change detection. It does not inspect state
before invoking those modules or maintain a parallel model of the state they
already manage.

## Repository Ownership

- `ansible-role-seriatim` owns the role implementation, defaults, metadata,
  README, dependency declaration, and repository-local validation.
- `../seriatim` is the read-only authority for the build, version, and CLI
  contracts.
- `rakestraw-ansible` is a read-only style reference.
- `ansible-workspace-dnd` owns this roadmap, the active implementation plan,
  and cross-repository status.
- All other repositories remain unchanged.

## Constraints and Settled Decisions

- The suite MVP supports Ubuntu 26.04 and native `amd64` and `arm64` builds.
- Local execution on the current Ubuntu 26.04 development host is a sufficient
  MVP integration proxy.
- Go is installed from Snap with classic confinement and defaults to channel
  `1.26/stable`.
- `community.general` is an approved dependency and provides Snap management;
  its version is pinned in the role's collection requirements.
- The build runs from the checked-out source using `seriatim_go_binary`
  (defaulting to `/snap/bin/go`) with `GOWORK=off`, `GOTOOLCHAIN=local`,
  `CGO_ENABLED=0`, `-trimpath`, package `./cmd/seriatim`, and the upstream
  linker flag that injects the selected version into
  `internal/buildinfo.Version`.
- The selected version is both the Git revision and the version injected into
  the executable. Supporting independent source and build identities is not an
  MVP requirement.
- The public interface is limited to meaningful deployment choices:
  `seriatim_version`, `seriatim_repository_url`, `seriatim_source_dir`,
  `seriatim_binary_path`, `seriatim_manage_build_dependencies`,
  `seriatim_go_snap_channel`, and `seriatim_go_binary`.
- Build flags, linker symbols, environment values, and package paths are
  implementation details, not public variables.
- Tasks that install dependencies or manage root-owned application state use
  task-level privilege escalation.
- `docs/decisions/0001-minimal-module-driven-ansible.md` governs the role's
  implementation style.

## Simplest Viable Implementation

The intended Seriatim implementation is approximately the following eight
ordinary tasks.

1. Assert the supported distribution, release, and architecture.
2. Install Git with `ansible.builtin.apt` when dependency management is
   enabled.
3. Install Go with `community.general.snap` when dependency management is
   enabled.
4. Create the source and binary parent directories with one
   `ansible.builtin.file` loop.
5. Check out the selected source with `ansible.builtin.git` and register its
   normal changed result.
6. Inspect whether the installed binary exists.
7. Run the upstream Go build when the Git checkout changed or the binary is
   absent.
8. Converge source ownership and the installed binary's ownership and mode
   with one `ansible.builtin.file` loop.

For this fixed set of two rebuild triggers, the build remains an ordinary
task with the conditions applied directly to its `when` expression. This keeps
the complete decision visible at the action site and avoids deferred execution
or a play-wide handler flush. Permission convergence then follows in its
natural task order. Do not create an intermediate `seriatim_build_required`
fact.

The implementation may combine or split a task when required for clear and
correct Ansible, but it must not add preflight checks around idempotent modules
or reintroduce persistent build-state machinery. Prefer a single readable task
file unless a split materially improves navigation.

## Rationale and Alternatives

This design uses the Git module's changed result as the natural signal that
source changed. A binary existence check is the only additional state needed
to decide whether the imperative build command must run. That preserves useful
convergence without adding unrequested drift detection or maintaining a second
database of compiler and build inputs.

Building directly to the configured binary path is intentionally simpler than
staging, checksumming, and recording a transactional installation. A failed
build will fail the play visibly; preserving an older executable in every
failure mode is not an MVP requirement.

## Acceptance Criteria

- The role rejects unsupported distributions, Ubuntu releases, and
  architectures before modifying application state.
- Default execution on the local Ubuntu 26.04 host installs or confirms Git
  and Go and checks out Seriatim tag `v1.5.0`.
- The role builds with the documented fixed upstream contract and installs
  `/usr/local/bin/seriatim` as `root:root` mode `0755`.
- The managed source checkout is owned by `root:root`.
- `/usr/local/bin/seriatim --version` reports
  `seriatim version v1.5.0`.
- An immediate second role run reports no changes.
- A missing binary causes one rebuild followed by an unchanged run.
- A changed selected version causes the Git task and build task to change and
  then converges.
- The implementation contains no build-input documents, fingerprints, binary
  checksums, sidecar build state, manual Git reset or clean commands, or
  preliminary checks for state already managed by `apt`, Snap, `file`, or
  `git`.
- Public defaults and argument specifications contain only the seven variables
  named in this roadmap.
- A caller may disable dependency management and select an existing Go
  executable with `seriatim_go_binary`.
- Tasks requiring superuser access use task-level privilege escalation.
- Syntax checking, ansible-lint, a focused local convergence test, and a clean
  repeated run pass.
- Role documentation describes the actual concise behavior and does not claim
  transactional build safety or exhaustive corruption recovery.
- No repository other than `ansible-role-seriatim` and the workspace control
  repository is modified.

## Dependencies and Follow-up Work

The role requires access to the Seriatim Git repository, Ubuntu Snap
infrastructure, and Go module sources from the managed host. After this revised
implementation is reviewed, its minimal conventions can inform a fresh Audita
roadmap and the remaining application roles.

The original implementation commits remain in Git history as evidence of the
superseded design. The prior completion and remediation documents must not be
used as templates for another role.

## Potential Future Hardening

- Build in a temporary location and validate before replacing the installed
  executable.
- Verify release signatures or source checksums.
- Record compiler and build-input identity for exact rebuild invalidation.
- Detect arbitrary binary modification independently of reported version.
- Protect or recover from unexpected symbolic links and malformed managed
  paths.
- Add broader Ubuntu release and architecture test coverage only if future
  platform behavior warrants it.

These are candidates for separately selected features if operational
experience or a changed threat model justifies them.