151 lines
7.4 KiB
Markdown
151 lines
7.4 KiB
Markdown
# Feature 0018: Adopt Scriptorium v0.15.0 in the Standalone Role
|
|
|
|
Status: in_progress
|
|
|
|
## Summary
|
|
|
|
Update the standalone Scriptorium role from v0.13.0 to v0.15.0 and expose its
|
|
new application-configuration settings using our existing nullable-variable
|
|
conventions. This is the first feature in the agreed
|
|
[application upgrade sequence](../application-upgrade-sequence.md).
|
|
|
|
## Problem or Opportunity
|
|
|
|
Although v0.15.0 primarily changes licensing and dependency versions, the
|
|
intervening v0.14.0 adopted ConfigKit and added application imports, overlays,
|
|
inspection, and transient retry controls. A version bump alone would leave
|
|
new configuration settings unavailable through the role's public interface.
|
|
|
|
The current role already emits `{}` for an unconfigured installation, omits
|
|
null optional fields, serializes mappings, and retains explicit falsey values.
|
|
Those practices remain compatible with the stricter upstream configuration
|
|
contract; no new production validation or migration mechanism is needed.
|
|
|
|
## Scope
|
|
|
|
- Adopt v0.15.0 as the standalone role's default source version.
|
|
- Expose ConfigKit imports and the application transient-retry setting.
|
|
- Confirm existing configuration variables and representative backend mappings
|
|
remain usable with the new application version.
|
|
- Update role documentation and focused offline integration coverage.
|
|
- Record completion and the role revision for later coordinated integration.
|
|
|
|
## Non-goals
|
|
|
|
- Changing pipeline, collection, consumer, or other application-role pins.
|
|
- D&D model choices, production/testing policy, or new provider credentials.
|
|
- Deploying prompt/profile/schema libraries or managing arbitrary overlay files.
|
|
- Selecting a runtime overlay for callers, managing a service, or adding HTTP
|
|
request/CLI-only controls such as execution reports and run deadlines to YAML.
|
|
- Upstream application changes, paid inference, or operational host deployment.
|
|
- Relicensing this Ansible role or copying upstream source/license material
|
|
into the role repository merely because the installed application changed.
|
|
|
|
## Target End State
|
|
|
|
### Installation and Existing Configuration
|
|
|
|
`scriptorium_version` defaults to `v0.15.0`. Retain the existing source checkout,
|
|
Go build, ownership, and permission behavior and the caller-selected version
|
|
interface. No build-toolchain change is required: the current Go 1.26 selection
|
|
satisfies the release's Go requirement.
|
|
|
|
Existing application fields keep their public variable names. Optional variables
|
|
remain null by default and are omitted; explicit supported zero/empty values
|
|
are serialized without truthiness checks. An installation with no application
|
|
settings still receives `{}`, not an empty file.
|
|
|
|
### New Public Variables
|
|
|
|
| Variable | Default | Rendered field |
|
|
| --- | --- | --- |
|
|
| `scriptorium_configkit_imports` | `null` | `configkit.imports` |
|
|
| `scriptorium_transient_retries` | `null` | `transient_retries` |
|
|
|
|
Imports are a native list of mapping entries, consistent with the other roles'
|
|
ConfigKit interfaces. Serialize the supplied list without reinterpreting path,
|
|
glob, or optional-entry semantics. Emit the parent section only when selected.
|
|
The caller owns referenced fragment and overlay files; ordinary inventory can
|
|
compose the list without a second raw-configuration interface.
|
|
|
|
Transient retries is an optional integer. Null means omit and inherit the
|
|
application/PromptKit default; zero explicitly disables additional transient
|
|
attempts. The standalone role does not freeze the upstream default or add a
|
|
retry budget of its own. Argument specifications and documentation describe
|
|
both variables consistently.
|
|
|
|
### Compatibility Guidance
|
|
|
|
Document the distinction between ConfigKit `overlays/` selected by
|
|
`--config-overlay` and PromptKit LLM profiles. Imports are configuration-root
|
|
relative, while application path values retain their process-working-directory
|
|
semantics. Link upstream for detailed validation and precedence rules.
|
|
|
|
Call out stricter YAML acceptance and changed retry behavior, plus the removal
|
|
of legacy DeepSeek catalog IDs, without installing compatibility aliases or
|
|
inventing role-side configuration guards. New fields should only be supplied
|
|
when selecting an application version that supports them.
|
|
|
|
Mention that Scriptorium v0.15.0's application grant is GPL-3.0-or-later and link
|
|
its tagged licensing notices. Do not conflate the application's grant with the
|
|
role's license or introduce legal approval as a deployment gate.
|
|
|
|
## Repository Ownership
|
|
|
|
- `ansible-role-scriptorium`: default version, variables, argument specification,
|
|
template, README, and repository-local tests.
|
|
- Workspace: feature roadmap, staged plan, progress, and review evidence.
|
|
- Scriptorium application: read-only tagged configuration/release contracts.
|
|
- Pipeline, collection, consumer, and asset repositories remain unchanged.
|
|
|
|
## Constraints and Settled Decisions
|
|
|
|
Follow the [Ansible house style](../../ansible.md),
|
|
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
|
|
[upgrade sequence](../application-upgrade-sequence.md). Review the tagged
|
|
v0.15.0 contract rather than assuming later application changes apply.
|
|
|
|
The existing suite continues installing its current Scriptorium role/application
|
|
pins until final integration. Standalone adoption is not suite publication.
|
|
|
|
## Simplest Viable Implementation
|
|
|
|
Update the version default and extend the existing defaults, argument
|
|
specification, and single configuration template with the two optional fields.
|
|
Include both in the empty-document condition. Reuse the existing source/build
|
|
and file/template tasks unchanged. No additional runtime tasks are needed.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- The default role installs v0.15.0 and native offline configuration validation
|
|
accepts the default and representative managed configurations.
|
|
- Representative non-null and falsey values remain correctly rendered; the new
|
|
retry field preserves explicit zero and is omitted when unset.
|
|
- A caller-supplied import is composed successfully by native configuration
|
|
inspection using a small externally supplied test fragment. An optional test
|
|
overlay can demonstrate native composition without adding role-owned overlay
|
|
management or retesting ConfigKit's complete precedence/error matrix.
|
|
- Existing offline profile/backend inspection remains useful and passes.
|
|
Application validation alone does not prove PromptKit source validity.
|
|
- Immediate repeated role application reports no changes. Tests assert supplied
|
|
configuration outcomes, not today's upstream/default version, catalog contents,
|
|
task arrangement, or file-module postconditions.
|
|
- Syntax/lint and repository integration checks pass without provider calls,
|
|
real secrets, or operational controller access.
|
|
- Suite and consumer pins remain unchanged, and completion identifies the role
|
|
commit available for the final integration feature.
|
|
|
|
## Dependencies and Follow-up Work
|
|
|
|
The staged implementation is recorded in
|
|
[implementation.md](../implementation.md) and awaits independent review.
|
|
Audita adoption follows review and closeout. The eventual suite integration
|
|
feature owns propagation of the new role revision, deployment settings, and
|
|
coordinated upgrade guidance.
|
|
|
|
## Upstream References
|
|
|
|
- [v0.15.0 configuration](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/config.md)
|
|
- [v0.14.0 migration notes](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.14.0/docs/releases/v0.14.0.md)
|
|
- [v0.15.0 release and licensing notes](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/releases/v0.15.0.md)
|