RFC-0046 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0046: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0046.This page is generated from the
lean/Gnomon/Spec/module for RFC-0046. Edit that source and regenerate this catalog.
Title: Configuration and Secrets
Status: draft
Owners: Module Platform, Runtime
Diagnostic range: M46000-M46099
Depends on: RFC-0001, RFC-0002, RFC-0005, RFC-0006, RFC-0007, RFC-0008, RFC-0024, RFC-0033, RFC-0034, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040, RFC-0041, RFC-0045
Proof citations in source: 10 / 10. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Configuration declaration | A module-level config declaration that specifies a value’s name, type, default, and whether it’s a secret. |
| Configuration value | A typed name-bound value declared by a module and resolved by the runtime. |
| Feature flag | A boolean configuration value with a queryable runtime API. |
| Layer | One source of configuration values (defaults, env vars, override files, secrets vault). |
| Resolution pipeline | The deterministic process that materializes the final value for each declared name from the layers. |
| Secret | A configuration value tagged sensitive; resolved from a secret backend, redacted in logs and audit. |
| Secret backend | A pluggable resolver for secret values: env, vault, aws-sm, gcp-sm, custom. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M46010 | Fatal | Required configuration value missing from all four layers |
M46011 | Warning | Optional configuration value missing; falling back to declared default |
M46020 | Fatal | Per-environment override file syntax error |
M46021 | Fatal | Configuration value parse error (type mismatch with declared type) |
M46030 | Error | Cross-module configuration read attempted without exported: true |
M46031 | Warning | Configuration name is shadowed by a higher-precedence layer; review intent |
M46040 | Fatal | Secrets backend returned a transient error after retries |
M46041 | Error | Secret value resolved is empty/null; treat as missing |
M46050 | Defect | Sensitive value leaked into log, audit, trace, or error emission |
M46051 | Warning | Secret cache TTL expired while in use; refreshing |
M46060 | Info | Configuration changed but hot reload is not enabled for this value; restart required |
M46070 | Warning | Operation references configuration via services.config.get without declaring uses { config(…) } |
M46080 | Warning | Configuration value containing a credential pattern is not tagged sensitive: true |
M46090 | Error | Per-tenant flag override attempted from a non-admin operation |
Dependency neighborhood
graph LR
nRFC_0046["RFC-0046"]
nRFC_0001["RFC-0001"]
nRFC_0046 --> nRFC_0001
nRFC_0002["RFC-0002"]
nRFC_0046 --> nRFC_0002
nRFC_0005["RFC-0005"]
nRFC_0046 --> nRFC_0005
nRFC_0006["RFC-0006"]
nRFC_0046 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0046 --> nRFC_0007
nRFC_0008["RFC-0008"]
nRFC_0046 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0046 --> nRFC_0024
nRFC_0033["RFC-0033"]
nRFC_0046 --> nRFC_0033
nRFC_0034["RFC-0034"]
nRFC_0046 --> nRFC_0034
nRFC_0036["RFC-0036"]
nRFC_0046 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0046 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0046 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0046 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0046 --> nRFC_0040
nRFC_0041["RFC-0041"]
nRFC_0046 --> nRFC_0041
nRFC_0045["RFC-0045"]
nRFC_0046 --> nRFC_0045
Invariants
- Configuration is namespaced by declaring module; cross-module reads require exported: true. (enforced by: compile-time)
- Configuration values resolve from per-environment file, then env vars, then module defaultConfig, then declared default, in strict precedence order. (enforced by: runtime)
- Feature flags are a documented subset of configuration; core.flags.isEnabled is preferred over services.config.get for booleans. (enforced by: lint)
- Hot reload applies only to flag-marked configuration; non-flag configuration changes require restart. (enforced by: runtime)
- Operations should declare configuration dependencies via ‘uses { config(…) }’ to enable compile-time validation. (enforced by: compile-time)
- Per-tenant flag overrides are stored in the graph backend and may only be set via admin operations, not config files. (enforced by: runtime)
- Required configuration values with no resolved layer abort boot with diagnostic M46010. (enforced by: boot-time)
- Sensitive configuration values must be resolved through a registered secrets backend. (enforced by: runtime)
- Sensitive values must be redacted from logs, audit entries, span attributes, errors, and diagnostics. (enforced by: runtime)
- The secrets cache TTL is bounded and expired entries must be re-resolved from the backend. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — All sensitive values MUST be tagged sensitive: true; untagged credential-pattern values produce M46080. (proof citation:
rfc0046_b21_grounded; verification pending)
Configuration Declaration
- MUST — Cross-module reads of configuration MUST be permitted only when the config is marked exported: true (M46030).
- MUST — If required is true and no layer supplies a value, boot MUST abort with M46010. (proof citation:
rfc0046_b13_grounded; verification pending) - MUST — If sensitive is true, the value MUST be loaded via the secrets backend.
- SHOULD — Modules SHOULD expose configuration through declared services rather than letting consumers read it directly. (proof citation:
rfc0046_b19_grounded; verification pending)
Configuration Injection
- MUST — Operations holding configuration values for extended periods MUST re-read configuration if rotation is required. (proof citation:
rfc0046_b15_grounded; verification pending) - SHOULD — Operations referencing configuration via services.config.get without declaring uses { config(…) } SHOULD emit a lint warning (M46070). (proof citation:
rfc0046_b10_grounded; verification pending)
Feature Flags
- MUST — Per-tenant flag overrides MUST be set via an admin operation, not via configuration files. (proof citation:
rfc0046_b5_grounded; verification pending) - SHOULD — When the per-environment override file changes on disk, the runtime SHOULD detect the change and re-resolve flag-marked configuration. (proof citation:
rfc0046_b1_grounded; verification pending) - SHOULD — core.flags.isEnabled SHOULD be preferred over services.config.get for boolean flags.
Resolution Layering
- MUST — Configuration values MUST be present in at least one of the four resolution layers, otherwise boot fails (M46010). (proof citation:
rfc0046_b24_grounded; verification pending) - MUST_NOT — Per-environment override files MUST NOT contain logic or imports; they are pure value declarations. (proof citation:
rfc0046_b3_grounded; verification pending)
Secret Resolution
- MUST — A secrets backend MUST expose the SecretsBackend interface with resolve and list methods.
- MUST — Implementations MUST track which configuration names are sensitive and apply redaction at every emission boundary.
- MUST — Secrets MUST be invalidated and re-resolved when the cache TTL expires. (proof citation:
rfc0046_b8_grounded; verification pending) - MUST — Secrets MUST be redacted from logs, audit entries, span attributes, error messages, and diagnostic outputs.
- MUST — The resolve method MUST return undefined (not throw) when a key is missing.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0002 |
| Depends on | RFC-0005 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Depends on | RFC-0033 |
| Depends on | RFC-0034 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |
| Depends on | RFC-0041 |
| Depends on | RFC-0045 |