ansible-workspace-dnd/docs/roadmap/features/0004-scriptorium-source-installation-and-configuration.md

# Feature 0004: Scriptorium Source Installation and Configuration

Status: done

## Summary

Provide a small, independently usable `rakestraw.scriptorium` role that
installs Scriptorium from a pinned Git tag, builds its executable on the
managed host, and manages its native YAML configuration. Preserve
Scriptorium's usefulness inside and outside the D&D transcript pipeline by
keeping application configuration in the standalone role and leaving prompt
library content and suite policy to their eventual owners.

## Problem or Opportunity

The `ansible-role-scriptorium` repository contains only its initial README and
license. Scriptorium is one of the five applications required by the pipeline,
but it is also a generally useful Promptkit-based application with independent
consumers. It needs a complete standalone installation and configuration role
before the pipeline role can compose it without owning Scriptorium-specific
behavior.

The completed Seriatim, Audita, and Notarius roles establish the concise
source-build pattern. Scriptorium can reuse that pattern while exposing its own
configuration contract through field-specific, nullable variables.

## Governing Policies

- [The Ansible house style](../../ansible.md) governs the role implementation,
  public configuration interface, and template.
- [The testing house style](../../testing.md) governs repository-local
  validation. Tests exercise role-owned behavior through public inputs and
  native application outcomes without snapshotting defaults, tracing tasks, or
  rechecking trusted-module postconditions.
- [The MVP roadmap](../mvp.md) fixes the common source-build architecture,
  supported platform, filesystem layout, and standalone-role boundary.

## Scope

- Implement `ansible-role-scriptorium` as a conventional standalone role.
- Support Ubuntu 26.04 on native `amd64` and `arm64` hosts.
- Install Git and the official Go Snap with classic confinement when build
  dependency management is enabled.
- Default the Go Snap channel to `1.26/stable`.
- Check out immutable Scriptorium tag `v0.13.0` by default under
  `/usr/local/src/scriptorium`.
- Build the native executable with Scriptorium's release build contract and
  install it at `/usr/local/bin/scriptorium`.
- Rebuild when the Git checkout changes or the binary is absent.
- Converge the source tree to `root:root` ownership and the installed binary to
  `root:root` ownership and mode `0755`.
- Manage `/usr/local/etc/scriptorium/config.yml` as `root:root` with mode
  `0644` using one role-owned template.
- Render `{}` when no application settings are selected, allowing Scriptorium
  to use its built-in defaults without copying them into Ansible.
- Expose every application configuration field through a field-specific role
  variable. Default each field to null and omit it from the rendered document
  until a caller supplies a non-null value.
- Expose the native open-ended `backends` mapping as one nullable variable and
  serialize the caller's mapping without inventing a second backend schema or
  merge mechanism.
- Keep defaults, argument specifications, README, metadata, collection
  dependency declaration, template, and focused integration tests aligned with
  this contract.

## Non-goals

- D&D-specific prompts, profiles, schemas, model choices, paths, or other
  pipeline policy.
- Cloning, copying, or otherwise populating prompt, profile, or schema
  libraries.
- A role-managed Scriptorium service, HTTP listener lifecycle, scheduler, or
  persistent runtime account.
- A raw mapping for the complete configuration document, a template override,
  or parallel configuration interfaces.
- Copying Scriptorium's documented built-in defaults into role defaults merely
  to render them back into YAML.
- Decomposing the open-ended `backends` mapping into variables for each backend
  ID or backend-specific option.
- Secret values, environment files, or another credential-delivery mechanism.
- Installation or configuration of Promptkit, another pipeline application,
  or the complete D&D suite.
- Installation from Scriptorium's published binary artifacts, cross-compiling,
  or supporting platforms outside the MVP.
- Production execution of Scriptorium to validate its binary or configuration.
- Detection of out-of-band binary modification, compiler changes, or fixed
  build-command changes.
- Build fingerprints, checksums, sidecar state, staged replacement, manual Git
  cleanup, or special recovery for malformed or adversarial host state.

## Target End State

On a supported host, applying the role with defaults installs or confirms Git
and Go, checks out Scriptorium `v0.13.0` at
`/usr/local/src/scriptorium`, builds `/usr/local/bin/scriptorium`, and manages
`/usr/local/etc/scriptorium/config.yml`. The managed configuration is the empty
mapping `{}`, so Scriptorium retains ownership of all application defaults.

When a caller sets an optional configuration variable, the corresponding
native YAML field appears in the correct section. Null fields are absent, as
are parent mappings with no selected descendants. Explicit false, zero, empty
string, empty collection, and other non-null values are serialized rather than
silently omitted, leaving their native semantics to Scriptorium.
`scriptorium_backends` represents the complete native `backends` field as a
mapping keyed by backend ID; the role does not rewrite its nested definitions
or combine fragments. Callers and composing roles may construct the final
mapping with ordinary inventory and Jinja expressions.

Prompt, profile, and schema directories remain caller-provided application
inputs. The standalone role exposes their configuration paths but does not
populate them. A later pipeline feature will deploy the maintained prompt
library and pass its selected locations through this public interface.

