osmose.engine.config_validation

Unknown-key validation for OSMOSE EngineConfig.from_dict().

Spec: docs/superpowers/specs/2026-04-19-config-validation-design.md (557ee1b).

Match order (fast -> slow):

  1. Exact literal lookup in KnownKeys.literals (O(1) set).

  2. Normalized-pattern lookup in KnownKeys.patterns (O(1) set) – converts user’s concrete key (species.linf.sp47) to pattern form (species.linf.sp{idx}) segment-by-segment.

  3. Regex match across KnownKeys.regexes (~15 compiled patterns).

  4. Miss -> UnknownKey with optional difflib suggestion (cutoff 0.85 against normalized pattern-form strings on both sides).

Functions

build_known_keys()

Union of ParameterRegistry field patterns + AST-extracted reader keys.

validate(cfg, mode)

Detect unknown config keys and dispatch per mode.

Classes

KnownKeys(patterns, literals, regexes)

UnknownKey(key, suggestion)