# 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)