An immediate repeated application reports no changes. A changed checkout or a
missing binary causes the build command to run. Configuration changes converge
through the template without becoming build triggers.

## Repository Ownership

- `ansible-role-scriptorium` owns the role implementation, public variables,
  native configuration serialization, metadata, dependency declaration,
  documentation, and repository-local tests.
- `../scriptorium` is the read-only authority for release, build, CLI, and
  configuration contracts.
- `rakestraw-ansible` is a read-only style and historical deployment reference.
- `ansible-role-dnd-pipeline` will later own D&D-specific Scriptorium values and
  prompt-library deployment through the standalone role's public interface.
- `ansible-workspace-dnd` owns this roadmap, the eventual staged implementation
  plan, and aggregate status.
- All other repositories remain unchanged.

## Constraints and Settled Decisions

- The selected default release is annotated tag `v0.13.0`, resolving to commit
  `f33af205242cbaeeb689c179c0465bd10beaa1a3`.
- The release declares Go 1.25.5. The suite-standard `1.26/stable` Go Snap
  channel satisfies that requirement.
- The native build uses package `./cmd/scriptorium`, `CGO_ENABLED=0`,
  `GOWORK=off`, `GOTOOLCHAIN=local`, `-trimpath`, and linker flags `-s -w`.
- Scriptorium does not embed the selected application tag and does not expose a
  native application-version command. Production convergence does not add
  version interrogation, and tests do not inspect the Git checkout merely to
  manufacture version evidence.
- Scriptorium accepts an empty configuration and resolves all omitted settings
  from built-in defaults. The role renders `{}` so the managed file is an
  explicit YAML mapping while selecting no application policy.
- Configuration discovery checks `/usr/local/etc/scriptorium/config.yml`
  before `/etc/scriptorium/config.yml`; the role manages the first path.
- Optional variables use YAML null defaults and template conditions use
  `is not none`. Parent mappings are emitted only when at least one descendant
  is non-null.
- Strings and mappings are serialized with Ansible or Jinja filters rather
  than hand-written YAML quoting.
- `scriptorium_backends` is a native open-ended mapping. Caller-side mapping
  composition is permitted, but the role supplies no merge or precedence
  behavior.
- Backend configuration may name a credential environment variable through
  `api_key_env`; secret values themselves remain outside the role and managed
  file.
- Tasks installing dependencies or managing root-owned state use task-level
  `become: true`.
- `community.general` supplies Snap management and is pinned to version
  `13.3.0` in the role's collection requirements.

## Fixed Public Interface

Provide these installation variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `scriptorium_version` | `v0.13.0` | Selected Git revision |
| `scriptorium_repository_url` | `https://gitea.maximumdirect.net/eric/scriptorium.git` | Source repository |
| `scriptorium_source_dir` | `/usr/local/src/scriptorium` | Managed source checkout |
| `scriptorium_binary_path` | `/usr/local/bin/scriptorium` | Installed executable |
| `scriptorium_manage_build_dependencies` | `true` | Whether to install Git and Go |
| `scriptorium_go_snap_channel` | `1.26/stable` | Go Snap channel |
| `scriptorium_go_binary` | `/snap/bin/go` | Go executable used for the build |
| `scriptorium_config_path` | `/usr/local/etc/scriptorium/config.yml` | Managed configuration file |

Provide these nullable configuration variables:

| Variable | Native field |
| --- | --- |
| `scriptorium_prompt_dir` | `prompt_dir` |
| `scriptorium_profile_dir` | `profile_dir` |
| `scriptorium_schema_dir` | `schema_dir` |
| `scriptorium_server_addr` | `server.addr` |
| `scriptorium_server_artifact_root` | `server.artifact_root` |
| `scriptorium_server_max_request_bytes` | `server.max_request_bytes` |
| `scriptorium_server_max_artifact_bytes` | `server.max_artifact_bytes` |
| `scriptorium_server_max_response_bytes` | `server.max_response_bytes` |
| `scriptorium_defaults_render_format` | `defaults.render_format` |
| `scriptorium_backends` | `backends` |

Argument specifications type paths and strings according to their native
shape, the three server limits as integers, and `scriptorium_backends` as a
mapping. They do not reproduce semantic validation owned by Scriptorium. The
role preserves non-null values while the application decides whether a
selected value is valid or effective.

## Simplest Viable Implementation

The expected production implementation is approximately nine ordinary tasks
in one readable task file:

1. Assert Ubuntu 26.04 and architecture `x86_64` or `aarch64`.
2. Install Git with `ansible.builtin.apt`, including
   `cache_valid_time: 3600`, when dependency management is enabled.
3. Install the classic Go Snap from `scriptorium_go_snap_channel` with
   `community.general.snap` when dependency management is enabled.
4. Create the source, binary, and configuration parent directories with one
   `ansible.builtin.file` loop.
5. Check out `scriptorium_version` with `ansible.builtin.git`, `force: true`,
   and register the module result.
6. Inspect whether `scriptorium_binary_path` exists with
   `ansible.builtin.stat`.
