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.

java_only_keys_set(cfg)

Real OSMOSE keys present in cfg that the Python engine does not read (inert on a Python run).

validate(cfg, mode)

Detect unknown config keys and dispatch per mode.

warn_unread_java_only_keys(cfg)

If cfg sets java-only keys, emit ONE deduped summary warning naming (up to _MAX_NAMED_JAVA_ONLY_KEYS of) them.

Classes

KnownKeys(patterns, literals, regexes)

UnknownKey(key, suggestion)