RFC-0046 · Configuration and Secrets
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
This RFC defines the layered configuration and secret resolution model that backs every Gnomon runtime. It replaces the legacy defaultConfig field’s scattered semantics with a normative four-layer resolution pipeline, specifies how typed configuration values are declared in .gnm source, defines the secret backend adapter protocol that lets vaults plug into the runtime, and specifies feature flags as queryable runtime state.
The design principle: configuration values are first-class, typed, statically validated. A module declares the configuration it needs; the runtime resolves values at boot; operations consume them via services.config.get(...). Missing required values are boot-time fatal errors, not runtime surprises.
2. Definitions
| Term | Meaning |
|---|---|
| Configuration value | A typed name-bound value declared by a module and resolved by the runtime. |
| Configuration declaration | A module-level config declaration that specifies a value’s name, type, default, and whether it’s a secret. |
| 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. |
| Feature flag | A boolean configuration value with a queryable runtime API. |
| 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. |
3. Resolution Layering
3.1 The four layers
Configuration values are resolved from four sources, listed highest to lowest precedence:
| Order | Layer | Source |
|---|---|---|
| 1 (highest) | Per-environment override file | <config-path>/config.<env>.gnm |
| 2 | Environment variables | GNOMON_CONFIG__<namespace>__<key> |
| 3 | Module defaultConfig | RFC-0040 §6 |
| 4 (lowest) | Declared default | The default slot on the configuration declaration (§4) |
Higher layers override lower layers. A value MUST be present in at least one layer; otherwise it’s a boot error (M46010).
3.2 Per-environment override files
The override path is configured by GNOMON_CONFIG_PATH (default: <bundle>/config). The active environment is configured by GNOMON_ENV (default: production). The runtime reads <GNOMON_CONFIG_PATH>/config.<GNOMON_ENV>.gnm at boot phase 2 (RFC-0045 §4.3).
The override file is an .gnm source file containing config-set declarations
as defined by RFC-0008 §8.18. config-set is a Schema-class declaration
restricted to these pure override files:
config-set core.platform.featureFlags = ["beta-ui", "experimental-search"]
config-set finance.budget.currency = "USD"
config-set graph.backend.poolSize = 64
Override files MUST NOT contain logic or imports. They are pure value declarations. Syntax violations are M46020.
3.3 Environment variables
Environment variables override per-module config using the convention from RFC-0045 §5.3:
GNOMON_CONFIG__<module-namespace>__<key> = <value>
The double-underscore separator delimits namespace boundaries. Underscores within identifiers are preserved (GNOMON_CONFIG__core_platform__feature_flags).
Values are parsed according to the configuration declaration’s type:
Text— taken verbatimInteger—Number.parseInt(value, 10); parse failure = M46021Number—Number.parseFloat(value); NaN = M46021Boolean—"true" | "1"→true,"false" | "0"→false; other = M46021List<T>— comma-separated, each element parsed asT- Structured types — JSON-decoded; invalid JSON = M46021
3.4 Module defaultConfig
Each module manifest’s defaultConfig (RFC-0040 §6) provides per-module defaults. These are the third-precedence layer.
3.5 Declared defaults
The default slot on a config declaration (§4) is the lowest-precedence layer — the value used if no other layer provides one.
4. Configuration Declaration
4.1 The config declaration kind
Modules declare their typed configuration via Schema-class config
declarations in .gnm source (or their YAML equivalent in module manifests).
RFC-0008 §8.18 owns the integrated source grammar:
config <name> {
meaning: <text>
type: <type-expr>
default: <literal>?
required: boolean (default true)
sensitive: boolean (default false)
description: <text>?
exported: boolean (default false)
flag: boolean (default false)
perTenant: boolean (default false)
}
Example:
config databasePoolSize {
meaning: "Maximum concurrent connections to the primary graph backend."
type: Integer
default: 32
required: false
}
config jwtSigningKey {
meaning: "HMAC signing key for session tokens (RFC-0048)."
type: Text
required: true
sensitive: true
}
4.2 Validation
At boot phase 2, the runtime validates every declared configuration name against the resolved layers:
- Find a value in the highest-precedence layer with a value.
- Parse it according to the declared type.
- If
required: trueand no layer supplied a value, abort boot (M46010). - If
sensitive: true, the value MUST be loaded via the secret backend (§5).
4.3 Configuration namespacing
Configuration names are namespaced by their declaring module. The full FQN is <module-namespace>.<config-name>. Operations and services reference values by FQN; the runtime resolves and injects them.
Cross-module configuration access is permitted but discouraged — modules SHOULD expose their configuration through declared services rather than letting consumers read it directly. Cross-module reads of configuration MUST be permitted only for config values that are explicitly marked exported: true (M46030 if not).
5. Secret Resolution
5.1 The secrets backend
When sensitive: true on a config declaration, the runtime delegates resolution to a secrets backend. The backend is selected via GNOMON_SECRETS_BACKEND (RFC-0045 §5.2). Recognized values:
| Backend | Source |
|---|---|
env | Environment variables only — the simplest backend, used in development |
vault | HashiCorp Vault (or compatible) |
aws-sm | AWS Secrets Manager |
gcp-sm | Google Cloud Secret Manager |
custom | Host-installed plugin |
5.2 Backend adapter protocol
A secrets backend MUST expose the interface:
SecretsBackend {
resolve(key: string): Promise<string | undefined>
list(prefix?: string): Promise<string[]>
}
The resolve method MUST return undefined (not throw) when a key is missing. The runtime distinguishes “not present” (use lower layer) from “backend error” (abort boot, M46040).
5.3 Key naming convention
Secret keys follow the pattern: <module-namespace>.<config-name> (lowercase, dot-separated). Backends MAY transform this naming (e.g., AWS Secrets Manager uses slashes; the adapter normalizes).
The legacy convention from RFC-0025 §3.1 (<ClientName>.token, etc.) is preserved as a special case: when a secret key matches the pattern <ClientName>.<credential-name>, the runtime MAY accept either form (auth.users.token or the legacy Auth.Users.token capitalized form).
5.4 Caching
Secrets MAY be cached in-memory after first resolution. Cache TTL is GNOMON_SECRETS_CACHE_TTL (default: 1 hour, minimum: 60 seconds). Secrets MUST be invalidated and re-resolved when the cache TTL expires.
5.5 Redaction
Secrets MUST be redacted from:
- Logs (their value MUST be replaced with
<redacted>before any log emission) - Audit log entries (RFC-0047)
- Span attributes (OpenTelemetry trace data)
- Error messages and stack traces
- Diagnostic outputs
Implementations MUST track which configuration names are sensitive and apply redaction at every emission boundary. Leakage of a sensitive value into any of the above is a defect (M46050).
6. Feature Flags
6.1 Declaration
A boolean configuration value MAY be declared as a feature flag:
config experimentalSearch {
meaning: "Enables experimental search-ranking algorithm."
type: Boolean
default: false
flag: true // marks this as a feature flag
}
The flag: true slot is informational — it makes the value queryable through the flag-specific runtime API.
6.2 Runtime API
The core.flags namespace (RFC-0035 §future) provides:
core.flags.isEnabled(name: Text): Boolean
core.flags.list(): List<{ name, enabled, source }>
isEnabled is the preferred consumer API for feature flags. It SHOULD be preferred over services.config.get for boolean flags because flag-specific tooling (lint, audit) tracks isEnabled references.
6.3 Hot reload
Feature flags MAY be hot-reloaded without runtime restart. When the per-environment override file (§3.2) changes on disk, the runtime SHOULD detect the change (via fsnotify or polling) and re-resolve all flag-marked configuration. Other configuration (non-flag) is NOT hot-reloaded; changing it requires a runtime restart.
The hot-reload behavior is implementation-optional. Hosts MAY require restart for all configuration changes (M46060 informational).
6.4 Per-tenant flags
In multi-tenant mode (GNOMON_TENANT_MODE=multi), feature flags MAY be set per-tenant:
config experimentalSearch {
...
flag: true
perTenant: true // permits per-tenant override
}
Per-tenant overrides are stored in the graph backend (a system-namespace Resource). The core.flags.isEnabled(name) API consults the per-tenant override before falling back to the global value. Per-tenant overrides MUST be set via an admin operation (RFC-0043), not via configuration files.
7. Configuration Injection
7.1 Service surface
Operation handlers and services access configuration via the runtime’s services.config capability:
services.config.get<T>(name: Text): T
services.config.tryGet<T>(name: Text): T | null
services.config.required<T>(name: Text): T // throws if missing (post-boot)
The configuration service is registered as a singleton provider (RFC-0040 §5.2) with capability scope core (resolvable from any context).
7.2 Static binding
The compiler MAY statically bind configuration references when the consumer’s source declares them:
operation submitOrder {
uses {
poolSize: config(core.platform.databasePoolSize)
}
...
}
The uses { ... config(...) } form makes the dependency explicit, enables compile-time validation (the named config must exist), and feeds the operation’s audit metadata.
Operations that reference configuration via services.config.get(...) without declaring the dependency SHOULD emit a lint warning (M46070).
7.3 Reload semantics
Configuration values are resolved once at boot (§3) and cached. Changes to the underlying source (env vars, files, secrets) do NOT propagate to running operations except via:
- Feature flags with hot reload enabled (§6.3)
- Secret rotation when the cache TTL expires (§5.4)
- Full runtime restart
Operations holding configuration values for extended periods (long-running sagas, event handlers) MUST re-read configuration if rotation is required.
8. Invariants
- The four-layer resolution order is normative: per-environment file > env vars > module defaultConfig > declared default (§3.1).
- Required configuration values without any layer providing them abort boot with M46010 (§4.2).
- Secret values MUST be resolved via a registered secrets backend (§5.1).
- Sensitive values MUST be redacted from all log, audit, trace, and error emissions (§5.5).
- Configuration is namespaced by declaring module; cross-module reads require explicit
exported: true(§4.3). - Feature flags are a documented subset of configuration (§6); the
core.flags.isEnabled(...)API is preferred over genericservices.config.get(...)for booleans. - Hot reload applies only to flag-marked configuration; non-flag configuration changes require restart (§6.3).
- Per-tenant flag overrides are stored in the graph backend and managed by admin operations, not config files (§6.4).
- Operations SHOULD declare configuration dependencies via
uses { config(...) }for compile-time validation (§7.2). - Secrets cache TTL is bounded; expired entries MUST be re-resolved (§5.4).
9. Compatibility and Migration
9.1 From legacy defaultConfig
The legacy defaultConfig field (RFC-0040 §6) is preserved as the third-precedence layer (§3.1). Existing modules need no migration; their values continue to apply but are now overridable by env vars and per-environment files.
9.2 From RFC-0025 §3.1 credential resolution
RFC-0025 §3.1 defines credential resolution for HTTP client declarations. This RFC supersedes that section’s resolution algorithm with the four-layer model:
| RFC-0025 §3.1 | This RFC |
|---|---|
| Per-environment secret binding | §3.2 (per-environment override file) |
| Process environment variable | §3.3 (env vars) |
| Runtime secret vault | §5 (secrets backend) |
The RFC-0025 §3.1 credential key naming (<ClientName>.token) is preserved as a special case (§5.3).
9.3 New requirements
- All sensitive values MUST be tagged
sensitive: true. Legacy modules that pass secrets throughdefaultConfigwithout tagging produce M46080 (lint). - Per-tenant flags MUST be admin-only (§6.4). Legacy code permits any operation to set per-tenant config; this RFC restricts.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.