250 lines
12 KiB
Markdown
250 lines
12 KiB
Markdown
# Initial Roadmap
|
|
|
|
## Purpose
|
|
|
|
This document records the decisions that define the initial MVP of the
|
|
Narratio Ansible roles and D&D collection. It is the durable reference for
|
|
choices that have been settled while the suite is being designed. Open
|
|
questions and later ideas should remain clearly distinguished from these
|
|
locked decisions.
|
|
|
|
## MVP Goal
|
|
|
|
Build independently usable Ansible roles for the five Narratio applications
|
|
and compose them through a suite-level role developed in its own repository.
|
|
The `rakestraw.dnd` collection exposes that role as `rakestraw.dnd.pipeline`.
|
|
The suite-level role installs and configures the complete D&D transcript
|
|
processing pipeline on a single supported host. Human operators invoke
|
|
Narratio commands directly to process D&D session recordings and produce
|
|
transcripts and related artifacts.
|
|
|
|
## Locked Decisions
|
|
|
|
### Supported platform
|
|
|
|
- The MVP supports Ubuntu 26.04.
|
|
- The MVP supports both `amd64` and `arm64` hosts.
|
|
- The roles should be structured so support for additional distributions and
|
|
releases can be added after the MVP without redesigning them.
|
|
|
|
### Managed applications
|
|
|
|
The suite-level role installs and configures all five applications in the
|
|
Narratio suite:
|
|
|
|
- Narratio
|
|
- Notarius
|
|
- Audita
|
|
- Seriatim
|
|
- Scriptorium
|
|
|
|
WhisperX is an external HTTP service consumed by Narratio. Deploying or
|
|
managing the WhisperX service is outside the MVP scope, although the Narratio
|
|
role will manage the native configuration needed to connect to it.
|
|
|
|
### Application installation
|
|
|
|
- The MVP builds all five applications from their official Git repositories on
|
|
the target host. This consistent model avoids making the suite depend on
|
|
every upstream project publishing prebuilt artifacts.
|
|
- Released roles build an explicitly selected application release tag.
|
|
Development may override the selected revision with a branch or commit.
|
|
- Source checkouts reside at `/usr/local/src/<app>` and are owned by `root`.
|
|
- Roles build and install the binary at `/usr/local/bin/<app>` with
|
|
`root:root` ownership and mode `0755`, using the application's native build
|
|
command and the simplest clear Ansible task flow.
|
|
- Builds use the application repository's own build contract, including any
|
|
application-specific version-injection linker flags. The common baseline is
|
|
`GOWORK=off`, `GOTOOLCHAIN=local`, `CGO_ENABLED=0`, and `-trimpath`.
|
|
- Roles normally rebuild when the Git task reports a changed checkout, the
|
|
binary is absent, or an application-level version or smoke check shows that
|
|
the installed binary is unsuitable. They do not maintain fingerprints,
|
|
checksums, or sidecar build-state files for the MVP.
|
|
- Each application role exposes variables only for meaningful consumer
|
|
choices, normally including its repository, selected version or revision,
|
|
source directory, binary path, dependency management, and Go Snap channel.
|
|
Fixed details of the upstream build contract need not become public
|
|
variables.
|
|
|
|
### Go toolchain
|
|
|
|
- Go is installed on the target host through the official Snap package using
|
|
classic confinement.
|
|
- The Snap channel is configurable and should track an explicit Go minor
|
|
release channel, rather than unconstrained `latest/stable`, when that channel
|
|
is available for the required Go version.
|
|
- The installed Go toolchain must satisfy the application's `go.mod`
|
|
requirement. Builds set `GOTOOLCHAIN=local` so provisioning does not silently
|
|
download a different toolchain.
|
|
- Each standalone application role can install its own build prerequisites and
|
|
exposes a variable allowing that behavior to be disabled. Repeating an
|
|
idempotent prerequisite task across the small roles is preferable to adding
|
|
a shared-role dependency during the MVP.
|
|
|
|
### Role and collection architecture
|
|
|
|
- All Ansible roles and collections in this suite use the root namespace
|
|
`rakestraw`.
|
|
- Each of the five managed applications has a separate, targeted Ansible role
|
|
in its own repository.
|
|
- Each application role owns installation and native configuration of that
|
|
application.
|
|
- The Narratio application role remains application-specific even though
|
|
Narratio is the runtime orchestrator for the full pipeline.
|
|
- The suite-level role is developed in the standalone
|
|
`ansible-role-dnd-pipeline` repository rather than directly in the collection
|
|
repository.
|
|
- The application and pipeline roles are independently developed, tested,
|
|
versioned, and released. An application-specific change therefore requires a
|
|
release of that application's role without requiring changes or releases in
|
|
unrelated role repositories.
|
|
- The collection is named `rakestraw.dnd`.
|
|
- The collection bundles and exposes the independently developed suite-level
|
|
role as `rakestraw.dnd.pipeline`, providing one opinionated interface for
|
|
consumers.
|
|
- The pipeline role owns compatible application-version selection,
|
|
cross-application configuration, D&D campaign deployment, prompt-library
|
|
deployment, operator access, the pipeline-wide secret-delivery policy, and
|
|
end-to-end validation.
|
|
- The pipeline role uses the Git-hosted standalone application roles as
|
|
dependencies. This is an intentional choice for the controlled project
|
|
environment despite the additional repository and dependency structure and
|
|
Ansible's preference for published collection dependencies.
|
|
- Consumer installation may require a dependency manifest or bootstrap step
|
|
that installs both the collection and its standalone role dependencies; a
|
|
plain collection installation is not assumed to resolve arbitrary Git role
|
|
dependencies by itself.
|
|
|
|
This design keeps repository ownership and change blast radius aligned with
|
|
the independently released applications while retaining a single opinionated
|
|
installation interface for the complete suite. It avoids forcing each small
|
|
role to become its own published collection and avoids coupling unrelated
|
|
application-role releases in one source repository.
|
|
|
|
### Ansible dependencies and task structure
|
|
|
|
- The standalone application roles are independently usable and prefer
|
|
`ansible.builtin` modules where they directly fit the task.
|
|
- `community.general` is treated as a stable, supported dependency. Roles may
|
|
freely select its modules when appropriate, provided the collection
|
|
dependency is declared and pinned for reproducible installation and tests.
|
|
- The roles do not depend on the private
|
|
`maximumdirect.core.ansible_role_loader` role used by the proof of concept.
|
|
- Platform-specific task selection may be added later using ordinary Ansible
|
|
includes when another supported platform creates a concrete need.
|
|
- Small amounts of repeated prerequisite or installation logic are acceptable
|
|
during the MVP. A shared helper role or collection plugin should be
|
|
introduced only if substantial, stable shared behavior emerges.
|
|
- Ansible modules are trusted to implement their documented state transitions,
|
|
idempotence, and change detection. Roles do not add preliminary existence
|
|
checks, manual comparisons, or supplemental state around a module that
|
|
already owns the desired behavior.
|
|
- State gathering is appropriate only when it controls behavior outside the
|
|
responsible module's contract, such as deciding whether an application
|
|
binary must be rebuilt.
|
|
|
|
### Dependency and release reproducibility
|
|
|
|
- Development dependency manifests may temporarily refer to branches or
|
|
commits while the roles are changing rapidly.
|
|
- Every released dependency manifest must pin each Git-hosted role dependency
|
|
to an immutable role release tag.
|
|
- The collection release is the compatibility record for the exact set of
|
|
application-role versions it composes.
|
|
- Collection integration tests must install and exercise the same pinned role
|
|
combination delivered to consumers, starting from an environment in which
|
|
the dependencies are not already installed.
|
|
- Updating one application role in the suite requires updating its pinned
|
|
version in the collection, validating the assembled suite, and releasing a
|
|
new collection version. Unrelated application-role repositories remain
|
|
unchanged.
|
|
|
|
### Prompt library
|
|
|
|
- The pipeline role installs Narratio's PromptKit-compatible prompt library
|
|
from the `narratio-prompts` Git repository. The Scriptorium role owns its
|
|
native prompt, profile, and schema directory configuration, while the
|
|
pipeline role owns populating those locations with suite integration
|
|
content.
|
|
- The upstream repository is
|
|
`https://gitea.maximumdirect.net/eric/narratio-prompts`.
|
|
- For the MVP, the pipeline role tracks and pulls the latest upstream commit.
|
|
- Pinning the prompt library to a version or release is deferred until the
|
|
upstream repository provides versioned releases.
|
|
|
|
### Accounts, ownership, and operator access
|
|
|
|
- The roles create a dedicated `narratio` user and `narratio` group as needed.
|
|
- The `narratio` account owns Narratio's writable runtime directories.
|
|
- Application source trees and installed binaries are owned by `root` and are
|
|
not writable by operators or the runtime account.
|
|
- Ordinary human users run `narratio run` and other Narratio commands directly.
|
|
- Those operators receive the required access by membership in the `narratio`
|
|
group.
|
|
- Managed configuration should be owned by `root`, readable by the `narratio`
|
|
group where needed, and remain under Ansible control rather than being
|
|
routinely edited by operators on the host.
|
|
- Shared runtime directories must grant the `narratio` group the write access
|
|
needed for direct operator invocations.
|
|
|
|
### Execution model
|
|
|
|
- Narratio is installed as a command-line application, not a persistent
|
|
daemon.
|
|
- Scheduling Narratio invocations through cron, systemd timers, or another
|
|
automation mechanism is not currently part of the locked MVP scope.
|
|
|
|
## Expected Filesystem Areas
|
|
|
|
The roles align with the applications' established default locations unless a
|
|
later design decision changes them:
|
|
|
|
- `/usr/local/etc/narratio` for Narratio configuration
|
|
- `/usr/local/etc/audita/config.yml` for Audita configuration
|
|
- `/usr/local/etc/notarius/config.yml` for Notarius configuration
|
|
- `/usr/local/etc/scriptorium/config.yml` for Scriptorium configuration
|
|
- `/usr/local/share/narratio/campaigns` for version-controlled campaign data
|
|
- `/usr/local/src/<app>` for root-owned application source checkouts
|
|
- `/usr/local/bin/<app>` for root-owned application binaries
|
|
- `/var/lib/narratio` for durable workspace and session state
|
|
- `/var/spool/narratio` for spool data
|
|
- `/var/cache/narratio` for cached data
|
|
|
|
The Narratio role creates and configures the campaign root; the pipeline role
|
|
populates it from the selected campaign source. `/usr/local/share` assumes Git
|
|
is authoritative and operators do not edit campaign content directly on the
|
|
managed host. The exact prompt-library checkout and installed-content paths
|
|
remain to be designed.
|
|
|
|
## Deferred Beyond the MVP
|
|
|
|
- Linux distributions and Ubuntu releases other than Ubuntu 26.04
|
|
- Architectures other than `amd64` and `arm64`
|
|
- Installation from prebuilt application release artifacts
|
|
- Deploying or managing WhisperX
|
|
- Versioned Narratio prompt-library releases and pinning
|
|
- A role-managed scheduler or persistent Narratio service
|
|
- Cryptographic artifact verification, supply-chain hardening, and protection
|
|
against adversarial source or dependency infrastructure
|
|
- Transactional binary replacement and preservation of the prior executable
|
|
after a local build failure
|
|
- Compiler-identity fingerprints, binary checksums, sidecar build-state files,
|
|
and recovery from deliberately malformed or redirected managed paths
|
|
|
|
## Design Work Still Open
|
|
|
|
The following areas require investigation and decisions before implementation:
|
|
|
|
- Exact application repository URLs, default release tags, build commands,
|
|
version-injection flags, and validation commands
|
|
- Standalone role Galaxy names and the dependency-manifest/bootstrap layout
|
|
- The mechanism used to incorporate the independently developed pipeline role
|
|
into collection releases
|
|
- Configuration contracts and filesystem requirements of Notarius, Audita,
|
|
Seriatim, and Scriptorium
|
|
- The prompt-library destination and its integration with Scriptorium
|
|
- Secret injection and storage
|
|
- Operator-group membership variables and directory permission details
|
|
- Upgrade, downgrade, and removal behavior
|
|
- Ansible dependency, validation, and test strategy
|