diff --git a/docs/config.md b/docs/config.md index 568b486..a6da030 100644 --- a/docs/config.md +++ b/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 diff --git a/docs/integrations/notarius.md b/docs/integrations/notarius.md index 94d30a5..49d7252 100644 --- a/docs/integrations/notarius.md +++ b/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 --config --input --output-dir [--resume] [--chunk_cache ] [--reference =]... --json +notarius run --config --input --output-dir [--resume] [--chunk_cache ] [--reference =]... [--config-profile ] --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//` and retain the diff --git a/docs/internal/stage-extract.md b/docs/internal/stage-extract.md index c9ef65c..e4c14ae 100644 --- a/docs/internal/stage-extract.md +++ b/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 - controls after force precedence; + reference without exposing its value, the optional exact configuration + 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.` output identity. It excludes executable, +canonical `narratio.extraction.` 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 -for artifact evidence, so changing current transcript bytes, reference bytes, -or producer identity makes the prior extraction obsolete. Operational runner -settings do not invalidate otherwise current durable evidence. This includes -`resume` and `chunk_cache`; changing them alone cannot make a complete -extraction non-resumable. If extraction executes, ordinary runs forward the -configured values, while force disables resume and selects `refresh`. +contracts, plus the same downstream profile-selection identity. The same +reference helper and transcript identity are resolved again for artifact +evidence, so changing current transcript bytes, reference bytes, producer +identity, or a named downstream selection makes the prior extraction obsolete. +Operational runner settings do not invalidate otherwise current durable +evidence. This includes `resume` and `chunk_cache`; changing them alone cannot +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 -contents, prompt/module definitions, or other transitive inputs. Operators must -force extraction after changing any such private input behind a stable -identifier. +This sensitivity is limited to the explicit downstream selector. Narratio's +own profile label and whole effective-configuration digest are not blanket +extraction invalidators. Neither contract can observe files imported by +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 diff --git a/docs/operations.md b/docs/operations.md index bfdd745..a5c3fec 100644 --- a/docs/operations.md +++ b/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, -and private config-file paths are operational and do not invalidate a current -result. -It cannot fingerprint configuration files, profiles, prompts, modules, or +reference mapping, output contracts, and the explicit Notarius configuration +profile selector. Executable, timeout, working directory, and private +config-file paths are operational and do not invalidate a current result. +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 -config paths remain the same. A forced extract +changing any of those inputs behind an unchanged selector, even when the +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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 039af3a..c7f865b 100644 --- a/docs/roadmap/implementation.md +++ b/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. diff --git a/docs/roadmap/notarius-config-profile.md b/docs/roadmap/notarius-config-profile.md index 0676a17..41f8cba 100644 --- a/docs/roadmap/notarius-config-profile.md +++ b/docs/roadmap/notarius-config-profile.md @@ -1,6 +1,6 @@ # Notarius Configuration Profile Selection -Status: Proposed; not implemented. +Status: Implemented. ## Goal and Authority diff --git a/examples/pipeline.full.annotated.yml b/examples/pipeline.full.annotated.yml index cb85f9c..b8f0a55 100644 --- a/examples/pipeline.full.annotated.yml +++ b/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