Plan adoption of current ConfigKit configuration semantics

This commit is contained in:
2026-11-17 20:19:32 +00:00
parent b9899ea3cc
commit db32d31708

View File

@@ -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/<any-mapping-key>/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.