Document Notarius configuration profiles

docs/config.md

@@ -360,6 +360,7 @@ Rules:
 | `pipeline.notarius.enabled` | bool | No | `false` |
 | `pipeline.notarius.binary` | string | No | `notarius` |
 | `pipeline.notarius.llm_api_key` | secret reference | No | unset; exact environment-variable name forwarded to Notarius |
+| `pipeline.notarius.config_profile` | string | No | unset; exact Notarius ConfigKit profile selector |
 | `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from the pipeline file directory |
 | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled |
 | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive |
@@ -382,6 +383,31 @@ Rules:
 | `pipeline.scriptorium.artifact_families` | map | No | empty; expands one ordinary artifact per canonical party character |
 | `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
+### Notarius Configuration Profile
+
+`pipeline.notarius.config_profile` optionally selects a Notarius ConfigKit
+configuration profile when extraction executes:
+
+```yaml
+notarius:
+  config_profile: downstream-economy
+```
+
+When the field is omitted or `null`, Narratio supplies no downstream profile
+selector and preserves Notarius's existing configuration-selection behavior.
+When present, Narratio forwards the exact string to Notarius, including an
+empty string or `default`, which explicitly select Notarius's composed base
+configuration. Notarius owns selector interpretation and validation; Narratio
+does not restrict profile names, resolve profile files, or rewrite the value.
+
+This selection is independent of Narratio's own `--profile` selection. A
+Narratio overlay may explicitly select a differently named Notarius overlay,
+but Narratio never forwards its own profile name automatically. It is also
+independent of `pipeline.notarius.llm_api_key`: an overlay may change either or
+both fields according to the deployed Notarius configuration. See the
+[Notarius integration contract](./integrations/notarius.md) for invocation and
+failure behavior.
+
 ### Notarius Credential
 
 `pipeline.notarius.llm_api_key` optionally names the one environment variable

docs/integrations/notarius.md

@@ -30,12 +30,24 @@ contract introduced in Notarius v0.6.0. Cache controls require support for the
 selected `--resume` and `--chunk_cache` flags. Notarius v0.7.0 is the tested
 cache integration baseline, not an unconditional minimum version; Narratio
 does not impose a runtime version gate. Each reference binding is a separate
-argument before `--json`:
+argument before `--json`. When `pipeline.notarius.config_profile` is present,
+its exact value is another argument pair before `--json`:
 
 ```text
-notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... --json
+notarius run <pipeline_id> --config <config_path> --input <trimmed_json> --output-dir <staging_dir> [--resume] [--chunk_cache <mode>] [--reference <selector>=<verified_snapshot_path>]... [--config-profile <name>] --json
 ```
 
+Notarius v0.7.0 is a known supporting version for `--config-profile`; using the
+option requires a compatible Notarius executable, but deployments that omit the
+field acquire no additional version requirement. Omitted or null configuration
+adds no flag. Supplied empty, `default`, and named selectors are forwarded
+without normalization so Notarius can apply its own ConfigKit semantics. This
+option selects a Notarius configuration overlay, not a PromptKit profile through
+`--llm-profile`, and Narratio never substitutes its own selected profile name.
+A missing or invalid downstream overlay is an ordinary Notarius subprocess
+failure: Narratio does not retry without the selector or fall back to another
+profile.
+
 Reference paths are absolute stable snapshots streamed from manifest-verified
 canonical files prepared inside the current Narratio session workspace. They
 live at `cache/notarius/references/<sha256>/<prepared-basename>` and retain the

docs/internal/stage-extract.md

@@ -23,11 +23,13 @@ procedures belong in [Operations](../operations.md).
    reusing verified bytes or reconstructing a missing/corrupt regular entry,
    and rejects any source change observed while copying;
 4. fingerprints the byte- and provenance-bearing Notarius invocation evidence,
-   including sorted reference identities;
+   including sorted reference identities and the explicit downstream
+   configuration-profile selection;
 5. creates a run-local staging directory and invokes the injected
    `notarius.Runner`, carrying the optional already-resolved credential
