ConfigKit/docs/adr/0004-secret-references-and-explicit-bootstrap.md

ADR 0004: Use secret references and explicit environment bootstrap

Status: accepted

Date: 2026-09-06

Context

Consumers need credentials without storing them in YAML and need a consistent way to load locally provisioned secret files. WeatherReporter already implements useful directory-loading code. Ordinary configuration loading must remain free of implicit process mutation, and operators must understand blocked secret files.

Decision

Represent secrets as ConfigKit-owned typed references to environment-variable names. Resolve only surviving references; retain names, never credentials, in configuration trees and inspection. Offer directory bootstrap as a separate, explicit startup operation, reusing WeatherReporter code where applicable. Existing environment variables win even when empty. Report skipped files and partial failures without values. Keep bootstrap provenance separate from later lookup provenance rather than imply an unchanged environment between calls. General environment-variable configuration overlays are not on the roadmap. The feature roadmap owns the unimplemented contract; stages remain in the implementation plan.

Alternatives considered

• Literal secrets or interpolated YAML: familiar but allows credentials into configuration artifacts and expands conventions and redaction obligations.
• Application-only directory loaders: keeps process mutation outside the library but preserves duplicated infrastructure and inconsistent skip/error semantics.
• Implicit bootstrap during loading: convenient but hides process mutation and makes repeated or concurrent loads difficult to reason about.
• Directory values overriding existing environment: simple, but defeats explicit deployment environment choices and obscures why a credential was selected.

Consequences

Applications migrate secret fields, choose startup ordering, and retain bootstrap reports. ConfigKit owns bounded loading, reference validation, safe reporting and inspection; applications own credential use. No multi-variable transaction or protection against concurrent process-environment mutation is promised.