5.9 KiB
ConfigKit Initial Target Record
Status and ownership
The initial feature target is implemented. This document now records the intended outcome, source foundations, and deliberately deferred scope without duplicating the current configuration contract or Go API reference. Ordered implementation history and acceptance evidence remain in the implementation plan until the maintainer retires completed roadmaps while preparing a release candidate.
The architecture policy owns responsibilities, dependency direction, confidentiality, and the two success criteria. The configuration contract and Go declarations own implemented behavior. The consumer adoption guide owns consumer fit and migration guidance. Accepted rationale remains in the ADRs.
Initial outcome
ConfigKit is one opinionated Go library for strict YAML configuration loading. It removes source handling, parsing, explicit import/profile traversal, composition, precedence, presence tracking, provenance, secret lookup/bootstrap, diagnostics, and safe inspection plumbing from applications. Applications retain their types, defaults, schema-version policy, recorded normalization, semantic validation, CLI parsing, remote acquisition, domain algorithms, resource checks, and runtime setup.
The maintained Narratio-, Notarius-, WeatherReporter-, and Seriatim-shaped examples demonstrate both architecture success criteria: simple consumers avoid optional composition machinery, complex consumers use the same conventions, and domain logic remains recognizable application code. These examples are migration evidence, not a claim that any sibling application has migrated.
Implementation foundations
The implementation was generalized from maintainer-authorized application code and tests at fixed clean revisions. The extraction inventory records exact revisions, symbols, adapted cases, intentional semantic differences, and the boundary that keeps sibling checkouts out of builds and tests. Links from that inventory or historical implementation evidence to sibling source are optional in isolated clones; immutable revision references remain authoritative evidence.
The module uses go.yaml.in/yaml/v4 only behind internal/yaml. ConfigKit owns the
document model, field binding, scalar grammar, errors, limits, and output behavior.
No upstream type, option, plugin, error chain, hidden parser value, or generic
constraint crosses the public API. The package-level import-boundary test enforces
this isolation for production, tests, and maintained examples.
Current feature owners
| Initial feature area | Current owner |
|---|---|
| Sources, lifecycle, limits, YAML/scalars, decoding, and ownership | Configuration contract and Go reference comments |
| Paths, presence, origins, sources, and definition history | Layered metadata, path.go, and metadata.go |
| Strict composition, imports, globs, source identity, and profiles | Strict composition, explicit imports, and selected profiles |
| Static defaults, null, types, projection, and custom text scalars | Defaults and typed decoding, schema binding, and typed projection |
| Schema versions, recorded resolution, and semantic validation | Version contract, resolution, and validation |
| Secret classification, typed references, and directory bootstrap | Redaction, references, and bootstrap |
| Explicit CLI overrides and complete precedence | CLI override contract |
| Effective rendering and safe historical explanation | Effective rendering and historical explanation |
| Canonical module options and downstream adoption | Module options and consumer guide |
| Diagnostics and structured errors | records.go, diagnostic.go, and relevant configuration-contract sections |
| Internal components and dependency placement | Component overview and architecture policy |
Explicit non-goals and deferred scope
General environment-variable configuration overlays are not supported. Typed secret references and explicit directory bootstrap are the environment convention. Literal credential configuration and implicit secret-directory discovery are unsupported.
The initial release deliberately excludes:
- automatic
conf.ddiscovery; - remote imports, arbitrary providers, and additional configuration formats;
- custom merge strategies, sequence merging, reset operators, and profile inheritance;
- parser-specific or custom structural-decoding extension APIs;
- generic dynamic-subtree conversion and module-registry APIs;
- automatic schema migrations;
- hot reload, runtime resource replacement, and remote resource validation;
- a bundled CLI framework or application commands; and
- configuration diffs and fingerprints.
Applications may build their own validate, effective-value, source, bootstrap, and explanation commands around the library. Broadening these boundaries requires concrete consumer evidence, compatibility review, and an explicit design change.