feat: define Seriatim role contract

.gitignore

@@ -1,5 +1,7 @@
 # ---> Ansible
 *.retry
+.ansible/
+tests/output/
 
 # ---> Linux
 *~
@@ -83,4 +85,3 @@ $RECYCLE.BIN/
 .history/
 
 # Built Visual Studio Code Extensions
-*.vsix

README.md

@@ -1,3 +1,52 @@
-# ansible-role-seriatim
+# Ansible Role: Seriatim
 
-Ansible role to install the Audita transcript processor.
+Installs the [Seriatim](https://gitea.maximumdirect.net/eric/seriatim)
+transcript processor from source. The role supports Ubuntu 26.04 on `amd64`
+and `arm64` hosts and is independently usable outside the D&D pipeline role.
+
+At this point the role defines and validates its public contract; binary
+installation is added by subsequent implementation work.
+
+## Requirements
+
+Ansible Core 2.18 or newer is required. Install the pinned collection
+dependency before using or validating the role:
+
+```sh
+ansible-galaxy collection install -r collections/requirements.yml
+```
+
+## Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `seriatim_version` | `v1.5.0` | Release identity expected from the installed binary. |
+| `seriatim_repository_url` | `https://gitea.maximumdirect.net/eric/seriatim.git` | Source repository URL. |
+| `seriatim_source_ref` | `{{ seriatim_version }}` | Git tag, branch, or commit to check out. |
+| `seriatim_build_version` | `{{ seriatim_version }}` | Version injected into build metadata. |
+| `seriatim_source_dir` | `/usr/local/src/seriatim` | Fully managed source checkout. |
+| `seriatim_binary_path` | `/usr/local/bin/seriatim` | Installed executable path. |
+| `seriatim_build_state_dir` | `/usr/local/src/seriatim.ansible-build-state` | Sidecar directory for build inputs and output state. |
+| `seriatim_manage_build_dependencies` | `true` | Install Git and Go when enabled. |
+| `seriatim_go_snap_channel` | `1.26/stable` | Go Snap channel. |
+| `seriatim_go_binary` | `/snap/bin/go` | Go executable used to inspect and build. |
+| `seriatim_go_build_flags` | `[-trimpath]` | Ordered Go build arguments before `-ldflags`. |
+| `seriatim_go_ldflags` | `-s -w -X gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version={{ seriatim_build_version }}` | Linker flags passed as one argument. |
+| `seriatim_go_package` | `./cmd/seriatim` | Go package built from the checkout. |
+
+For development revisions, set both `seriatim_source_ref` and an honest
+`seriatim_build_version`. Released deployments should select immutable tags.
+
+## Static validation
+
+```sh
+ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
+  ../.venv/bin/ansible-playbook -i tests/inventory tests/converge.yml \
+  --syntax-check
+ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
+  ../.venv/bin/ansible-lint .
+```
+
+## License
+
+BSD-3-Clause

ansible.cfg

@@ -0,0 +1,2 @@
+[defaults]
+roles_path = ..

collections/requirements.yml

@@ -0,0 +1,4 @@
+---
+collections:
+  - name: community.general
+    version: 13.3.0

defaults/main.yml

@@ -0,0 +1,16 @@
+---
+seriatim_version: v1.5.0
+seriatim_repository_url: https://gitea.maximumdirect.net/eric/seriatim.git
+seriatim_source_ref: "{{ seriatim_version }}"
+seriatim_build_version: "{{ seriatim_version }}"
+seriatim_source_dir: /usr/local/src/seriatim
+seriatim_binary_path: /usr/local/bin/seriatim
+seriatim_build_state_dir: /usr/local/src/seriatim.ansible-build-state
+seriatim_manage_build_dependencies: true
+seriatim_go_snap_channel: 1.26/stable
+seriatim_go_binary: /snap/bin/go
+seriatim_go_build_flags:
+  - -trimpath
+seriatim_go_ldflags: >-
+  -s -w -X gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version={{ seriatim_build_version }}
+seriatim_go_package: ./cmd/seriatim

meta/argument_specs.yml

@@ -0,0 +1,58 @@
+---
+argument_specs:
+  main:
+    short_description: Install the Seriatim transcript processor from source
+    options:
+      seriatim_version:
+        type: str
+        required: true
+        description: Release identity expected from the installed binary.
+      seriatim_repository_url:
+        type: str
+        required: true
+        description: Git repository containing Seriatim source.
+      seriatim_source_ref:
+        type: str
+        required: true
+        description: Git tag, branch, or commit to check out.
+      seriatim_build_version:
+        type: str
+        required: true
+        description: Version value injected into build metadata.
+      seriatim_source_dir:
+        type: path
+        required: true
+        description: Fully managed source checkout path.
+      seriatim_binary_path:
+        type: path
+        required: true
+        description: Installed executable path.
+      seriatim_build_state_dir:
+        type: path
+        required: true
+        description: Sidecar directory holding successful build state.
+      seriatim_manage_build_dependencies:
+        type: bool
+        required: true
+        description: Whether to install Git and Go.
+      seriatim_go_snap_channel:
+        type: str
+        required: true
+        description: Go Snap channel to install.
+      seriatim_go_binary:
+        type: path
+        required: true
+        description: Go executable used for discovery and builds.
+      seriatim_go_build_flags:
+        type: list
+        elements: str
+        required: true
+        description: Ordered arguments passed to go build before ldflags.
+      seriatim_go_ldflags:
+        type: str
+        required: true
+        description: Linker flags passed to go build as one argument.
+      seriatim_go_package:
+        type: str
+        required: true
+        description: Go package built from the source checkout.

meta/main.yml

@@ -0,0 +1,17 @@
+---
+galaxy_info:
+  role_name: seriatim
+  namespace: rakestraw
+  author: Eric Rakestraw
+  description: Install the Seriatim transcript processor from source
+  license: BSD-3-Clause
+  min_ansible_version: "2.18"
+  platforms:
+    - name: Ubuntu
+      versions:
+        - resolute
+  galaxy_tags:
+    - seriatim
+    - transcript
+    - processing
+dependencies: []

tasks/main.yml

@@ -0,0 +1,3 @@
+---
+- name: Validate Seriatim role inputs
+  ansible.builtin.import_tasks: validate.yml

tasks/validate.yml

@@ -0,0 +1,38 @@
+---
+- name: Verify the managed host is supported
+  ansible.builtin.assert:
+    that:
+      - ansible_facts.distribution == 'Ubuntu'
+      - ansible_facts.distribution_version is version('26.04', '==')
+      - ansible_facts.architecture in ['x86_64', 'aarch64']
+    fail_msg: >-
+      Seriatim supports Ubuntu 26.04 on x86_64 and aarch64; detected
+      {{ ansible_facts.distribution }} {{ ansible_facts.distribution_version }}
+      on {{ ansible_facts.architecture }}.
+
+- name: Verify required Seriatim values are nonempty
+  ansible.builtin.assert:
+    that:
+      - seriatim_version | length > 0
+      - seriatim_repository_url | length > 0
+      - seriatim_source_ref | length > 0
+      - seriatim_build_version | length > 0
+      - seriatim_go_snap_channel | length > 0
+      - seriatim_go_binary | length > 0
+      - seriatim_go_build_flags | length > 0
+      - seriatim_go_build_flags | select('equalto', '') | list | length == 0
+      - seriatim_go_ldflags | length > 0
+      - seriatim_go_package | length > 0
+      - seriatim_build_version is not regex('.*\\s+.*')
+    fail_msg: Seriatim repository, revision, build, and Go values must be nonempty, and the build version cannot contain whitespace.
+
+- name: Verify managed Seriatim paths are safe and distinct
+  ansible.builtin.assert:
+    that:
+      - seriatim_source_dir is match('^/')
+      - seriatim_binary_path is match('^/')
+      - seriatim_build_state_dir is match('^/')
+      - seriatim_source_dir != seriatim_binary_path
+      - seriatim_source_dir != seriatim_build_state_dir
+      - seriatim_binary_path != seriatim_build_state_dir
+    fail_msg: Seriatim source, binary, and state paths must be absolute and pairwise distinct.

tests/converge.yml

@@ -0,0 +1,7 @@
+---
+- name: Converge Seriatim role
+  hosts: seriatim
+  gather_facts: true
+  become: true
+  roles:
+    - role: ansible-role-seriatim

tests/inventory

@@ -0,0 +1,2 @@
+[seriatim]
+localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3.14