Module heal 

Self-healing engine (C-016).

Phase 1 (syntactic repair) lives in the lexer (H001: unclosed strings) and parser (H002: trailing commas, H003: missing commas, H004: bracket recovery). This module hosts:

• Phase 2 (semantic key repair): similarity scoring and best-candidate selection over a set of legal keys, wired to schema-controlled tables in validation (H005 suggestions in strict mode, guarded auto-rename under resilient mode).
• Phase 3 (type/constraint healing): safe coercion functions, wired to validation mismatches (H007 under resilient mode) with sentinel recognition in strict messages.

Functions

best_key_match

Choose the best matching key from a legal set. Only candidates with similarity ≥ threshold are considered; on an exact tie the earliest candidate in argument order wins.

coerce_string_to

Safe string → target-type coercion, applied only when a type error is detected but the value is a string that could reasonably become the expected type. Returns the coerced value or None.

heal

Run the self-healing passes over a module. Returns the number of repairs recorded. Phase 1 repairs are already in module.healing; phases 2 and 3 run schema-driven inside validation (H005/H007), which owns the schema tree and the evaluated values they need.

key_similarity

Composite similarity score blending three independent signals with a noisy-OR: edit distance (primary), keyboard adjacency, and phonetics. Any single strong signal can push the score high, while weak signals reinforce each other. 0.0–1.0.

keyboard_similarity

Keyboard-layout similarity: how close two strings are on a QWERTY layout. Returns 0.0–1.0; 1.0 means every character is on the same or an adjacent key. Only meaningful for strings of equal length.

make_key_typo_diagnostic

Build an H005 (key typo suggestion) diagnostic.

normalized_levenshtein

Normalized string-similarity based on optimal string alignment (the restricted Damerau-Levenshtein variant): 1.0 for identical strings, 0.0 when every character differs. Case-insensitive, and a transposition (the most common typo, prot/port) counts as a single edit.

phonetic_similarity

Phonetic similarity via a simplified Soundex-style Metaphone. 1.0 when the encodings match, 0.0 otherwise.

sentinel_meaning

Map a sentinel word to its conventional intent. Sentinels are not values — they signal intent. The schema layer resolves the concrete value (e.g. “unlimited” under Int(min=0) might become -1).

try_coerce_duration

Try to parse a string as a duration: 5s, 300ms, 1.5h. Returns milliseconds on success.

try_coerce_int

Try to coerce a string that looks like an integer. Rejects signs that are more likely formatting than numbers.