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

7.6 KiB Raw Blame History