gnomonlearn
Docs/RFC-0046/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Configuration declarationA module-level config declaration that specifies a value’s name, type, default, and whether it’s a secret.
Configuration valueA typed name-bound value declared by a module and resolved by the runtime.
Feature flagA boolean configuration value with a queryable runtime API.
LayerOne source of configuration values (defaults, env vars, override files, secrets vault).
Resolution pipelineThe deterministic process that materializes the final value for each declared name from the layers.
SecretA configuration value tagged sensitive; resolved from a secret backend, redacted in logs and audit.
Secret backendA pluggable resolver for secret values: env, vault, aws-sm, gcp-sm, custom.

Diagnostics

CodeSeverityDescription
M46010FatalRequired configuration value missing from all four layers
M46011WarningOptional configuration value missing; falling back to declared default
M46020FatalPer-environment override file syntax error
M46021FatalConfiguration value parse error (type mismatch with declared type)
M46030ErrorCross-module configuration read attempted without exported: true
M46031WarningConfiguration name is shadowed by a higher-precedence layer; review intent
M46040FatalSecrets backend returned a transient error after retries
M46041ErrorSecret value resolved is empty/null; treat as missing
M46050DefectSensitive value leaked into log, audit, trace, or error emission
M46051WarningSecret cache TTL expired while in use; refreshing
M46060InfoConfiguration changed but hot reload is not enabled for this value; restart required
M46070WarningOperation references configuration via services.config.get without declaring uses { config(…) }
M46080WarningConfiguration value containing a credential pattern is not tagged sensitive: true
M46090ErrorPer-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

  1. Configuration is namespaced by declaring module; cross-module reads require exported: true. (enforced by: compile-time)
  2. Configuration values resolve from per-environment file, then env vars, then module defaultConfig, then declared default, in strict precedence order. (enforced by: runtime)
  3. Feature flags are a documented subset of configuration; core.flags.isEnabled is preferred over services.config.get for booleans. (enforced by: lint)
  4. Hot reload applies only to flag-marked configuration; non-flag configuration changes require restart. (enforced by: runtime)
  5. Operations should declare configuration dependencies via ‘uses { config(…) }’ to enable compile-time validation. (enforced by: compile-time)
  6. Per-tenant flag overrides are stored in the graph backend and may only be set via admin operations, not config files. (enforced by: runtime)
  7. Required configuration values with no resolved layer abort boot with diagnostic M46010. (enforced by: boot-time)
  8. Sensitive configuration values must be resolved through a registered secrets backend. (enforced by: runtime)
  9. Sensitive values must be redacted from logs, audit entries, span attributes, errors, and diagnostics. (enforced by: runtime)
  10. 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

  1. MUST — All sensitive values MUST be tagged sensitive: true; untagged credential-pattern values produce M46080. (proof citation: rfc0046_b21_grounded; verification pending)

Configuration Declaration

  1. MUST — Cross-module reads of configuration MUST be permitted only when the config is marked exported: true (M46030).
  2. MUST — If required is true and no layer supplies a value, boot MUST abort with M46010. (proof citation: rfc0046_b13_grounded; verification pending)
  3. MUST — If sensitive is true, the value MUST be loaded via the secrets backend.
  4. SHOULD — Modules SHOULD expose configuration through declared services rather than letting consumers read it directly. (proof citation: rfc0046_b19_grounded; verification pending)

Configuration Injection

  1. MUST — Operations holding configuration values for extended periods MUST re-read configuration if rotation is required. (proof citation: rfc0046_b15_grounded; verification pending)
  2. 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

  1. MUST — Per-tenant flag overrides MUST be set via an admin operation, not via configuration files. (proof citation: rfc0046_b5_grounded; verification pending)
  2. 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)
  3. SHOULD — core.flags.isEnabled SHOULD be preferred over services.config.get for boolean flags.

Resolution Layering

  1. 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)
  2. 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

  1. MUST — A secrets backend MUST expose the SecretsBackend interface with resolve and list methods.
  2. MUST — Implementations MUST track which configuration names are sensitive and apply redaction at every emission boundary.
  3. MUST — Secrets MUST be invalidated and re-resolved when the cache TTL expires. (proof citation: rfc0046_b8_grounded; verification pending)
  4. MUST — Secrets MUST be redacted from logs, audit entries, span attributes, error messages, and diagnostic outputs.
  5. MUST — The resolve method MUST return undefined (not throw) when a key is missing.

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0002
Depends onRFC-0005
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0008
Depends onRFC-0024
Depends onRFC-0033
Depends onRFC-0034
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040
Depends onRFC-0041
Depends onRFC-0045