84 lines
5.9 KiB
Markdown
84 lines
5.9 KiB
Markdown
# 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](implementation.md) until
|
|
the maintainer retires completed roadmaps while preparing a release candidate.
|
|
|
|
The [architecture policy](../policy/architecture.md) owns responsibilities,
|
|
dependency direction, confidentiality, and the two success criteria. The
|
|
[configuration contract](../config.md) and Go declarations own implemented behavior.
|
|
The [consumer adoption guide](../consumers/README.md) owns consumer fit and migration
|
|
guidance. Accepted rationale remains in the [ADRs](../development.md#task-specific-reading-guide).
|
|
|
|
## 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](../internal/extraction.md)
|
|
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](../config.md) and Go reference comments |
|
|
| Paths, presence, origins, sources, and definition history | [Layered metadata](../config.md#layered-metadata), [`path.go`](../../path.go), and [`metadata.go`](../../metadata.go) |
|
|
| Strict composition, imports, globs, source identity, and profiles | [Strict composition](../config.md#strict-document-composition), [explicit imports](../config.md#explicit-imports), and [selected profiles](../config.md#selected-profiles) |
|
|
| Static defaults, null, types, projection, and custom text scalars | [Defaults and typed decoding](../config.md#defaults-and-typed-decoding), [schema binding](../config.md#application-schema-binding), and [typed projection](../config.md#typed-projection-and-ownership) |
|
|
| Schema versions, recorded resolution, and semantic validation | [Version contract](../config.md#application-schema-versions), [resolution](../config.md#recorded-application-resolution), and [validation](../config.md#semantic-validation) |
|
|
| Secret classification, typed references, and directory bootstrap | [Redaction](../config.md#secret-classification-and-effective-rendering), [references](../config.md#typed-secret-references), and [bootstrap](../config.md#explicit-secrets-directory-bootstrap) |
|
|
| Explicit CLI overrides and complete precedence | [CLI override contract](../config.md#explicit-cli-overrides) |
|
|
| Effective rendering and safe historical explanation | [Effective rendering](../config.md#secret-classification-and-effective-rendering) and [historical explanation](../config.md#historical-value-explanation) |
|
|
| Canonical module options and downstream adoption | [Module options](../config.md#canonical-module-options) and [consumer guide](../consumers/README.md) |
|
|
| Diagnostics and structured errors | [`records.go`](../../records.go), [`diagnostic.go`](../../diagnostic.go), and relevant configuration-contract sections |
|
|
| Internal components and dependency placement | [Component overview](../internal/overview.md) and [architecture policy](../policy/architecture.md) |
|
|
|
|
## 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.d` discovery;
|
|
- 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.
|