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

# Feature 0001: Seriatim Source Installation

Status: proposed

## Summary

Implement the first independently usable application role by teaching
`ansible-role-seriatim` to install Seriatim from a pinned upstream source
release. This feature establishes the source-build and role conventions that
can be reviewed before analogous work begins in the other application roles.

## Problem or Opportunity

The pipeline applications do not yet share a uniform prebuilt release model,
and the new Ansible role repositories contain only initial scaffolding. The MVP
therefore builds applications on the managed host. Seriatim is the smallest
useful proving ground because it has no central application configuration file,
allowing this feature to isolate installation, reproducibility, idempotence,
and validation concerns.

## Scope

- Establish a conventional, independently usable Ansible role structure in
  `ansible-role-seriatim`.
- Support Ubuntu 26.04 on native `amd64` and `arm64` hosts.
- Install Git and the official Go Snap using classic confinement when build
  dependency management is enabled.
- Default the Go Snap channel to `1.26/stable` and allow consumers to override
  the channel or disable build-dependency management.
- Clone the official Seriatim repository into a root-owned managed source
  directory, defaulting to `/usr/local/src/seriatim`.
- Default to the immutable `v1.5.0` release tag, verified as the latest current
  upstream tag on 2026-09-07, while supporting explicit branch or commit
  overrides for development.
- Build a native, statically linked Seriatim binary using the upstream build
  contract, including release-version injection.
- Validate a staged binary before installing it as
  `/usr/local/bin/seriatim` with `root:root` ownership and mode `0755`.
- Record sufficient build state to rebuild when the resolved source commit,
  Go compiler version, or effective build arguments change.
- Validate the installed binary and demonstrate convergence on a repeated role
  run.
- Document the role interface, defaults, supported platform, development
  overrides, and validation procedure.

## 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 Seriatim release artifacts.
- Removal or purge behavior.
- A shared build helper role or premature abstraction of the first
  implementation.
- Full Ubuntu 26.04 platform-matrix or `arm64` integration infrastructure.

## Target End State

On an Ubuntu 26.04 `amd64` or `arm64` host, applying the role with default
variables checks out Seriatim `v1.5.0` under `/usr/local/src/seriatim`, builds
it with the locally installed Go 1.26 toolchain, validates it, and installs a
root-owned executable at `/usr/local/bin/seriatim`. The installed command
reports `v1.5.0` through its global version flag.

A second application of the role makes no changes when the selected source,
compiler, build arguments, and installed binary are unchanged. Changing the
selected revision, compiler patch version, or effective build arguments causes
a rebuild. A failed build or validation does not replace an existing working
binary.

The managed source checkout is authoritative and may be reset to the selected
revision; local modifications beneath it are not preserved. Development users
may select a branch or commit explicitly, but released role and collection
manifests use immutable release tags.

## Repository Ownership

- `ansible-role-seriatim` owns all implementation, defaults, documentation,
  and repository-local validation added by this feature.
- `../seriatim` is the read-only authority for the application build, version,
  and CLI contracts.
- `ansible-workspace-dnd` owns this roadmap, the active implementation plan,
  and cross-repository status only.
- The remaining role, collection, application, content, and proof-of-concept
  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; dedicated platform-matrix infrastructure is deferred.
- Go is installed from Snap with classic confinement. Builds use the local
  toolchain with `GOTOOLCHAIN=local` rather than allowing automatic toolchain
  downloads.
- `community.general` is an approved dependency and provides Snap management;
  its version is pinned in the role's collection requirements.
- The suite standardizes on Go channel `1.26/stable`, even though Seriatim's
  current `go.mod` requires Go 1.25.
- Builds use `GOWORK=off`, `CGO_ENABLED=0`, and `-trimpath`.
- Release builds inject the selected release version into
  `gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version` with
  `-ldflags`.
- A change to the installed Go compiler patch version is a build-input change
  and triggers a rebuild.
- `/usr/local/src/seriatim` is fully Ansible-managed. The role enforces the
  selected Git revision rather than preserving local changes.
- Source and installed binaries are owned by `root` and are not writable by
  runtime operators.

## Rationale and Alternatives

Starting with Seriatim exercises the common source installation path without
mixing in application configuration, credentials, shared accounts, or pipeline
composition. This makes the first implementation small enough to review
carefully and allows its conventions to be corrected before being repeated.

Using Go `1.26/stable` across the suite favors one predictable host toolchain
over selecting each application's minimum supported version. Rebuilding after
a compiler patch change preserves an honest relationship between recorded
build inputs and installed output. Keeping the first role self-contained also
avoids committing to a shared abstraction before repeated implementation has
shown which behavior is truly common.

## Acceptance Criteria

- The role rejects unsupported distributions, Ubuntu releases, and
  architectures with a clear diagnostic before modifying application state.
- Default role execution on the local Ubuntu 26.04 host installs or confirms
  the required Git and Go build dependencies.
- The source checkout resolves to the commit referenced by tag `v1.5.0` and is
  root-owned at `/usr/local/src/seriatim` by default.
- The role builds with the documented local-toolchain and version-injection
  contract and installs `/usr/local/bin/seriatim` as `root:root` mode `0755`.
- `/usr/local/bin/seriatim --version` reports `v1.5.0`.
- An immediate second role run reports no changes.
- A changed selected revision, Go compiler patch version, or effective build
  argument invalidates recorded build state and rebuilds the binary.
- A deliberately failed staged build or version validation leaves a previously
  installed working binary intact.
- Development revision overrides converge to the requested branch or commit
  and discard unmanaged changes in the source checkout.
- Role defaults, metadata, README documentation, syntax validation, focused
  automated checks, and local integration evidence are present in the owning
  repository.
- No repository other than `ansible-role-seriatim` and the workspace control
  repository is modified.

## Dependencies and Follow-up Work

This feature depends only on access to the Seriatim Git repository, Ubuntu Snap
infrastructure, and Go module sources from the managed host.

After review, the source-build conventions may be adopted by the Audita,
Scriptorium, Notarius, and Narratio roles. Generalization into shared tooling,
prebuilt-binary installation, removal behavior, and dedicated multi-platform
test infrastructure remain deferred until concrete experience justifies them.