Plan the ConfigKit upgrade and test isolation

docs/roadmap/notarius-credential-forwarding.md

@@ -0,0 +1,157 @@
+# Typed Notarius Credential Forwarding
+
+Status: proposed
+
+## Summary
+
+Allow an operator to configure one typed credential reference for the Notarius
+stage. Narratio resolves that reference through its existing ConfigKit secrets
+bootstrap and supplies the credential to the Notarius subprocess under the
+referenced environment-variable name.
+
+This request defines only the operator-facing configuration and invocation
+contract. It does not prescribe an internal implementation.
+
+## Problem
+
+An enabled Notarius pipeline may select a PromptKit profile that requires an
+API key, such as a profile whose `api_key_env` is `OPENROUTER_API_KEY`.
+Narratio already supports environment and secrets-directory bootstrap for typed
+credentials, but the Notarius configuration section has no credential field.
+
+Consequently, an operator cannot declare the Notarius credential dependency in
+Narratio configuration. Supplying the variable to Narratio's environment or
+conventional secrets directory is not sufficient under the current public
+contract: the Notarius invocation receives Narratio's minimal child
+environment, and no selected Notarius credential is forwarded.
+
+This leaves an otherwise valid configured extraction stage unable to
+authenticate to a provider without an out-of-band invocation mechanism.
+
+## Required Operator-Facing API
+
+Add one optional typed secret reference at:
+
+```text
+pipeline.notarius.llm_api_key
+```
+
+Example:
+
+```yaml
+notarius:
+  enabled: true
+  config_path: /usr/local/etc/notarius/config.yml
+  pipeline_id: dnd-session
+  llm_api_key: OPENROUTER_API_KEY
+  outputs:
+    spells:
+      lane_id: spells
+      media_type: application/json
+      schema_id: notarius.dnd.spells
+      schema_version: v1
+      module_key: dnd/spells
+```
+
+`llm_api_key` contains an environment-variable name, never a raw credential.
+Its value uses the same typed-secret and ConfigKit bootstrap semantics as other
+Narratio credential references:
+
+- when the field is absent, Narratio forwards no Notarius credential and
+  preserves the current behavior;
+- when the field is present, its value must be a valid typed secret reference
+  that resolves to a nonempty credential during configuration loading;
+- an existing process environment value takes precedence over a value loaded
+  from the selected secrets directory;
+- `--secrets-dir` and conventional sibling `secrets/` discovery retain their
+  existing meanings; and
+- a selected profile may replace or explicitly remove the field under ordinary
+  ConfigKit overlay semantics.
+
+For a configured reference such as `OPENROUTER_API_KEY`, the Notarius child
+process receives the resolved credential under exactly that environment name.
+This lets the operator coordinate the Narratio field with the `api_key_env`
+selected by the Notarius PromptKit profile without introducing
+provider-specific configuration in Narratio.
+
+No new CLI flag is required. The existing Notarius argument vector, pipeline
+configuration path, working directory, reference bindings, receipt, and output
+contracts remain unchanged.
+
+## Inspection and Diagnostic Contract
+
+- `narratio config validate` resolves the configured secret reference and
+  fails before stage execution when it is missing or empty.
+- `narratio config show` may expose the non-secret reference name, such as
+  `OPENROUTER_API_KEY`, but never the resolved credential value.
+- `narratio config sources` and `narratio config diff` retain their existing
+  secret-safe behavior.
+- Configuration digests, manifests, generated configuration, command
+  arguments, persisted diagnostics, receipts, and other operator-visible
+  output must not contain the resolved credential value.
+- Errors may identify the field or unresolved environment-variable name but
+  must not include credential bytes.
+
+## Compatibility
+
+The field is optional and defaults to absent. Existing configurations retain
+their current behavior without migration.
+
+The credential name belongs to deployment configuration rather than to a
+specific provider. Narratio does not infer a name from a Notarius pipeline,
+profile ID, backend, model, or configuration file. Operators must select a name
+that agrees with the Notarius PromptKit profile they deploy.
+
+## Acceptance Criteria
+
+- A pipeline with Notarius enabled and no `notarius.llm_api_key` continues to
+  load and invoke Notarius with no forwarded provider credential.
+- A pipeline may set `notarius.llm_api_key` to a valid environment-variable
+  reference.
+- The reference resolves from an existing process environment value or from
+  Narratio's existing explicit or conventional secrets-directory bootstrap.
+- A missing or empty configured credential fails configuration loading before
+  Notarius execution.
+- A successful Notarius invocation receives the resolved value under exactly
+  the configured reference name.
+- Unrelated credentials present in Narratio's environment or secrets directory
+  are not made available to Notarius merely because this field is configured.
+- Base and named-profile configuration follow ordinary ConfigKit replacement,
+  explicit-null, source-reporting, diff, and secret-resolution semantics.
+- Effective inspection exposes at most the safe reference name and never the
+  resolved value.
+- No raw credential appears in command arguments, generated configuration,
+  manifests, receipts, persisted diagnostics, error messages, or test output.
+- The existing Notarius CLI arguments and result-validation contract remain
+  unchanged.
+- Focused tests use synthetic credentials and a controlled Notarius substitute;
+  they do not contact a model provider or require a real API key.
+- Configuration, CLI, integration, example, troubleshooting, and release
+  documentation are updated only where their existing canonical ownership
+  requires it when the feature is implemented.
+
+## Non-goals
+
+- Defining how Narratio implements credential resolution or subprocess
+  construction internally.
+- Adding an arbitrary environment-variable map to the Notarius stage.
+- Forwarding every variable loaded from the secrets directory.
+- Inferring provider, backend, profile, model, or credential names from
+  Notarius configuration.
+- Managing secret files, credential values, rotation, encryption, or an
+  external secret store.
+- Changing Notarius configuration syntax, PromptKit profile syntax, CLI flags,
+  receipt schemas, pipeline definitions, or output bundles.
+- Supporting more than one Notarius provider credential in this feature.
+- Validating a credential with its provider during configuration loading.
+- Adding credentials to command-line arguments, ordinary YAML values, or
+  generated invocation files.
+
+## Consumer Dependency
+
+The D&D Ansible pipeline requires this operator-facing contract before it can
+provide complete suite-managed credential delivery. Its intended deployment
+places files named for configured secret references in Narratio's conventional
+`secrets/` directory. That deployment can select and provision the value only
+after Narratio provides a typed field that forwards the selected Notarius
+credential under the same reference name.