gnomonlearn
Docs/RFC-0046 configuration resolution contract proposal

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

  1. RFC-0046 §3.1 says every config value MUST appear in at least one layer, while §4.2 and §4.1’s required: false imply optional config can remain absent. Section 7.1 defines tryGet returning null for absence.
  2. Section 3.1 defines four value layers, with override file highest. Section 4.2 says a sensitive: true value 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.
  3. Section 3.3 uses parseInt and parseFloat with only a failure/NaN test. Those functions accept numeric prefixes of malformed strings such as 12junk, violating the typed-validation goal in §1. Number also lacks a settled canonical value type, as recorded in RFC0046_CONFIGURATION_REVIEW.md.
  4. 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.platform versus core_platform.
  5. Section 6.2 describes core.flags as 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.
  6. 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.
  • Resolve optional config to an explicit absent state. Only missing required: true values produce M46010. tryGet returns null for absent; required throws post-boot if it becomes absent; get needs a specified absent behavior instead of an implicit cast to T.
  • 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 configured SecretsBackend; the env backend 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_size addresses core.platform.pool_size. Reject empty or ambiguous segments.
  • Specify core.flags as 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

  1. Optional absent config boots and returns null through tryGet; required absent config fails boot with M46010.
  2. 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.
  3. Numeric parsing rejects 12junk, NaN, infinities, and unsupported precision; the canonical numeric type is used end to end.
  4. Environment names round-trip for dotted namespaces and identifiers with underscores, and two distinct FQNs never encode to one environment name.
  5. Flag/secret refresh is visible atomically; non-flag, nonsecret config stays at its boot snapshot until restart.