# ConfigKit v0.9.0

This minor release expands import selection, adds author-declared collection
identity and operations, and supports inheritance between identified records.
It also moves CLI assignments after inheritance and typed decoding. These changes
include breaking API and configuration behavior changes from v0.8.0; review the
migration guidance below before upgrading.

## Changes

- Extend imports with named-file and directory lists, directory filename patterns,
  exclusions, recursion and depth controls, and explicit hidden-file and symlink
  discovery controls. Add `ImportDefaults` to ordinary and layered options, with
  authored declarations taking precedence over application defaults. Imports are
  optional by default. `SourceInfo.ImportSelections` exposes completed optional
  declarations that selected no sources. See the
  [import contract](../config.md#explicit-imports) and
  [consumer guidance](../consumers/README.md#import-defaults-and-selection-inspection).
- Use shared dependency-ready ordering for import composition and sibling
  inheritance. Dependencies complete before dependents, with deterministic
  selection among currently eligible contributions. Source acquisition and
  callback order remain separate from assembly order. See the
  [ordering decision](../adr/0015-shared-dependency-ready-ordering.md).
- Add root `configkit.sequences` declarations for collection identity and
  `replace`, `append`, or `upsert` operations, including in selected overlays.
  Strict peers combine distinct identities and reject duplicates; precedence
  and inheritance apply the destination's collection operation. Upsert replaces
  a whole matching record at its retained position. Identity supports compound
  field sets and scalar strings, numbers, booleans, and null. See the
  [collection contract](../config.md#strict-document-composition).
- Add `Definition.SequenceIdentities`, exact `SequenceIdentityAt` registrations,
  and dynamic `SequenceIdentityMatching` selectors. Application registrations
  govern structural collection operations and check existing matching final
  typed sequences, including values from defaults, CLI assignments, and
  application resolution. YAML-only declarations govern structural operations
  without adding that final-result check.
- Support record inheritance within an identified sequence using an `extends`
  mapping containing the parent's complete identity. The child retains its own
  identity, relationships use surviving assembled records, and output sequence
  order is preserved. See [sibling inheritance](../config.md#sibling-inheritance)
  and the maintained [sequence catalog](../consumers/README.md#identified-prompt-sequences).
- Apply explicit CLI overrides to the decoded configuration before application
  resolution. Mappings retain omitted fields and their presence metadata;
  sequences replace whole lists independently of collection operations. See the
  [CLI contract](../config.md#explicit-cli-overrides).
- Correct native import alias and contained-symlink handling, source-version
  path projection, and provenance/history through collection movement,
  replacement, inheritance, and CLI assignment. Reduce repeated scans,
  accumulated policy copying, and sparse-projection storage during construction.

## Compatibility and upgrade

This pre-v1 minor release intentionally changes the v0.8.0 contracts:

1. **Migrate import requiredness.** The YAML `optional` field is removed and is
   rejected. Replace `optional: true` with `required: false`; omission is equivalent
   when the application does not default imports to required. Replace
   `optional: false` with `required: true`. Imports that previously relied on
   implicit requiredness now need `required: true`, or an application
   `ImportDefaults.Required` default set to true. Review discovery filters:
   `follow` and `hidden` default to true, and directory searches select all
   filenames unless a pattern is supplied.
2. **Replace sequence registrations.** `SequenceComposition` and
   `Definition.SequenceCompositions` are removed without compatibility aliases.
   For a previous registration at `prompts` using `id`, use:

   ```go
   rules.SequenceIdentities = []configkit.SequenceIdentity{
       configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
   }
   ```

   These registrations now also enforce identity in final typed sequences. Fix
   missing or duplicate identities introduced by defaults, CLI assignments, or
   application resolution. Registration does not require a collection to exist
   or determine its allowed shape; schema and application validation retain
   those responsibilities.
3. **Review collection precedence and ordering.** An identified collection now
   defaults to upsert across layers and inheritance when no explicit mode
   applies, rather than unconditional whole-sequence replacement. Declare
   `mode: replace` at the relevant destination where replacement is intended.
   With append or upsert, `[]` contributes no records and does not clear the
   collection; null is invalid. Use `mode: replace` with `[]` to clear it.
   An explicit mode persists at its destination until changed; a parent's mode
   does not transfer to a different inheriting destination. Unidentified
   sequences retain strict peer conflicts and whole-value precedence
   replacement. Dependency-ready assembly can change sequence positions and
   diagnostic or history order compared with the former traversal order.
4. **Review CLI recovery and inheritance assumptions.** CLI overrides can no
   longer repair values that fail earlier decoding, bypass source or inheritance
   errors, or add or cancel inheritance relationships. Supply structural
   directives in source configuration. Application resolution still receives
   explicit CLI values and may record subsequent normalization or derivation.
5. **Update affected Go literals and diagnostic handling.** Use keyed literals
   for expanded option and source-information structs. Collection validation adds
   `CodeSequenceInvalid` (`sequence.invalid`) and `CodeSequenceConflict`
   (`sequence.conflict`); update diagnostic handling where applicable.

Select this version and rebuild:

```sh
go get gitea.maximumdirect.net/eric/ConfigKit@v0.9.0
```

The consumer minimum remains Go 1.26.0. The YAML dependency remains
`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets;
macOS remains best-effort. Publication follows the existing
[release procedure](../release.md).

[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/docs/oss/attribution.md)