-   reference without exposing its value, plus effective resume and chunk-cache
+   reference without exposing its value, the optional exact configuration
-   controls after force precedence;
+   profile, plus effective resume and chunk-cache controls after force
+   precedence;
 6. revalidates the reference snapshots, then validates the v2 successful
    receipt, confined index, management documents, configured required lane
    descriptors, validation summaries, and regular payload files;
@@ -70,7 +72,9 @@ outputs is stable and does not repeatedly invalidate dependent stages.
 Before the focused validator runs, the application compares extract's versioned
 semantic fingerprint. It covers enablement, Notarius pipeline identity, sorted
 reference selector/source mappings, sorted declared output contracts, and each
-canonical `narratio.extraction.<key>` output identity. It excludes executable,
+canonical `narratio.extraction.<key>` output identity. It also covers the
+explicit Notarius configuration-profile selection; omitted, empty, and exact
+`default` selectors share the base-selection identity. It excludes executable,
 timeout, working directory, config path, and private Notarius config contents.
 Credential presence, reference name, and resolved value are likewise
 operational-only and excluded. Ordinary command loading still resolves a
@@ -81,13 +85,15 @@ not rerun a valid completed extraction or stale its dependents.
 stage record still matches the current byte- and provenance-bearing invocation
 evidence. That evidence covers the current direct trimmed-transcript identity,
 sorted prepared-reference identities, pipeline identity, and configured output
-contracts. The same reference helper and transcript identity are resolved again
+contracts, plus the same downstream profile-selection identity. The same
-for artifact evidence, so changing current transcript bytes, reference bytes,
+reference helper and transcript identity are resolved again for artifact
-or producer identity makes the prior extraction obsolete. Operational runner
+evidence, so changing current transcript bytes, reference bytes, producer
-settings do not invalidate otherwise current durable evidence. This includes
+identity, or a named downstream selection makes the prior extraction obsolete.
-`resume` and `chunk_cache`; changing them alone cannot make a complete
+Operational runner settings do not invalidate otherwise current durable
-extraction non-resumable. If extraction executes, ordinary runs forward the
+evidence. This includes `resume` and `chunk_cache`; changing them alone cannot
-configured values, while force disables resume and selects `refresh`.
+make a complete extraction non-resumable. If extraction executes, ordinary
+runs forward the configured values, while force disables resume and selects
+`refresh`.
 
 A valid prepared-reference change makes extraction non-resumable. Missing,
 unsafe, or checksum-inconsistent prepared evidence is a hard validation error
@@ -100,10 +106,12 @@ contracts and provenance, regular-file status, and stored checksums. Missing or
 obsolete results are non-resumable and run again; unsafe filesystem conditions
 return an error rather than silently accepting or replacing data.
 
-Neither contract can observe files imported by Notarius configuration, profile
+This sensitivity is limited to the explicit downstream selector. Narratio's
-contents, prompt/module definitions, or other transitive inputs. Operators must
+own profile label and whole effective-configuration digest are not blanket
-force extraction after changing any such private input behind a stable
+extraction invalidators. Neither contract can observe files imported by
-identifier.
+Notarius configuration, profile contents, prompt/module definitions, or other
+transitive inputs. Operators must force extraction after changing any such
+private input behind a stable identifier.
 
 ## Failure Behavior
 

docs/operations.md

@@ -233,6 +233,30 @@ earlier checkpoints are reused and execution resumes with failed, stale, or
 missing work in dependency order. `--force` is unnecessary unless the operator
 intends to replace otherwise-current artifacts.
 
