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. 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.

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 and the directive migration guidance.

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 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.

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 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.

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.

COPYRIGHT | LICENSE | ATTRIBUTION