eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finalize the ConfigKit roadmap and implementation plan

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-06 13:59:01 -05:00
parent 9fc272f7a9
commit cc40880a22
10 changed files with 904 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/policy/architecture.md
View File

@@ -61,7 +61,10 @@ remote acquisition, runtime initialization, and resource checks.
Library code must not depend on consuming applications or initialize their
runtime resources. It must not perform implicit network access, discover
application-specific paths, or change process-global state to load configuration.
application-specific paths, or change process-global state during ordinary `Load`.
The explicit secrets-directory bootstrap is a narrow, opt-in exception: applications
invoke it during startup, and it reports writes, skips and partial failures. It
must never run implicitly as part of configuration loading.
Remote data can enter through application-supplied input without introducing a
network provider into the library.
@@ -90,10 +93,20 @@ parser defaults. Processing order and diagnostics must be deterministic for the
same inputs and options. Invalid input must not produce a successful usable
configuration. Do not run application hooks on invalid typed configuration.
Preserve presence and source information through processing. Ordinary Go zero
User-controlled precedence is application defaults, composed base, selected
profile, then explicitly supplied CLI overrides. Applications own flag parsing;
ConfigKit owns overlay semantics and provenance. Domain resolution follows these
inputs and must remain recorded, not become a hidden override channel.
Preserve node-based composition until the effective input is ready for typed
decoding. Preserve presence and source information through processing. Ordinary Go zero
values must not be used to infer whether input was absent. Final configuration,
metadata, and effective inspection must agree, including application resolution
changes; see [ADR 0003](../adr/0003-preserve-presence-and-resolution-history.md).
Safe historical values and an explanation renderer belong to the initial target,
including superseded/deleted paths and effective source attribution. Inspection
must agree with the final typed snapshot and apply historical sensitivity rules.
See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
Detailed syntax and operation tables belong to the target roadmap until their
current configuration contract is implemented.
@@ -104,6 +117,14 @@ ConfigKit must not mutate a result after returning it. Ordinary exported Go
values are not language-enforced immutable objects; document caller ownership
and the lifetime of captured metadata without promising otherwise.
Secret values enter configuration through typed environment-name references;
literal credentials are not a supported configuration convention. Only an explicit
accessor exposes a resolved credential to application code. Credential bytes must
never enter composition trees, history, or inspection. General environment-variable
configuration overlays are an explicit non-goal. Bootstrap must preserve already
set variables, including empty ones, and report blocked files without contents.
See [ADR 0004](../adr/0004-secret-references-and-explicit-bootstrap.md).
Secrets must be considered throughout error handling and inspection. Library
renderers must apply secret classification, and parser errors must not be
forwarded blindly when they can include raw input. Do not log configuration