RFC-0046 configuration resolution contract proposal
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.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: first-release proposal. Normative prose, Lean, and RDF remain unchanged pending the owner decision on public configuration semantics.
Contract gaps
- RFC-0046 §3.1 says every config value MUST appear in at least one layer,
while §4.2 and §4.1’s
required: falseimply optional config can remain absent. Section 7.1 definestryGetreturning null for absence. - Section 3.1 defines four value layers, with override file highest.
Section 4.2 says a
sensitive: truevalue MUST load via the secrets backend. Section 5.2 says a missing backend key falls back to a lower layer, but does not say whether lower-layer plaintext is allowed. The vault is absent from the precedence table. RFC-0045 §4.3 instead names bundle defaults, environment variables, then secrets vault as the boot layering sequence, omitting override files and declared defaults. - Section 3.3 uses
parseIntandparseFloatwith only a failure/NaN test. Those functions accept numeric prefixes of malformed strings such as12junk, violating the typed-validation goal in §1.Numberalso lacks a settled canonical value type, as recorded inRFC0046_CONFIGURATION_REVIEW.md. - The environment-variable pattern contains dotted module namespaces and
arbitrary config identifiers but does not define a reversible mapping to
portable process environment names. The example with underscores is not
a mapping rule for
core.platformversuscore_platform. - Section 6.2 describes
core.flagsas providing an API, but its RFC-0035 reference is marked future and the current framework does not establish it as a released implementation. The RFC should state the API as a required future contract until conformance fixtures pass. - Section 7.3 says values are resolved once at boot, but §§5.4 and 6.3 explicitly permit secret refresh and flag reload. The base snapshot and exceptions need separate names so consumers know what can change.
Recommended first-release semantics
- Resolve optional config to an explicit absent state. Only missing
required: truevalues produce M46010.tryGetreturns null for absent;requiredthrows post-boot if it becomes absent;getneeds a specified absent behavior instead of an implicit cast toT. - Use the four layers to choose a nonsecret value or a secret reference.
For
sensitive: true, never place plaintext in a checked-in override file or manifest default. The selected reference is resolved through the configuredSecretsBackend; theenvbackend may read an environment value. A missing secret reference can fall back to a lower reference only if that lower source is also secret-safe. A backend error aborts boot; it never silently falls back. Define the same ordering in RFC-0045. - Parse numeric env values as whole strings, rejecting trailing characters, infinities, and out-of-range values with M46021. Use the pending canonical numeric type decision to choose Decimal versus a new Number type.
- Map
GNOMON_CONFIG__<namespace-segment>__...__<config-name>to a config FQN by joining all namespace segments with.; preserve single underscores within each segment. Example:GNOMON_CONFIG__core__platform__pool_sizeaddressescore.platform.pool_size. Reject empty or ambiguous segments. - Specify
core.flagsas a normative API target with separate implementation conformance evidence. Publish no claim that it already runs until that implementation is verified. - Define a boot configuration snapshot for ordinary values. Secret rotation and optional flag reload replace individual snapshot entries atomically, with versioned reads for long-running operations.
Acceptance checks
- Optional absent config boots and returns null through
tryGet; required absent config fails boot with M46010. - Secret values never appear in checked-in overrides, generated manifests, logs, audit records, diagnostics, or trace attributes. A missing secret reference and a backend failure follow distinct paths.
- Numeric parsing rejects
12junk,NaN, infinities, and unsupported precision; the canonical numeric type is used end to end. - Environment names round-trip for dotted namespaces and identifiers with underscores, and two distinct FQNs never encode to one environment name.
- Flag/secret refresh is visible atomically; non-flag, nonsecret config stays at its boot snapshot until restart.