+### Developing With A Notarius Configuration Profile
+
+A Narratio development overlay can explicitly select a Notarius overlay without
+requiring the names to match. For example, `profiles/testing.yml` may contain:
+
+```yaml
+notarius:
+  config_profile: downstream-economy
+```
+
+Selecting Narratio's `testing` profile then supplies `downstream-economy` only
+when extraction executes. Switching that explicit selector makes a recorded
+extraction non-current and reruns it when `extract` is in the selected stage
+range; the usual dependent invalidation then applies. Selecting a profile does
+not create a separate workspace or retain a separate current extraction result.
+
+Narratio cannot observe edits inside Notarius configuration behind an unchanged
+selector. Force extraction after such an edit when a replacement is intended.
+Use `regenerate-artifacts` when both extraction and analysis must be rebuilt;
+use `analyze` when the existing extraction bundle should be preserved. Field
+semantics belong in [Configuration](./config.md#notarius-configuration-profile),
+and the exact downstream invocation belongs in the
+[Notarius integration contract](./integrations/notarius.md#invocation).
+
 ## Artifact Selection
 
 For a configured artifact family, selecting its family key expands to every
@@ -377,13 +401,13 @@ narratio run-stage extract 2026-04-04 --force
 Narratio automatically reruns extraction when its recorded invocation contract,
 prepared Narratio reference identities, or durable output validation changes.
 The semantic portion covers Notarius enablement, pipeline identity, declared
-reference mapping, and output contracts. Executable, timeout, working directory,
+reference mapping, output contracts, and the explicit Notarius configuration
-and private config-file paths are operational and do not invalidate a current
+profile selector. Executable, timeout, working directory, and private
-result.
+config-file paths are operational and do not invalidate a current result.
-It cannot fingerprint configuration files, profiles, prompts, modules, or
+It cannot fingerprint configuration or profile contents, prompts, modules, or
 other references loaded transitively by Notarius itself. Force extraction after
-changing any of those inputs, even when the top-level Narratio and Notarius
+changing any of those inputs behind an unchanged selector, even when the
-config paths remain the same. A forced extract
+top-level Narratio and Notarius config paths remain the same. A forced extract
 marks successful downstream stages stale. Ordinary extraction failures or
 outcome changes also stale affected downstream stages, while an identical
 repeated `notarius_disabled` self-skip does not repeatedly invalidate them.

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Notarius Configuration Profile Selection
 
-Status: Implementation in progress; Stages 1-3 complete.
+Status: Complete; all stages implemented and verified.
 
 ## Scope and Working Instructions
 
@@ -209,7 +209,16 @@ Notarius's own overlay loader and cache internals remain outside these tests.
 
 ## Stage 4: Document the Feature and Validate the Completed Change
 
-Status: Pending.
+Status: Complete.
+
+Completion marker (2026-09-21): Updated the canonical configuration,
+integration, extract-internals, operations, and maintained-example documentation;
+marked the feature roadmap implemented; and reviewed the completed behavior
+against the consumer request. Verified with Go 1.26.8 using `go test ./...`,
+`go test -race ./...`, `go vet ./...`, `go build ./...`,
+`go test ./internal/doccheck`,
+`go test ./internal/config -run '^TestExamplesLoadAndValidate$'`, and
+`git diff --check`.
 
 Preparation: Canonical documentation owners listed in the feature roadmap,
 `examples/README.md`, and the existing development-focused operations guidance.

docs/roadmap/notarius-config-profile.md

@@ -1,6 +1,6 @@
 # Notarius Configuration Profile Selection
 
-Status: Proposed; not implemented.
+Status: Implemented.
 
 ## Goal and Authority
 

examples/pipeline.full.annotated.yml

@@ -134,6 +134,10 @@ notarius:
   # Optional environment-variable reference. Match this name to api_key_env in
   # the selected Notarius/PromptKit profile; never put the credential here.
   llm_api_key: NOTARIUS_LLM_API_KEY
+  # Optionally select a Notarius ConfigKit overlay when extraction runs. This
+  # is independent of Narratio's selected profile and may use a different name.
+  # See docs/config.md and docs/integrations/notarius.md for the contracts.
+  # config_profile: downstream-economy
   config_path: /usr/local/etc/notarius/config.yml
   pipeline_id: dnd-session
   timeout: 3h