configkit/docs/releases/v1.0.0.md

# ConfigKit v1.0.0

ConfigKit's first stable release completes the public API cleanup, moves the Go
module to `go.maximumdirect.net/configkit`, and scopes configuration controls to
the root of each source document. It also corrects presence, history, and
sensitivity reporting and adds direct source lookup for successful and failed
loads.

This release includes intentional breaking changes from v0.10.2. The public Go
API, documented configuration and resolution semantics, and structured diagnostic
contracts now follow the [stable-release compatibility policy](../policy/release.md#versioning-and-compatibility).
That policy includes the existing allowance for minor releases to raise the Go
consumer minimum.

## Upgrade from v0.10.2

### Module path

Update the dependency requirement and Go imports from
`gitea.maximumdirect.net/eric/ConfigKit` to `go.maximumdirect.net/configkit`,
selecting v1.0.0. The package name remains `configkit`.

Go treats the two import paths as different packages with different named types.
Coordinate the change with dependencies that exchange ConfigKit values with your
application. Earlier tags retain their original module declarations; no old-path
compatibility module is provided. See the
[module migration guide](../consumers/README.md#vanity-module-path-migration).

### Source-document controls

Rename genuine source-root `configkit` control blocks to `config` in main files,
imported fragments, underlays, selected overlays, and programmatic mapping inputs.
The recognized controls remain `imports` and `sequences`, subject to their
existing context-specific rules and import opt-in.

The control name is reserved only at the root of each acquired document. ConfigKit
extracts controls before placing that document's payload. Nested `config` keys,
including those in sequence records, are ordinary application data. Application-root
`config` data produced by placement, defaults, CLI overrides, or resolution is
also ordinary data and is not interpreted again as controls.

Review source-root application fields already named `config`: move, rename, or
separately mount that data. The former names `configkit` and `_configkit` are now
ordinary application keys at every depth, with no control aliases. A permissive
schema can therefore accept an unmigrated control block as data without executing
its imports. Stored source-local declaration paths change from `/configkit/...`
to `/config/...`.

Source-version checks distinguish actual source-local controls from application
paths with the same spelling. Existing inheritance rules remain in place. See
[imports and control scope](../config.md#declaration-and-selection-rules) and
[the directive migration guidance](../config.md#earlier-directive-spelling).

### Public Go API

The following names replace their pre-v1 counterparts outright, without
compatibility aliases:

| Previous API | v1.0.0 API |
| --- | --- |
| `Resolution.InputInfo(path)` | `Resolution.EntryInfo(path)` |
| `Definition.Secret` | `Definition.Sensitive` |
| `SourceVersionModeDefault` | `SourceVersionModeMainOnly` |
| `SourceVersionCheck` | `SourceVersionEvidence` |
| `SourceInfo.VersionCheck` | `SourceInfo.VersionEvidence` |
| `ImportSelection` | `EmptyImportSelection` |
| `SourceInfo.ImportSelections` | `SourceInfo.EmptyImportSelections` |
| `SourceInfo.DestinationUnresolved` | `SourceInfo.DestinationIsFallback` |
| `ImportDefaults.Follow` / `.Hidden` | `FollowSymlinks` / `IncludeHidden` |
| `Paths(paths...)` | `SearchPaths(paths...)` |
| `LoadSecretsDir(directory)` | `LoadSecretsIntoEnvironment(directory)` |
| `LayerBase` | `LayerMain` |
| `CodeExplainLimitExceeded` | `CodeHistoryLimitExceeded` |
| `Resolution.Record(path, ChangeDerivedDefault, reason, deps...)` | `Resolution.RecordDerivedDefault(path, reason, deps...)` |
| `Resolution.Record(path, ChangeNormalization, reason, deps...)` | `Resolution.RecordNormalization(path, reason, deps...)` |

The recording methods describe mutations the application has already performed;
they do not assign values. `Default` and `Normalize` remain the helpers that both
assign and record. `EntryInfo` names the fixed resolution-entry metadata view,
including defaults and CLI assignments. Version evidence records what was
observed, not proof of checker execution or acceptance.

The redundant `ImportSelection.Outcome`, `ImportSelectionOutcome`, and
`ImportSelectionNone` are removed. Empty-selection records retain their selector,
path, and location. The obsolete diagnostic constants `CodeResolveInvalidKind`
and `CodeOptionsUnavailable` are also removed without replacements.

Update stored or compared strings as well as Go symbols:

- The main provenance layer changes from `"base"` to `"main"`.
- The retained-history limit diagnostic changes from
  `"explain.limit_exceeded"` to `"history.limit_exceeded"`.

The YAML import options `follow` and `hidden`, the `configkit:"secret"` Go tag,
and typed `Secret` references retain their existing spelling and behavior. See
the [API migration guide](../consumers/README.md#pre-v1-public-api-cleanup) for
the consolidated mapping and usage guidance. Rebuild and run your application's
configuration tests after migrating its imports, API calls, and source controls.

## Source inspection

`Result.Source(id)` and `LoadError.Source(id)` return a detached `SourceInfo`
record and a found flag for an already acquired source. They complement
`Sources()` and the existing callback-scoped `Resolution.Source(id)`. Empty or
unknown IDs return false. Lookup does not reopen inputs or resolve credentials;
failed loads retain the same partial, conservatively redacted evidence as their
source inventory. See [results and failures](../config.md#results-and-failures).

## Correctness and internal improvements

- Resolution presence queries distinguish numeric mapping keys from sequence
  indexes using the configuration's entry shape. A later shape change no longer
  transfers input explicitness to a different semantic path.
- Metadata history and value explanations now use one shared internal history
  model. This corrects attribution across shape changes, preserves container
  origins, and avoids duplicate intermediate source-history records.
- Final dynamically typed secret fields retain their sensitivity classification
  in inspection output. Parsed dependency paths are deduplicated without losing
  distinctions needed for sensitivity propagation.
- Composition-conflict diagnostics preserve claimant order through structured
  reporting and rendering, consistent with scoped assembly order.
- History selection and explanation use indexes and reuse prepared selections
  and sensitivity dependencies to reduce repeated traversal. Retained-history
  accounting follows the shared model, and secret resolution and validation share
  traversal machinery.

These changes preserve the documented loading and inspection rules apart from
the explicit migrations above. No end-to-end performance improvement is claimed.
The [configuration contract](../config.md) and public Go declaration comments
remain the behavior references.

## Requirements and release delivery

The consumer minimum rises from Go 1.26.0 to Go 1.27.0. Consumers must upgrade
their Go toolchain before adopting this release. The YAML dependency is unchanged.
Linux amd64 and arm64 remain the release-validated targets; macOS support remains
best-effort under the [platform support policy](../policy/release.md#platform-support).

Release tooling moves to `go.maximumdirect.net/releasekit` v0.6.0. Beginning with
this release, the source tag and checked-in note are accompanied by a Gitea release
page containing the complete note and licensing footer. Source publication and
hosted delivery remain separate outcomes under the [release procedure](../release.md).

[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/oss/attribution.md)