From db32d3170865e5f4174fafdbf2412acd731c41a3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 20:19:32 +0000 Subject: [PATCH] Plan adoption of current ConfigKit configuration semantics --- docs/roadmap/configkit.md | 435 ++++++++++++++++++++++---------------- 1 file changed, 251 insertions(+), 184 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 937fa053..6c247442 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,229 +1,296 @@ -# ConfigKit 0.5 And Configuration Inheritance +# Adopt Current ConfigKit Configuration Semantics ## Purpose -Adopt ConfigKit v0.5.0 and make its sibling inheritance useful and supported in -Notarius configuration, particularly for deriving development or testing -pipelines from a complete D&D pipeline without duplicating the pipeline body. +Adopt `go.maximumdirect.net/configkit` v1.2.1 and its native consumer workflow. +The objective is consistent configuration semantics across ConfigKit-consuming +applications. Existing Notarius composition behavior is a migration baseline, +not a compatibility requirement to reproduce through adapters. -ConfigKit owns source composition and inheritance. Notarius continues to own -typed configuration, domain defaults and validation, pipeline resolution, and -execution. This work does not introduce a second configuration-merging engine. +[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the +boundary: ConfigKit delivers the final resolved application document; Notarius +supplies application schema, defaults, normalization, validation, and subsequent +pipeline resolution. This roadmap defines the target and required work. A later +implementation plan will own sequencing. Release publication is separate work. -The [implementation plan](implementation.md) owns the ordered work and -validation sequence. Release preparation and publication remain separate. +## Reviewed Baseline And Sources -## Reviewed Baseline +Reviewed on 2026-11-17 against Notarius `b9899ea`: -Reviewed on 2026-10-03. Notarius pins ConfigKit v0.4.2 and uses its ordinary -`Load` API in `internal/core/config/load.go`. Configuration version 5 supports -imports, selected configuration overlays, explicit command overrides, recorded -normalization, and redacted effective/explain output. Runtime configuration is -detached from the ConfigKit inspection snapshot. +- ConfigKit v0.5.0 under `gitea.maximumdirect.net/eric/ConfigKit`; +- PromptKit v0.12.0, which consumes that same old ConfigKit package; +- Go 1.25.5 and go-yaml v4.0.0-rc.6; +- Notarius configuration version 5, imports, overlays, sibling inheritance, + declaration-relative application paths, and effective/explanation CLI reports. -Named pipelines and artifact lanes are mappings; pipeline `steps` and validator -chains are sequences. The complete example imports -`examples/pipelines/dnd-session.yml`, while the existing development overlay -changes operational settings. Relative configured paths are resolved from the -file supplying their surviving declaration. The current path resolver uses -ConfigKit origin/source metadata and host filesystem paths. +The released v1.2.1 tag in `../ConfigKit` identifies source commit +`51ef3144158db1a09fabdbd1c7ae59908c84923b`. Review references: -Target ConfigKit v0.5.0 at full source commit -`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Consult the pinned -[release guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md) -and [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md). -The release adds inheritance, layered loading, filesystem-backed sources, -mapping sources, and passive resource contexts. Its Go requirement and YAML -dependency are unchanged. The upgrade has not yet been trialed against -Notarius's test suite at this review baseline. +- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/consumers/README.md) +- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/config.md) +- [Release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/releases/) + +All intervening release notes were read in the local checkout. The important +changes are: + +| Releases | Relevance to Notarius | +| --- | --- | +| v0.6.0 | Loading/inspection optimizations; Go minimum becomes 1.26.0. No promised application-wide speedup. | +| v0.7.0–v0.7.1 | Frozen effective-configuration diffs; maintainer tooling update. | +| v0.8.0 | Input destinations, sequence-item placement, source-version checks, and identified sequences. | +| v0.9.0 | Expanded imports; imports optional by default; author-declared replace/append/upsert; identified-record inheritance; CLI assignments move after inheritance and decoding. | +| v0.10.0–v0.10.2 | Explicit configuration discovery; broader absent-main lifecycle; loading, ownership, acquisition, and history fixes. | +| v1.0.0 | New module path, source-root `config` controls, public API cleanup, source lookup, and Go 1.27.0 minimum. | +| v1.1.0 | Field-level normalization inside lists; identity-aware provenance/history across record movement. | +| v1.2.0 | Main-relative companion inputs and layered overlay context selection. | +| v1.2.1 | Stable go-yaml v4.0.0 and loader-plugin adaptation. | + +### Current Integration Areas + +`internal/core/config/load.go` supplies ConfigKit's definition and callbacks. +`loaded_config.go` privately retains its inspection result and publishes a +detached runtime value. `document_paths.go`, `pipeline_document.go`, and +`document_normalizer.go` implement application normalization and source tracking. +The normalizer currently records whole-list coverage even for leaf edits. + +`internal/cli/configkit_load.go` and `run.go` own selection and diagnostics. +`discoverConfigPath` manually probes files before `config.Load` calls ConfigKit. +The complete example imports its pipeline through root `configkit`. Current +documentation describes unconditionally replacing whole step lists. + +ConfigKit types also appear inside the PromptKit adapter's native source and +inspection APIs. That is a distinct integration boundary with the dependency +constraint below; a repository-wide import replacement would be incorrect. ## Target End State -### Native Sibling Inheritance +### Native Loading And Ownership -Operators can define a named pipeline with `extends: parent-pipeline` and -override only the settings that differ. The parent remains an ordinary named, -valid pipeline; no abstract-template flag, template registry, or special -validation exemption is introduced. Derived pipelines use the existing run, -listing, validation, effective-configuration, and explanation commands. +Use the new public package and the ordinary `Load` workflow for the application +configuration. Defaults, `Resolve`, `Validate`, `VersionRule`, and sensitivity +classification remain supported application extension points. The handoff +contains fully composed, decoded, normalized, and validated application values. +Runtime conversion and catalog-dependent pipeline preparation retain their +application ownership. -Use ConfigKit's native semantics without restricting inheritance to pipelines -or implementing a Notarius-specific subset: +ConfigKit owns import acquisition, ordering, inheritance, collection operations, +CLI assignment semantics, limits, source evidence, and frozen inspection. Pass +its results and structured failures through the established adapter boundary. +Application validation checks the resulting domain configuration; it does not +audit superseded contributions or replay structural directives. -- `extends` selects one exact key among the mapping's immediate siblings. - It is not a path, cross-scope lookup, or multiple-parent expression. -- Source precedence is assembled before inheritance, and inheritance runs - before typed decoding and application resolution. Inherited input is explicit - for presence-sensitive defaults, including zero, false, empty, and null. -- Child mappings recursively overlay parent mappings; sequences, scalars, - and null replace inherited values. Existing typed/domain validation still - determines whether the resulting value is valid. -- Omitting `extends` retains a lower-priority relationship; `extends: null` - cancels the relationship, not arbitrary inherited fields independently. -- Root and sequence-element mappings have no sibling namespace for their own - string relationship. Nested mappings may have one. In particular, individual - entries of the `steps` sequence cannot extend other step entries. -- ConfigKit rejects missing/non-mapping parents, invalid directive types, and - cycles, and resolves effective relationships even in unselected entries. -- Parent definitions receive normal typed decoding and Notarius validation. - Inheritance is not a way to hide invalid partial pipeline definitions. -- Inherited nested relationships resolve at their destination according to - ConfigKit's rules; do not pre-expand or reinterpret them in Notarius. +Keep configuration `version: 5`: its typed application shape is unchanged. +Explain the deliberate ConfigKit syntax/semantic migration in operator guidance +and the eventual minor-release note. Existing files require migration rather +than a compatibility pre-parser or legacy control aliases. -Names are matched by ConfigKit before Notarius's existing identifier trimming. -Document exact-key lookup rather than introducing pre-inheritance name rewriting. +### Source Controls, Imports, And Composition -The principal documented workflow is whole-pipeline reuse. Inheritance does not -append steps, merge sequences by `id`, or allow a child to override one list -element without supplying a replacement list. The same applies to validator -chains. Do not disguise this boundary through custom list-merging code. +Use source-root `config` controls in Notarius configuration inputs. Update real +control blocks and stored declaration pointers, including imported files, +overlays, mapping fixtures, and examples. Nested application data named `config` +retains native treatment. Former `configkit`/`_configkit` keys are ordinary data; +ordinary typed validation governs them. No custom legacy-control scanner is +needed. -### Paths, Provenance, And Runtime Boundaries +This control migration applies to Notarius's application loader. PromptKit +operator files and adapter fixtures follow the version of PromptKit that reads +them; retain their old control spelling while that separate engine remains old. -An inherited relative reference or resource path remains relative to its -original declaring file, not the child's file or the invocation directory. -Imported parents, overlays, and nested inheritance must retain that behavior. -Direct child declarations use their own source context. Built-in relative -destinations and CLI-supplied paths keep their existing bases. +Enable ConfigKit imports and accept its native path/list, directory, glob, +destination, placement, exclusion, recursion, hidden-file, symlink, and +requiredness rules. Leave `ImportDefaults` unspecified unless an application +choice is explicitly approved. In particular, do not restore former implicit +requiredness or impose a YAML-only directory filter globally. Required deployed +fragments, such as the maintained complete pipeline import, should say +`required: true` in their declaration so an incomplete installation fails there. +Optional imports remain genuinely optional. +Use the native main-only source-version default; fragments do not acquire a new +mandatory version declaration as a side effect of this upgrade. -Review `documentPathBase` and related original-path/normalization handling -against the new origin metadata. Make narrowly required corrections if needed; -do not assume that successful typed decoding proves correct path resolution. -Effective output must agree with the runtime paths, and explanations must retain -the upstream derivation evidence through recorded Notarius normalization. +Expose native identified sequence operations and inheritance through the source +format. Without identity, lists retain native peer-conflict/whole-replacement +behavior. Identified lists support strict peer composition and native +replace/append/upsert across tiers. Upsert replaces a complete matching record, +retaining its position; it is not a recursive merge of that record. Clearing an +append/upsert collection requires explicit replacement with an empty list. +Dependency-ready assembly order, not a Notarius sorting or append pass, controls +composition. Final Notarius checks still validate stage order, supported modules, +reference dependencies, and unique application identifiers. -Keep the ConfigKit boundary private: no upstream inheritance objects or -unresolved directives reach runtime pipeline/module types. ConfigKit expands -relationships once during loading. Notarius's existing binding-profile, -validation-policy, and module-default resolution still operate on the resulting -configuration; they are not replaced with generic sibling inheritance. +Step identity registration is an explicit decision below. Other identified +collections remain available through author declarations; no broad automatic +`id` inference or universal registration is required. Demonstrate a composed +step list and a derived pipeline using native controls in maintained examples +or small canonical snippets, with behavioral coverage. -Configuration overlays, pipeline inheritance, and PromptKit `base_profile` -inheritance remain distinct mechanisms. The latter still belongs to PromptKit. +CLI overrides apply after inheritance and typed decoding, before application +resolution. Preserve explicit zero/false/empty values. Structural errors cannot +be repaired by CLI assignments; document this instead of rebuilding the former +override order. Notarius's binding-profile and validation-policy rules remain +domain semantics applied to the final configuration. -### Compatibility And Upgrade Policy +### Native Source Selection And Resources -Keep Notarius configuration `version: 5`. The typed runtime shape is unchanged; -the new capability belongs to configuration composition. No new CLI flag or -inheritance opt-in setting is needed or available upstream. +Replace manual acquisition/probing with ConfigKit source descriptions. Explicit +`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive +`File` sources: a missing selected file fails instead of searching elsewhere. +For default discovery use `SearchConfig` with an approved search convention; +the recommended Unix-system preset and its alternative are recorded below. +Use a required search for commands that require a configuration file, preserving +their need for a selected configuration. This does not impose requiredness on +all imports or on separate defaults-only programmatic loads. -The significant compatibility change is that `extends` becomes a reserved key -in every input mapping, including dynamic module-option maps and named maps. -It is consumed before typed decoding, so it can no longer be ordinary data or -an ordinary entry name there. Audit maintained configuration/fixtures for such -usage and document that affected operator configurations must rename the key -or identifier and any associated consumer field. Do not silently strip, alias, -or bypass the directive to preserve an incompatible interpretation. +Report the actual selected main file using retained source information; update +load/error plumbing rather than making a second discovery pass. Construction of +search descriptions remains side-effect-free, and acquisition errors follow +ConfigKit's native selected-file behavior. -Configurations without that collision should retain their existing meaning. -Preserve discovery, import rules, overlay selection, explicit CLI override -precedence, strict decoding, redaction, defaults, and validation. Existing -configuration-stage inheritance does not alter the fixed execution pipeline, -artifact contracts, warning policy, or checkpoint identity design. +Retain the deliberately selected application path policy: file-authored values +use their declaring file, CLI paths use the invocation directory, and relative +application defaults use the canonical main file. Use `EntryInfo`, source records, +and public resource contexts where appropriate. Native destinations and source +coordinates are distinct: a mounted or inherited value keeps its source base. +No new target-existence, confinement, symlink, or permission policy is added to +application resource paths. ConfigKit's own input-root rules remain upstream. -The eventual Notarius release should be a new minor version, explaining both -the feature and the newly reserved input key. Release preparation/publication -is separate from this work; no exact release number is selected here. +Ordinary `Load` is sufficient for current application composition. `LoadLayered`, +`MainRelative`, and overlay fallbacks are available when actual bundled/companion +inputs need them; the upgrade does not require an artificial extra input layer. -## Required Work +### Lean Application Resolution And Inspection -### Dependency And Configuration Integration +Replace `InputInfo` with `EntryInfo`, `Definition.Secret` with `Sensitive`, +generic `Record` calls with the corresponding named recording methods, and +`LayerBase`/`"base"` with `LayerMain`/`"main"` where used. Audit all affected +symbols and diagnostic strings against the v1 migration table. Use assignment- +and-record helpers when appropriate; named recording methods alone do not mutate +the application value. -Upgrade `go.mod` and `go.sum` to the exact target. Keep PromptKit and unrelated -dependencies unchanged unless dependency resolution demonstrably requires it. -Continue using ordinary `configkit.Load`, the existing typed defaults factory, -and source-aware resolution/validation callbacks. +Use v1.1 field-level recording for list leaf normalization. Remove the old +blanket whole-sequence coverage wrapper where its only purpose was satisfying +the old audit. Record actual structural mutations at their proper scope. Resolve +source-relative values before moving records; fixed entry positions, final +positions, historical evidence, and effective origins serve different purposes. +Keep map-key relocation bookkeeping only where actual application identifier +normalization still needs it. Do not add an independent history-replay engine. -Inspect the load, operational-document, path, conversion, inspection, and CLI -boundaries. Add only integration adjustments demonstrated necessary by the -upstream change. There should be no `Extends` field added to Notarius runtime -types and no homegrown inheritance algorithm. +Effective/explanation commands delegate to ConfigKit's captured inspection, +retaining redaction, presence, source history, and detached ownership. Source +lookup APIs support useful diagnostics, including empty import selections when +needed, without turning ordinary optional absence into warnings. ConfigKit's +`Diff` is available for a later operator-facing comparison command; a new CLI +diff or secrets-management workflow is not required for this adoption. -Update ConfigKit's factual attribution version and COPYRIGHT/LICENSE/source -links to the target commit after inspecting its actual notices. Preserve the -selected project grant and reuse unchanged local license texts. +## Dependency And Toolchain Boundary -### Maintained Example +The target is ConfigKit v1.2.1, stable go-yaml v4.0.0, and a Go consumer minimum +of 1.27.0. Update the selected release-validation toolchain, setup guidance, and +actual configured build/CI environments consistently. Minimum and validation +patch remain separate choices. Include Go and configuration migration impact in +the eventual release note; patch releases cannot raise the Go minimum. -Extend the complete example's imported pipeline definitions with a small -`dnd-session-development` sibling deriving from `dnd-session`, demonstrating a -pipeline-level setting override such as a smaller structural-repair budget. -Use already supported values and existing profile sources so the example -validates without an invented model/profile dependency. Explain that -`llm_profile` is another useful override when the operator supplies that profile. +PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`, +its source helpers, and inspection. Keep these contained in the LLM adapter +until its separate upgrade; ordinary Notarius configuration uses new-path types. +Prefer neutral scalar/domain handoffs over translating dependency-owned graphs. -Retain the runnable parent, minimal example, and existing operational overlay. -Do not duplicate the complete steps list or add a third standalone configuration -merely to demonstrate inheritance. Update example-loading/listing expectations -for the additional pipeline, checking inherited behavior rather than snapshots -of incidental formatting or total line counts. +There is also a concrete shared-dependency incompatibility: -### Canonical Documentation +- ConfigKit v1.2.1 requires stable go-yaml v4.0.0. +- Old-path ConfigKit v0.5.0 imports `go.yaml.in/yaml/v4/plugin/limit`. +- Stable go-yaml contains `plugin/loaderlimits` and no `plugin/limit`. +- Go selects one version of this shared YAML module, despite ConfigKit itself + having two distinct module paths. -- `docs/config.md`: own syntax, composition order, exact sibling lookup, - replacement/null semantics, path bases, reserved-key migration, and limits - on step/validator-list composition. Link to the maintained example and pinned - upstream rules rather than duplicating the entire upstream manual. -- `docs/internal/configuration.md`: describe expansion before typed decoding, - presence and source-aware normalization, and the unchanged runtime boundary. -- `docs/integrations/pkg-configkit.md`: update the supported version, public - contract links, and integration scope. -- `docs/oss/attribution.md`: update the dependency's verified source/notice links. -- `docs/cli.md` and consumer guides: update only where navigation or examples - benefit from showing selection of the derived pipeline. Do not invent new - invocation syntax or duplicate the configuration reference. +Therefore keeping PromptKit v0.12.0 and its unpatched ConfigKit v0.5.0 does not +produce a buildable v1.2.1 target. Resolve the open dependency decision before +finalizing the implementation plan. Neither a local fork/replace nor silently +ending at ConfigKit v1.2.0 is the target architecture. This planning pass made +no dependency changes and ran no trial application build. -The existing ConfigKit architecture decision remains applicable. No new ADR is -required solely for consuming the library's composition feature; do not rewrite -an accepted ADR or turn new private implementation details into invariants. +## Required Repository Work And Acceptance -## Verification And Acceptance +- Migrate application-side dependency imports, APIs, diagnostics, source + declarations, inspection, and discovery; resolve the PromptKit/YAML boundary + through the approved dependency path. Native builds must pass at completion. +- Update real-file loading, imports, overlays, inheritance, CLI assignment, + path-origin, failure, and ownership tests under `internal/core/config` and + `internal/cli`. Add representative collection composition and step-reference + normalization cases, including imports in distinct directories and leaf + histories after list composition. Test native semantics, not the old behavior. +- Retain two top-level configuration examples. Migrate the complete example's + required import and demonstrate useful native composition without adding a + second application merger or an unnecessary example framework. +- Revise `docs/config.md`, `docs/cli.md`, `docs/internal/configuration.md`, and + affected operations/subprocess guidance for syntax, search, imports, collections, + CLI ordering, origins, and inspection. Update README/toolchain/release guidance + and affected dependency integration references. Preserve accepted ADR history; + ADR-0020 already supplies the durable ownership rationale. +- Update `docs/oss/attribution.md` from actual selected module revisions and + notices, including coexistence of old/new ConfigKit if applicable, stable YAML, + and newly selected transitive dependencies. Preserve the application grant. + Upstream ReleaseKit is maintainer tooling; adopting it as Notarius release + machinery or adding its gates is outside this feature. +- Verify focused configuration/CLI/LLM tests, full offline tests, vet, a native + build, maintained examples and report commands without provider calls, tidy + consistency, selected module identities, and affected links. No production + inference, fixed performance improvement, new release gate, or broader + filesystem/security guarantee is part of acceptance. -Use focused Notarius boundary tests, not a duplicate of ConfigKit's full suite: +Completion means current native configuration semantics are usable and documented +on a coherent dependency graph, with final domain validation and no unresolved +directives at runtime. The old ConfigKit 0.5 roadmap is replaced by this feature +scope; unrelated completed plans and review findings remain separate records. -- Existing maintained configurations continue loading and resolving. -- A derived pipeline retains its own identifier and inherits the complete - parent pipeline while applying its explicit overrides. -- Imports and selected overlays participate in composition before inheritance; - explicit CLI overrides keep their documented precedence. -- Representative zero/false/null inputs exercise existing presence-sensitive - defaulting or validation correctly; null is not universally valid merely - because inheritance can represent it. -- Replacing a steps or validator sequence does not concatenate or merge it. -- References inherited from a parent in another file retain their declaring - directory, while child-supplied replacements use the child's directory. -- Effective and explanation output remain redacted and expose useful source - and inheritance information after application normalization. -- Representative invalid inheritance produces ConfigKit load diagnostics through - the normal Notarius CLI error path, without a parallel validation engine. -- Maintained examples and their imported fragments validate offline without - credentials or provider calls. +## Open Decisions -Configuration and CLI boundary coverage should protect document/path/operational, -effective/explanation, and maintained-example behavior. Framework-resolution -coverage is appropriate where a distinct handoff risk requires it. Acceptance -includes the offline default suite, vet, and build with `GOWORK=off`, dependency -tidiness, and documentation diff/link checks appropriate to the changes. The -implementation plan owns their sequencing; these checks are not additional -permanent release gates. +### 1. Resolve The Stable-YAML Conflict With Old PromptKit -## Deferred Capabilities And Non-Goals +Recommendation: seek a narrowly scoped **released upstream compatibility patch** +for the old ConfigKit module used by PromptKit, adapting it to stable go-yaml. +If upstream supports that patch, the two module identities can coexist briefly +and Notarius can complete its ConfigKit upgrade before the separate PromptKit +feature migration. This preserves the desired ordering using supported releases +rather than adding application-owned compatibility machinery. No such patch is +assumed to exist or assigned an invented release number here. -- Do not adopt `LoadLayered` or add a new underlay precedence tier now. Existing - imports, overlays, and typed defaults remain the loading model. Bundled - pipeline presets or site-wide default layers need a separate operator-facing - design if selected later. -- Do not move Go defaults into embedded YAML or mapping sources solely because - v0.5.0 provides those APIs. -- Do not generalize references to arbitrary `fs.FS` resources in this work. - `SourceContext` may be used if it materially helps the required path behavior, - but its filesystem access rules must not silently replace Notarius's existing - host-path contract or introduce new path restrictions. -- No abstract templates, multiple inheritance, list-element composition, - new template schema, new pipeline scheduler, or extra configuration knobs. -- No opt-in gate or Notarius-only prohibition on other valid native inheritance - locations; use upstream semantics and existing domain validation. +Alternative: coordinate the PromptKit adapter's module/API migration with this +cutover and select a current PromptKit release that consumes ConfigKit v1.2.1. +This is the cleaner long-term dependency graph and avoids maintaining a legacy +patch, but couples the two implementation work sets. If selected, prepare the +PromptKit roadmap before claiming a standalone ConfigKit sprint can finish. -There are no significant open design decisions at this baseline. Implementation -should verify the new metadata behavior and correct concrete integration gaps -without broadening the agreed feature scope. +A temporary ConfigKit v1.2.0 checkpoint can assist that coordinated migration +because it still selects YAML rc.6, but it does not complete this roadmap's +v1.2.1 target. Dependency patches/forks inside Notarius are not the recommendation. + +### 2. Default Main-File Search Convention + +Recommendation: use ConfigKit's `UnixSystemDirectories()` preset for default +Notarius discovery, with `SearchOptions.Required` enabled. It fits the +sysadmin-focused deployment, retains the existing installed location among its +candidates, and shares conventional names/order with other ConfigKit consumers. +Explicit CLI/environment selections remain exclusive file choices. Document the +new candidates and native first-selected-file failure behavior. + +Alternative: use `SearchPaths` containing only the current installed default +`/usr/local/etc/notarius/config.yml`. This still delegates acquisition to ConfigKit +and minimizes discovery changes, but offers less convention sharing. User/home +or working-directory presets can be selected deliberately if a broader discovery +workflow is desired; they are not silently enabled by the recommended preset. + +### 3. Application Identity For Pipeline Steps + +Recommendation: register `id` for `/pipelines//steps` using +`SequenceIdentityMatching`. Step IDs already have application significance and +uniqueness checks. Native identity makes independently imported steps composable +and gives overlays/inheritance the ordinary upsert default. Authors can explicitly +select replacement or append. Document the full-record upsert rule and clearing +semantics, and exercise reference-dependent paths after composition. + +Alternative: leave sequence registrations empty and let authors opt in with +source-local `config.sequences` declarations. This is also ConfigKit-native and +preserves ordinary unregistered-list replacement when no declaration is supplied, +but each composed pipeline must declare its collection identity. In either case, +avoid automatic identity inference for validator chains or other unrelated lists.