235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
# Feature 0021: Adopt Narratio v3.0.0 in the Standalone Role
|
|
|
|
Status: done
|
|
|
|
## 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 adoption and independent review are complete for all four upgraded
|
|
applications. Git history preserves the completed staged plan. The next,
|
|
coordinated 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.
|
|
|
|
## Implementation Evidence
|
|
|
|
- Standalone role commits: `a28f22c` (v3 interface and migrated fixtures),
|
|
`45f6836` (selector and credential-list coverage), and `3c0700b` (upgrade
|
|
guidance). Production tasks, suite dependencies, collection, and consumer
|
|
remain unchanged.
|
|
- `bash -n` and the local integration harness passed. The harness includes
|
|
syntax check and production-profile lint and exercised native offline
|
|
baseline, named, and explicit-empty validation, selected v2.1.0 behavior,
|
|
supplied-Go recovery, synthetic credential loading, and clean immediate
|
|
repeats. Role and workspace whitespace checks passed.
|
|
- Independent review on 2026-09-29 found no required remediation or unjustified
|
|
strengthening of requirements. Syntax checks, production-profile lint, shell
|
|
syntax, whitespace checks, and native v3.0.0 configuration validation passed
|
|
again during review. The review used recorded successful integration runs
|
|
rather than rerunning their host-mutating scenarios. No remediation document
|
|
was changed.
|
|
- Reviewed standalone revision: `3c0700b`. Coordinated suite migration remains
|
|
separate follow-up work; suite, collection, and consumer pins are unchanged.
|
|
|
|
## 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)
|