7. Run the native Go build through `scriptorium_go_binary` when the checkout
   changed or the binary is absent.
8. Converge recursive source ownership and binary ownership and mode with one
   item-driven `ansible.builtin.file` loop.
9. Render the field-specific configuration with one
   `ansible.builtin.template` task.

Use `argv` for the build command, declare its change semantics, and put its two
conditions directly on the task. Do not add a rebuild fact, handler, executable
discovery, compiler or application interrogation, configuration assembly facts,
preliminary configuration probes, or post-operation validation to production
tasks.

## Rationale and Alternatives

A standalone role is valuable beyond the D&D pipeline and prevents the suite
role from becoming the owner of Scriptorium's native application interface.
The suite can later provide opinionated directory paths and backend choices
without reducing the role's usefulness to independent consumers.

Field-specific nullable variables preserve a documented and typed inventory
interface while allowing upstream defaults to evolve. Rendering `{}` is
preferable to copying those defaults into Ansible and is more explicit than an
empty file. Conditional sections distinguish omission from intentional falsey
values.

The `backends` mapping is the deliberate exception to leaf-level variables.
Its keys are caller-defined backend IDs and its values follow an extensible
native schema. Passing that one native field through as a mapping is simpler
and more useful than inventing variables for arbitrary IDs, while still
avoiding a raw mapping for the complete configuration document.

The role exposes server configuration because it is part of Scriptorium's
native interface, but it does not infer that callers want a managed service.
Consumers may invoke the CLI directly or arrange their own process lifecycle.

Scriptorium now publishes binary release artifacts, but the MVP deliberately
uses the common source-build model across all five applications. Artifact-based
installation remains a later cross-suite decision.

## Acceptance Criteria

### Required Role Behavior

- The role rejects unsupported platforms before modifying application state.
- On a supported host, it installs the selected Scriptorium source release and
  builds the binary with the upstream release contract.
- Source, binary, and configuration state converge to the paths, ownership,
  and modes selected above through the responsible Ansible modules.
- With no configuration variables selected, the template renders `{}` and
  Scriptorium accepts the managed file while retaining its built-in defaults.
- Each non-null configuration variable renders its corresponding native field.
  Null fields and empty parent sections are omitted, while intentional falsey
  values are retained.
- A caller-supplied backend mapping is rendered without structural rewriting,
  and independently defined mappings can be composed before assignment.
- A changed checkout or missing binary causes the imperative build to run. An
  immediate repeated application with unchanged inputs reports no changes.
- Dependency opt-out accepts a caller-supplied `scriptorium_go_binary`.
- Root-owned operations use task-level privilege escalation; play-level
  escalation is not required.
- Defaults, argument specifications, template behavior, README, and metadata
  remain aligned with the public interface.
- Production tasks contain no role-private state, redundant probes,
  application self-tests, or speculative guarantees.
- No repository other than `ansible-role-scriptorium` and the workspace control
  repository is modified.

### Required Validation

- Syntax checking and production-profile ansible-lint pass.
- A default invocation exercises the installed application with the managed
  configuration, followed immediately by a role application reporting no
  changes. It does not snapshot the role's current default tag or complete
  default document.
- One recovery case removes the binary, disables dependency management,
  supplies a caller-selected Go executable, confirms that executable is used,
  and finishes with a clean repeated application.
- One representative configuration case verifies selected scalar and nested
  values, selected omissions, intentional zero values, and a caller-supplied
  backend mapping. An offline native Scriptorium command accepts and uses the
  managed configuration, and an immediate repeated application reports no
  changes.
- Tests do not assert task names or order, individual task results, exact
  current defaults, complete configuration snapshots, public-variable counts,
  trusted-module file or package postconditions, or an exhaustive negative
  platform matrix.
- Because Scriptorium exposes no native application release identity, the test
  suite does not substitute a Git-checkout assertion or version-specific
  behavior snapshot for a native version-selection test.

## Dependencies and Follow-up Work

The managed host requires access to the Scriptorium Git repository, Ubuntu
Snap infrastructure, and Go module sources. Useful prompt execution also needs
prompt definitions and, depending on the chosen configuration, profiles,
schemas, backend endpoints, and credential environment variables. Those inputs
remain caller responsibilities for this standalone feature.

With this feature complete, the Narratio standalone role can be designed
against all four downstream application-role interfaces. The later pipeline
role will install maintained prompt-library content and supply D&D-specific
Scriptorium configuration through this role.

The role was implemented in `ansible-role-scriptorium` commits `90d7f45` and
`5944eac`, then finalized after independent review by remediation commit
`8f47aa8`. Its complete integration suite passes.

## Potential Future Hardening

- Build into a temporary path before replacing the installed executable.
- Verify source signatures or release artifacts.
- Detect compiler, build-command, or out-of-band binary changes.
- Validate configuration during production convergence.
- Manage a service, runtime account, secret environment, or network controls if
  later operating requirements select them.
- Support Scriptorium's published binary artifacts as part of a future
  suite-wide installation-model change.
- Add broader platform coverage only when supported-platform behavior expands.