Plan the pipeline role composition foundation
This commit is contained in:
@@ -0,0 +1,382 @@
|
||||
# Feature 0006: Pipeline Role Composition Foundation
|
||||
|
||||
Status: ready
|
||||
|
||||
## Summary
|
||||
|
||||
Establish `ansible-role-dnd-pipeline` as the independently developed
|
||||
suite-level role that composes the five completed application roles. The
|
||||
feature provides a reproducible dependency manifest, a small suite-owned
|
||||
public interface, compatible application-version selection, and the native
|
||||
cross-application paths Narratio needs to find the installed tools.
|
||||
|
||||
This is the foundation of the complete D&D deployment, not the complete
|
||||
deployment itself. Campaign data, the prompt library, operator access, secret
|
||||
delivery, and opinionated D&D processing policy remain later pipeline-role
|
||||
features.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
The five standalone application roles are implemented, tested, and
|
||||
independently usable. The `ansible-role-dnd-pipeline` repository still contains
|
||||
only its initial README and license, so consumers must currently discover,
|
||||
install, version, and invoke every role separately and manually connect their
|
||||
paths.
|
||||
|
||||
The suite needs one composition boundary before it can add D&D-specific
|
||||
content and policy. Establishing that boundary first keeps later work focused:
|
||||
subsequent features can add suite behavior without reopening how dependencies
|
||||
are named, installed, invoked, or configured.
|
||||
|
||||
## Governing Policies
|
||||
|
||||
- [The Ansible house style](../../ansible.md) governs role composition, public
|
||||
variables, task structure, and the use of downstream role interfaces.
|
||||
- [The testing house style](../../testing.md) governs repository-local
|
||||
validation. Tests exercise the assembled role through native outcomes and
|
||||
clean repeated convergence without reproducing the standalone suites.
|
||||
- [The MVP roadmap](../mvp.md) fixes the supported platform, independently
|
||||
released application roles, Git-hosted role dependencies, source-build
|
||||
model, and suite/collection boundary.
|
||||
- [Decision 0001](../../decisions/0001-minimal-module-driven-ansible.md)
|
||||
requires the smallest direct composition and rejects supplemental state or
|
||||
verification machinery without a selected requirement.
|
||||
|
||||
## Scope
|
||||
|
||||
- Turn `ansible-role-dnd-pipeline` into a conventional standalone Ansible role
|
||||
with defaults, argument specifications, metadata, dependency manifests,
|
||||
documentation, and focused integration coverage.
|
||||
- Install the five standalone roles from their Git repositories under the
|
||||
canonical names `rakestraw.audita`, `rakestraw.narratio`,
|
||||
`rakestraw.notarius`, `rakestraw.seriatim`, and `rakestraw.scriptorium`.
|
||||
- Pin the development dependency manifest to the reviewed commits that
|
||||
completed the five standalone roles. Preserve the existing release policy
|
||||
that replaces development commits with immutable role tags before a
|
||||
released suite or collection is published.
|
||||
- Invoke all five application roles as declared role dependencies in a fixed,
|
||||
readable order.
|
||||
- Select one known-compatible default application release for each component:
|
||||
Audita `v0.9.1`, Narratio `v2.0.0`, Notarius `v0.6.0`, Seriatim `v1.5.0`,
|
||||
and Scriptorium `v0.13.0`.
|
||||
- Expose one suite-level dependency-management choice, Go Snap channel, and Go
|
||||
executable, then pass those values to every application role.
|
||||
- Require a suite-level WhisperX transcription URL and pass it to the Narratio
|
||||
role.
|
||||
- Configure Narratio with the standard binary and configuration paths managed
|
||||
by the composed roles so the orchestrator can find Seriatim, Audita,
|
||||
Notarius, and Scriptorium.
|
||||
- Keep dependency metadata, defaults, argument specifications, README, and
|
||||
focused repository-local tests aligned with the public contract.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Checking out or deploying the `campaigns` repository, including its
|
||||
revision and update policy.
|
||||
- Installing the `narratio-prompts` prompt library or selecting its filesystem
|
||||
layout.
|
||||
- Defining PromptKit profiles, Scriptorium backends, Notarius pipelines,
|
||||
Narratio artifacts, publish outputs, or detailed Audita policy.
|
||||
- Enabling Notarius in the Narratio pipeline before a usable Notarius pipeline
|
||||
definition is supplied.
|
||||
- Selecting human operators or changing their group membership.
|
||||
- Defining, storing, templating, or injecting secret values or environment
|
||||
files.
|
||||
- Running a real recording through the end-to-end D&D workflow.
|
||||
- Bundling the role into `rakestraw.dnd`; collection incorporation remains the
|
||||
next repository boundary after the standalone pipeline role is functional.
|
||||
- Publishing or tagging any role or collection release.
|
||||
- Duplicating every public variable from every application role behind a
|
||||
`dnd_pipeline_` alias.
|
||||
- Reimplementing application installation, configuration templates, account
|
||||
creation, or platform validation in the pipeline role.
|
||||
- Supporting partial component installation, per-component enable switches,
|
||||
removal, or migration from the legacy proof-of-concept role.
|
||||
- Probing downstream state, inspecting task results, or validating a
|
||||
successful downstream operation during production convergence.
|
||||
- Testing every application-role behavior again at the suite level.
|
||||
|
||||
## Target End State
|
||||
|
||||
A consumer first installs the pipeline role's declared Git role dependencies,
|
||||
then applies `rakestraw.dnd_pipeline` with a WhisperX transcription URL. The
|
||||
role invokes the five standalone roles, which install their selected sources,
|
||||
binaries, native configuration, and Narratio runtime state using their own
|
||||
public contracts.
|
||||
|
||||
The pipeline role selects the five compatible application versions as one
|
||||
set. A caller may replace an individual selection through the corresponding
|
||||
suite variable without editing the dependency declaration or addressing the
|
||||
application role directly. Shared dependency management, Go channel, and Go
|
||||
executable choices likewise flow consistently to all five roles.
|
||||
|
||||
Narratio's managed pipeline document names the installed Seriatim, Audita,
|
||||
Notarius, and Scriptorium executable paths and the managed configuration paths
|
||||
for the configured applications. Notarius remains installed but is not enabled
|
||||
as a Narratio stage by this foundation feature. All other optional application
|
||||
settings retain their standalone-role defaults unless a caller supplies the
|
||||
underlying application role variable directly.
|
||||
|
||||
The pipeline role does not own or reproduce downstream templates. It composes
|
||||
the roles through their public variables and lets each role converge its own
|
||||
state. An immediate second pipeline-role application reports no changes.
|
||||
|
||||
This intentionally minimal interface is a foundation, not the pipeline role's
|
||||
final policy surface. Later features will give the pipeline role concrete,
|
||||
opinionated D&D defaults for Audita, Narratio, Notarius, Seriatim, and
|
||||
Scriptorium through the standalone roles' existing field-specific variables.
|
||||
Those values will remain overrideable through ordinary inventory precedence.
|
||||
The suite will add only policy it deliberately owns, rather than copying every
|
||||
upstream application default.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
- `ansible-role-dnd-pipeline` owns the dependency manifest, suite public
|
||||
interface, dependency declarations, cross-application path wiring,
|
||||
repository documentation, and focused integration suite. This is the only
|
||||
implementation repository changed by the feature.
|
||||
- `ansible-role-{audita,narratio,notarius,seriatim,scriptorium}` are read-only
|
||||
dependency sources and the authorities for their respective public role
|
||||
interfaces. Their reviewed commits define the development dependency set.
|
||||
- `../{audita,narratio,notarius,seriatim,scriptorium}` remain read-only
|
||||
authorities for application behavior.
|
||||
- `rakestraw-ansible` is a read-only style and historical deployment-policy
|
||||
reference. Its monolithic installation and templating are not copied.
|
||||
- `assets/campaigns` and `assets/narratio-prompts` are read-only authorities
|
||||
for the content and layouts that later pipeline-role features will deploy.
|
||||
Their availability in the workspace does not bring content deployment into
|
||||
this composition-foundation feature.
|
||||
- `ansible-collection-dnd` remains unchanged until collection assembly is
|
||||
selected as a later feature.
|
||||
- `ansible-workspace-dnd` owns this roadmap, the eventual staged plan, the
|
||||
settled MVP decisions, and aggregate status.
|
||||
|
||||
## Constraints and Settled Decisions
|
||||
|
||||
- The standalone role is named `dnd_pipeline` in the `rakestraw` Galaxy
|
||||
namespace. It will later be incorporated into the collection under the
|
||||
shorter consumer-facing name `rakestraw.dnd.pipeline`.
|
||||
- Git dependencies are installed with these canonical role names:
|
||||
|
||||
| Role | Repository | Development revision |
|
||||
| --- | --- | --- |
|
||||
| `rakestraw.audita` | `https://gitea.maximumdirect.net/eric/ansible-role-audita.git` | `d2d0b9d00b3b491ce7613ccfc8f686f3d1fa0896` |
|
||||
| `rakestraw.narratio` | `https://gitea.maximumdirect.net/eric/ansible-role-narratio.git` | `7feff4728a5968b6b1dd87e83add9fa1a9066b18` |
|
||||
| `rakestraw.notarius` | `https://gitea.maximumdirect.net/eric/ansible-role-notarius.git` | `cfecf37261f2595d45113235c591ee102d6f181f` |
|
||||
| `rakestraw.seriatim` | `https://gitea.maximumdirect.net/eric/ansible-role-seriatim.git` | `e08c63c0b078658bdfa2d10a2e6e1e4f9372a075` |
|
||||
| `rakestraw.scriptorium` | `https://gitea.maximumdirect.net/eric/ansible-role-scriptorium.git` | `8f47aa802a5e0c9dae9c0f43a1c70b3512b2c8b2` |
|
||||
|
||||
- Commit pins are appropriate for active development because the role
|
||||
repositories do not yet publish release tags. A release must use immutable
|
||||
role tags under the policy already fixed in the MVP roadmap.
|
||||
- `requirements.yml` is the consumer and test bootstrap manifest for the five
|
||||
Git roles. `collections/requirements.yml` declares the pinned
|
||||
`community.general` dependency needed transitively by those roles.
|
||||
- `meta/main.yml` declares the five application roles as dependencies and maps
|
||||
the suite-owned inputs to their existing public variables. It does not use
|
||||
an implementation-specific loader role.
|
||||
- Dependencies execute in this order: Seriatim, Audita, Notarius,
|
||||
Scriptorium, then Narratio. The order makes the downstream tools conceptually
|
||||
available before the orchestrator, but the role does not add probes or
|
||||
runtime validation to enforce the order's postconditions.
|
||||
- Repeated Git, APT, and Snap declarations inside the five roles are accepted.
|
||||
Their modules are idempotent, and consolidating them would weaken standalone
|
||||
role ownership for no selected benefit.
|
||||
- The suite owns only choices that must be coordinated across applications or
|
||||
recorded as a compatible set. It does not alias the complete downstream
|
||||
interfaces. Unmapped application-specific variables retain their ordinary
|
||||
Ansible behavior and may be supplied directly by advanced callers.
|
||||
- The preceding boundary governs this composition foundation only; it does not
|
||||
make the finished pipeline role policy-neutral. Later D&D-configuration
|
||||
features will supply opinionated values directly through the downstream
|
||||
roles' public variables, preserving inventory overrides without introducing
|
||||
parallel templates or complete shadow interfaces.
|
||||
- The feature uses the standard application paths fixed by the MVP and current
|
||||
standalone roles:
|
||||
|
||||
| Purpose | Path |
|
||||
| --- | --- |
|
||||
| Seriatim executable | `/usr/local/bin/seriatim` |
|
||||
| Audita executable | `/usr/local/bin/audita` |
|
||||
| Audita configuration | `/usr/local/etc/audita/config.yml` |
|
||||
| Notarius executable | `/usr/local/bin/notarius` |
|
||||
| Notarius configuration | `/usr/local/etc/notarius/config.yml` |
|
||||
| Scriptorium executable | `/usr/local/bin/scriptorium` |
|
||||
| Scriptorium configuration | `/usr/local/etc/scriptorium/config.yml` |
|
||||
|
||||
- Relocating those coordinated paths is not a requirement for this feature.
|
||||
If a real deployment needs relocation, a later feature may introduce a
|
||||
small set of coherent suite path variables rather than exposing mismatched
|
||||
per-role overrides.
|
||||
- Notarius is installed because it is part of the suite, but
|
||||
`narratio_notarius_enabled` remains null until a later feature supplies a
|
||||
complete D&D Notarius pipeline and explicitly enables it.
|
||||
- Tasks requiring elevated access remain owned by the downstream roles and
|
||||
use their task-level `become: true`; the pipeline role does not require
|
||||
play-level escalation.
|
||||
|
||||
## Fixed Public Interface
|
||||
|
||||
| Variable | Default | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `dnd_pipeline_audita_version` | `v0.9.1` | Audita application revision selected for the compatible set |
|
||||
| `dnd_pipeline_narratio_version` | `v2.0.0` | Narratio application revision selected for the compatible set |
|
||||
| `dnd_pipeline_notarius_version` | `v0.6.0` | Notarius application revision selected for the compatible set |
|
||||
| `dnd_pipeline_seriatim_version` | `v1.5.0` | Seriatim application revision selected for the compatible set |
|
||||
| `dnd_pipeline_scriptorium_version` | `v0.13.0` | Scriptorium application revision selected for the compatible set |
|
||||
| `dnd_pipeline_manage_build_dependencies` | `true` | Whether every application role manages Git and Go |
|
||||
| `dnd_pipeline_go_snap_channel` | `1.26/stable` | Go Snap channel passed to every application role |
|
||||
| `dnd_pipeline_go_binary` | `/snap/bin/go` | Go executable passed to every application role |
|
||||
| `dnd_pipeline_whisperx_transcribe_url` | required | External WhisperX HTTP endpoint passed to Narratio |
|
||||
|
||||
Argument specifications type and document each value. The WhisperX URL is
|
||||
required because neither Narratio nor the suite has a valid universal
|
||||
endpoint. The suite version variables select application source revisions;
|
||||
they are separate from the Git revisions pinning the Ansible role
|
||||
dependencies.
|
||||
|
||||
The role intentionally has no raw map of arbitrary downstream variables and
|
||||
no parallel configuration template. Application-specific choices that are not
|
||||
part of this interface continue to use the standalone roles' documented
|
||||
variables.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
The implementation is primarily metadata:
|
||||
|
||||
1. Define the nine suite variables above in defaults and argument
|
||||
specifications, omitting a default for the required WhisperX URL.
|
||||
2. Declare the five named role dependencies in `meta/main.yml`, in the settled
|
||||
order, and pass each dependency its selected version plus the common
|
||||
dependency-management and Go values.
|
||||
3. Pass the WhisperX URL and standard downstream binary/configuration paths to
|
||||
the Narratio dependency.
|
||||
4. Add the Git-role and collection dependency manifests used by consumers and
|
||||
tests.
|
||||
5. Document installation, variables, dependency bootstrap, the boundary with
|
||||
application-specific variables, and an ordinary playbook example.
|
||||
6. Add a focused integration driver that installs dependencies in an isolated
|
||||
roles path, applies the real pipeline role, observes the assembled native
|
||||
application outcome, and requires immediate clean repeated convergence.
|
||||
|
||||
No custom tasks are required merely to prove that role dependencies ran. The
|
||||
pipeline role should not inspect downstream binaries, files, packages,
|
||||
checkouts, or registered task results during production convergence. It should
|
||||
not copy downstream defaults into facts or introduce an abstraction around
|
||||
ordinary role dependency metadata.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
Using declared role dependencies reflects the actual ownership boundary: each
|
||||
application role remains responsible for its own installation and native
|
||||
configuration, while the pipeline role selects and connects them. Rewriting
|
||||
or including copies of downstream tasks would couple the suite to their
|
||||
implementations and discard the independent-release model already selected.
|
||||
|
||||
A small suite-prefixed interface makes coordinated decisions explicit without
|
||||
creating five complete shadow interfaces. Version selection belongs here
|
||||
because the suite promises a compatible application set. Build dependency and
|
||||
Go choices are common because all five roles use the same source-build model.
|
||||
The WhisperX endpoint belongs here because it is required to construct the
|
||||
Narratio configuration and is deployment-specific.
|
||||
|
||||
The standard downstream paths are suite policy rather than configurable inputs
|
||||
for this first composition feature. Exposing every source, binary, and
|
||||
configuration path would add aliases and cross-variable consistency rules
|
||||
without a demonstrated consumer need. Advanced callers can still use
|
||||
unmapped application variables where they do not conflict with coordinated
|
||||
suite policy.
|
||||
|
||||
Keeping content, operators, secrets, and D&D processing definitions out of
|
||||
this feature avoids combining several unsettled interfaces with dependency
|
||||
composition. Those features can build on a running, natively valid application
|
||||
suite and receive focused roadmaps of their own.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Required Role Behavior
|
||||
|
||||
- A documented bootstrap command installs all five standalone roles from
|
||||
`requirements.yml` under their canonical names and installs the pinned
|
||||
collection dependency.
|
||||
- Applying the pipeline role with a valid
|
||||
`dnd_pipeline_whisperx_transcribe_url` invokes all five standalone roles and
|
||||
reaches their ordinary managed end state on Ubuntu 26.04 `amd64` or `arm64`.
|
||||
- The default suite selections install Audita `v0.9.1`, Narratio `v2.0.0`,
|
||||
Notarius `v0.6.0`, Seriatim `v1.5.0`, and Scriptorium `v0.13.0` as one
|
||||
compatible development set.
|
||||
- A caller can change each application revision through its corresponding
|
||||
`dnd_pipeline_*_version` variable.
|
||||
- The common dependency-management switch, Go channel, and Go executable are
|
||||
passed to all five roles without duplicating their installation tasks.
|
||||
- Narratio receives the required WhisperX URL and the standard executable and
|
||||
configuration paths for all four downstream applications.
|
||||
- Notarius is installed but is not enabled in the Narratio pipeline by this
|
||||
feature.
|
||||
- An immediate repeated role application with unchanged inputs reports no
|
||||
changes.
|
||||
- The role contains no copied application tasks or templates, downstream state
|
||||
probes, role-private state, custom dependency loader, or production
|
||||
self-validation.
|
||||
- Defaults, argument specifications, dependency metadata, manifests, and
|
||||
README remain aligned with the fixed interface.
|
||||
- No implementation repository other than `ansible-role-dnd-pipeline` is
|
||||
modified.
|
||||
|
||||
### Required Validation
|
||||
|
||||
- YAML syntax checking and production-profile ansible-lint pass for the role
|
||||
and its test playbooks.
|
||||
- The integration driver installs the five Git dependencies into a fresh,
|
||||
isolated role path from the same manifest documented for consumers.
|
||||
- One baseline application runs the real pipeline role with a test WhisperX
|
||||
URL, exercises each installed application through a practical native smoke
|
||||
or configuration command, validates Narratio's assembled configuration
|
||||
natively, and is followed immediately by a role application reporting no
|
||||
changes.
|
||||
- One representative application explicitly selects Seriatim `v1.4.0`
|
||||
through `dnd_pipeline_seriatim_version` and observes that selection through
|
||||
Seriatim's native version interface. This proves suite forwarding without
|
||||
asserting that any release remains the default or promising that arbitrary
|
||||
component combinations are compatible.
|
||||
- Tests do not repeat the standalone roles' missing-binary, custom-Go,
|
||||
template-branch, file-metadata, package, Git, or platform matrices.
|
||||
- Tests do not assert dependency task order, exact current default values,
|
||||
role-variable counts, individual task results, or trusted-module
|
||||
postconditions.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
The five application-role implementations and public interfaces are complete.
|
||||
The managed host must be able to reach their application source repositories,
|
||||
Ubuntu Snap infrastructure, Go module sources, and the caller-supplied
|
||||
WhisperX service.
|
||||
|
||||
After this foundation is implemented and reviewed, later pipeline-role
|
||||
features must settle and implement:
|
||||
|
||||
- prompt-library checkout and Scriptorium integration;
|
||||
- campaign checkout, revision policy, and deployment;
|
||||
- D&D-specific Audita, Notarius, Scriptorium, and Narratio policy;
|
||||
- operator-selection and group-membership behavior;
|
||||
- pipeline-wide secret delivery; and
|
||||
- an end-to-end pipeline validation scenario.
|
||||
|
||||
Collection assembly remains a separate feature after the standalone pipeline
|
||||
role has a stable contract. Before any released dependency manifest or
|
||||
collection is published, the standalone roles must receive immutable release
|
||||
tags and the development commit pins must be replaced by those tags.
|
||||
|
||||
The D&D-policy follow-up must inspect the asset repositories and current
|
||||
application contracts, select concrete suite defaults for all five
|
||||
applications, and document how callers override them. It should reuse the
|
||||
standalone roles' field-specific variables rather than adding pipeline-owned
|
||||
configuration templates or duplicating every downstream setting behind a new
|
||||
alias.
|
||||
|
||||
## Potential Future Hardening
|
||||
|
||||
- Verify signed role or application releases.
|
||||
- Apply an allowlist to dependency or application repository origins.
|
||||
- Add policy for hosts whose installed dependency roles differ from the
|
||||
manifest used by the controller.
|
||||
Reference in New Issue
Block a user