eric/ansible-workspace-dnd

Fork 0

Files

Eric Rakestraw 005a1c8ad5 Close out the standalone Narratio upgrade

2026-09-29 13:16:41 +00:00

12 KiB

Raw Permalink Blame History

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. 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, testing house style, MVP roadmap, and upgrade sequence. 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.

12 KiB Raw Permalink Blame History