Defines a typed configuration contract, explicit precedence, secret references, startup validation, immutable deployment snapshots, and safe rotation so environments differ intentionally rather than through hidden state.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Ship one application artifact across environments and supply versioned configuration at deployment. Validate a typed schema before readiness, resolve secrets by reference through an approved store, and record a redacted effective-config digest.
Scope
- Configuration schema, defaults, sources, precedence, environments, secrets, validation, rollout, reload, rotation, drift, and diagnostics.
- Runtime settings for deployed services and workers.
- Local-development and test profiles without production credentials.
Outside this block
- Building environment-specific application binaries.
- Checking secret values into repositories or diagnostic bundles.
Contract
- Every setting declares type, requiredness, safe default if any, sensitivity, mutability, owner, and validation constraints.
- Precedence is fixed and observable; an unknown key or invalid value fails validation rather than being ignored silently.
- Environment names select a profile, not arbitrary conditionals scattered through domain code.
- Secret configuration stores a reference or injected value outside normal logs and generated client bundles.
- Each deployment records schema version and a digest of redacted effective values.
- Dynamic reload is allowed only for settings marked reloadable and applies atomically with rollback to the prior valid snapshot.
Implementation guidance
- Generate documentation and deployment validation from the same schema consumed at startup.
- Separate compile-time feature availability from runtime feature policy.
- Use workload identity and secret-store access instead of long-lived shared credentials where available.
- Test production-like missing, malformed, deprecated, and rotated settings in CI or staging.
Failure handling and safeguards
- A missing required secret keeps readiness false without printing its value.
- A partially failed reload leaves the complete previous snapshot active.
- Detected drift opens an explicit reconciliation path; automation does not overwrite an emergency change without policy.
Verification and operations
- Measure validation failures, deprecated/unknown key use, reload success, config drift, secret rotation age, and deployment digest distribution.
- Alert when replicas of one release use unexpected digests.
- Exercise secret rotation without full downtime and verify old credentials are revoked.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.