v1.0.0 c88aac990b

ConfigKit v1.0.0 Stable

eric released this 2026-11-02 01:17:02 +00:00 | 0 commits to main since this release

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.

Downloads

1 Release 19 Tags