Prepare the Narratio upgrade implementation sprint
This commit is contained in:
214
docs/roadmap/features/0021-narratio-v3-adoption.md
Normal file
214
docs/roadmap/features/0021-narratio-v3-adoption.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Feature 0021: Adopt Narratio v3.0.0 in the Standalone Role
|
||||
|
||||
Status: ready
|
||||
|
||||
## Summary
|
||||
|
||||
Update the standalone Narratio role from v2.2.0 to v3.0.0 and align its
|
||||
configuration interface with the new Audita and Notarius contracts. This is
|
||||
the fourth feature in the agreed
|
||||
[application upgrade sequence](../application-upgrade-sequence.md). Suite
|
||||
integration remains a separate, subsequent feature.
|
||||
|
||||
## Problem or Opportunity
|
||||
|
||||
Narratio v3 replaces configuration-profile terminology with overlays, replaces
|
||||
singular downstream credential references with lists, and delegates Audita v2
|
||||
configuration to Audita. The existing role still exposes retired fields that
|
||||
v3 rejects. Advancing only the executable would therefore leave callers and
|
||||
the representative configuration fixture with an incompatible interface.
|
||||
|
||||
## Scope
|
||||
|
||||
- Default the standalone role to Narratio v3.0.0.
|
||||
- Align defaults, argument specifications, template, examples, and tests with
|
||||
the changed downstream configuration fields.
|
||||
- Document operator migration, ownership boundaries, and native compatibility
|
||||
consequences without automating session or asset migration.
|
||||
- Record the independently reviewed role revision for final suite integration.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Updating pipeline, collection, consumer, or other application-role pins.
|
||||
- Deploying downstream applications, changing D&D defaults, or migrating
|
||||
suite-owned testing overlays and credentials.
|
||||
- Creating arbitrary overlay assets or selecting Narratio's runtime overlay
|
||||
through an installer variable.
|
||||
- Compatibility aliases, dual-version template branches, automatic migration
|
||||
of existing manifests, cache deletion, or forced stage reruns.
|
||||
- New production validation, credential discovery, runtime version gates,
|
||||
forwarding/redaction machinery, or upstream application changes.
|
||||
- Live providers, operational deployment, or publication.
|
||||
|
||||
## Target End State
|
||||
|
||||
### Standalone Installation
|
||||
|
||||
`narratio_version` defaults to `v3.0.0`. Preserve source-build behavior, Go
|
||||
selection, service account, filesystem paths, owner/group/mode interfaces, and
|
||||
the required caller-supplied WhisperX URL. Configuration continues to use the
|
||||
existing root document shape and one ordinary template task. Unchanged native
|
||||
fields and caller composition remain supported.
|
||||
|
||||
### Audita Interface
|
||||
|
||||
Add the following optional variables with null defaults. Field paths below
|
||||
refer to the root configuration document's `audita` section; upstream prose
|
||||
also calls this `pipeline.audita`.
|
||||
|
||||
| Role variable | Native field | Argument type |
|
||||
| --- | --- | --- |
|
||||
| `narratio_audita_credentials` | `audita.credentials` | list of strings |
|
||||
| `narratio_audita_overlay` | `audita.overlay` | string |
|
||||
| `narratio_audita_proposal_profile` | `audita.proposal_profile` | string |
|
||||
| `narratio_audita_validation_profile` | `audita.validation_profile` | string |
|
||||
|
||||
Remove these retired role variables and their rendered fields:
|
||||
|
||||
- `narratio_audita_llm_api_key`
|
||||
- `narratio_audita_base_url`
|
||||
- `narratio_audita_model`
|
||||
- `narratio_audita_total_llm_concurrency`
|
||||
- `narratio_audita_proposal_llm_concurrency`
|
||||
- `narratio_audita_validation_model`
|
||||
- `narratio_audita_validation_llm_concurrency`
|
||||
- `narratio_audita_work_dir_retention`
|
||||
- `narratio_audita_report`
|
||||
|
||||
Retain binary, timeout, modules, transcript description, config path, and output
|
||||
schema variables. Null modules are omitted; explicit `[]` means no correction
|
||||
modules. Audita owns backend definitions, model/profile contents, concurrency,
|
||||
reporting, and debug policy. Document migration to Audita's own configuration
|
||||
without trying to infer replacements for those policies.
|
||||
|
||||
### Notarius Interface
|
||||
|
||||
Replace `narratio_notarius_config_profile` with
|
||||
`narratio_notarius_config_overlay`, an optional nullable string rendered as
|
||||
`notarius.config_overlay`. Preserve supplied empty strings, `default`, and
|
||||
named selectors exactly; null omits the selector. Selection is independent of
|
||||
Narratio's own overlay and is not a PromptKit LLM-profile selection.
|
||||
|
||||
Replace `narratio_notarius_llm_api_key` with
|
||||
`narratio_notarius_credentials`, an optional nullable list of strings rendered
|
||||
as `notarius.credentials`. Preserve other Notarius configuration interfaces,
|
||||
including cache controls, references, and output mappings.
|
||||
|
||||
### Rendering and Credential Ownership
|
||||
|
||||
Use `is not none`, appropriate serialization, and parent-section conditions
|
||||
covering the new variables. Null omits a field; empty lists and strings remain
|
||||
explicit. Do not copy native defaults into optional role defaults.
|
||||
|
||||
Credential lists contain environment-variable/secret-reference **names**, not
|
||||
secret values. Narratio resolves and forwards them under their exact names.
|
||||
The role neither resolves credentials nor infers them from downstream files.
|
||||
Null omits the field and `[]` emits an explicit empty list; Narratio overlays
|
||||
replace lists rather than append to them. Operators must list every backend
|
||||
credential needed by the selected Audita configuration, including configured
|
||||
but unselected backends. Notarius likewise requires names matching its selected
|
||||
provider configuration. Resolution occurs at pipeline loading, even when a
|
||||
downstream stage will not execute.
|
||||
|
||||
Removing retired variables is a documented breaking role-interface migration.
|
||||
Do not add alias precedence, version-dependent rendering, or special guards
|
||||
for old inventory. Users retaining old deployments retain their old role pin.
|
||||
|
||||
### Operator Upgrade Guidance
|
||||
|
||||
- Replace Narratio `--profile` with `--overlay` and selected `profiles/` files
|
||||
with `overlays/`. Explicit imports from a directory named `profiles` remain
|
||||
valid; this is not a blanket filesystem rename or an LLM-profile rename.
|
||||
- Migrate downstream Notarius selection to `config_overlay` and its selected
|
||||
files to `overlays/`. Named selection needs a supporting Notarius executable;
|
||||
v0.8.1 is the tested baseline, not a new unconditional role version gate.
|
||||
- Audita v2 must be configured independently before running polish. Narratio
|
||||
does not generate its config or infer downstream overlay/profile selectors.
|
||||
- Link the tagged manifest migration procedure: back up old manifests and
|
||||
migrate `effective_config.selected_profile` to `selected_overlay` while
|
||||
preserving progress/checkpoint state. Do not rewrite immutable remote
|
||||
snapshots or infer that every stage must rerun.
|
||||
- Note the native extraction-resume consequence for renamed named Notarius
|
||||
selectors: the next applicable run regenerates extraction with normal
|
||||
dependent invalidation. Omitted/base selections do not gain invalidation
|
||||
solely from this rename. The role does not implement this behavior.
|
||||
|
||||
## Repository Ownership
|
||||
|
||||
- `ansible-role-narratio`: standalone interface, template, documentation, and
|
||||
repository-local tests.
|
||||
- Workspace: roadmap, later staged plan, status, and independent review.
|
||||
- `../narratio`: read-only authoritative v3.0.0 contracts.
|
||||
- Pipeline, collection, consumer, assets, and other roles 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). Use tagged v3.0.0
|
||||
contracts rather than assuming a newer checkout has the same interface.
|
||||
|
||||
Keep meaningful explicit v2.1.0 version-selection and supplied-Go recovery
|
||||
tests where their baseline inputs remain compatible. Do not turn configurable
|
||||
version selection into a promise that new configuration fields work on old
|
||||
applications; new fields stay unset in those cases.
|
||||
|
||||
## Simplest Viable Implementation
|
||||
|
||||
Change the version default and the affected defaults, argument-spec entries,
|
||||
and conditional template fields. Adapt existing representative fixtures and
|
||||
native validation to the new public interface. No additional production tasks,
|
||||
state probes, file migration, or configuration assembly mechanism is needed.
|
||||
|
||||
## Rationale and Alternatives
|
||||
|
||||
Expose the native v3 interface directly instead of retaining aliases or
|
||||
translating legacy Audita tuning into guessed backend/profile definitions.
|
||||
This preserves application ownership and avoids a compatibility framework in
|
||||
the generic installer. Coordinated suite migration can then make explicit D&D
|
||||
policy choices against already-reviewed standalone roles.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The default role installs Narratio v3.0.0; native offline validation accepts
|
||||
baseline and representative rendered configuration.
|
||||
- Added and renamed fields agree across defaults, argument specifications,
|
||||
template, examples, and documentation. Retired native fields are not emitted.
|
||||
- Focused behavioral cases demonstrate null omission, supplied credential-name
|
||||
lists, explicit empty lists, named/empty downstream selectors, and existing
|
||||
meaningful falsey and artifact-composition behavior. Keep this representative,
|
||||
not a matrix of every native rule or a snapshot of today's defaults.
|
||||
- Native validation uses synthetic credential values supplied only to the test
|
||||
process as needed; managed configuration contains names, not values. No live
|
||||
provider calls or reimplementation of upstream forwarding/redaction tests is
|
||||
required. Preserve existing useful log checks without expanding their scope.
|
||||
- Immediate identical role application reports no changes. Selected-version
|
||||
and supplied-Go/missing-binary outcomes remain covered.
|
||||
- Syntax/lint and local repository integration checks pass. No operational
|
||||
controller, target deployment, downstream pipeline execution, or real keys
|
||||
are prerequisites for standalone-role acceptance.
|
||||
- Documentation explains breaking variable changes and links upstream upgrade
|
||||
procedures. No production validation or automatic migration has been added.
|
||||
- Suite, collection, and consumer pins remain unchanged. Independent review
|
||||
records the standalone revision for coordinated integration.
|
||||
|
||||
## Dependencies and Follow-up Work
|
||||
|
||||
Standalone Scriptorium, Audita, and Notarius adoption is complete. This roadmap
|
||||
is approved; execution is defined in the [implementation plan](../implementation.md).
|
||||
After implementation and review, the final integration feature owns D&D
|
||||
configuration, credentials, overlay assets, coordinated dependency pins,
|
||||
collection assembly, and consumer migration guidance. It must deliberately
|
||||
review retry/timeout budgets rather than copying retired tuning mechanically.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None identified for this standalone scope.
|
||||
|
||||
## Upstream References
|
||||
|
||||
- [Narratio v3.0.0 release](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md)
|
||||
- [Configuration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/config.md)
|
||||
- [Audita integration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/audita.md)
|
||||
- [Notarius integration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/notarius.md)
|
||||
- [Operator migration procedures](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md)
|
||||
Reference in New Issue
Block a user