Package-level declarations

Enums opt into mapping by implementing this interface; the processor maps via wireValue, never ordinal or name. W is the wire type (String or Int).

A reported-but-absorbed mapping event. Report rule: every event that loses data or stems from breakage is reported; declared-absence flows (null→null pass-through, absent→default, sanctioned null) are silent.

Base of all runtime mapping errors.

Listeners are observers: an exception thrown by a listener is suppressed and never affects the mapping or other listeners.

OnFail.Throw on List<T>: broken element → HARD typed MappingException at the indexed path; null element STILL skips with MappingDegradation.DroppedNullElement — absence stays type-driven under Throw. CancellationException rethrows untouched.

OnFail.Throw to Set<T>: broken element → HARD typed MappingException at the indexed path; null element skips with report; post-conversion convergence is reported. CancellationException rethrows untouched.

Element ladder, List<T?> default (alignment preserved): null element → null pass-through, silent; broken element → null-in-place + MappingDegradation.AbsorbedConversionError whose cause is the TYPED exception from toMappingException. Length and index alignment are preserved. Only Exceptions are absorbed: CancellationException and Errors always propagate.

OnFail.Throw on List<T?> ("optional but validated elements"): broken element → HARD typed MappingException at the indexed path; null element → null pass-through, silent. CancellationException rethrows untouched.

Element ladder, List<T> default (skip rung): null element → skip + MappingDegradation.DroppedNullElement (free filterNotNull); broken element → skip + MappingDegradation.DroppedBrokenElement whose cause is the TYPED exception from toMappingException at the indexed path; sanctioned null → silent skip. Relative order is preserved; element failure never escalates to the container. Only Exceptions are absorbed: CancellationException and Errors always propagate.

Set<T> default: always skip (null-in-place is degenerate in a set) — null element → skip + report; broken element → skip + MappingDegradation.DroppedBrokenElement with the TYPED cause; post-conversion convergence (distinct sources → same target) → MappingDegradation.ConvergedDuplicateElement at the LATER element's path. Survivors keep insertion order (LinkedHashSet). Only Exceptions are absorbed: CancellationException and Errors always propagate.

Map<K, V>, OnFail.Throw: broken key/value → HARD typed MappingException at the entry path, carrying the real type pair keyFrom→keyTo or valueFrom→valueTo; null source value skips with report (absence stays type-driven); key collision → last-wins + report. CancellationException rethrows untouched.

Map<K, V> default: each entry's key and value convert on their own ladders at path["key"], with the real type pairs keyFrom→keyTo and valueFrom→valueTo carried into typed causes. Broken key/value → drop entry + MappingDegradation.DroppedBrokenElement with the TYPED cause; null source value → drop + MappingDegradation.DroppedNullElement; sanctioned-null key/value → silent drop; post-conversion key collision → last-wins + MappingDegradation.DuplicateKey. Only Exceptions are absorbed: CancellationException and Errors always propagate.

Map<K, V?> (nullable target values): null source value → null-in-place, silent; broken value → null-in-place + MappingDegradation.AbsorbedConversionError with the TYPED cause carrying valueFrom→valueTo; broken key → drop entry + MappingDegradation.DroppedBrokenElement carrying keyFrom→keyTo; sanctioned-null key → silent drop; key collision → reported, value still written (last wins). Only Exceptions are absorbed: CancellationException and Errors always propagate.

Defaulted target, Auto (ladder rows 2/4/6/8): absent → fallback silent; sanctioned null → fallback silent; broken → fallback + MappingDegradation.AbsorbedConversionError whose cause is the TYPED exception from toMappingException. Only Exceptions are absorbed: CancellationException and Errors always propagate.

Nullable-default variant of convertOrElse, Auto: identical ladder, but the fallback is the target field's OWN default, which is statically nullable (val x: T? = …), so the landing type is T?. The copy stage reaches this overload whenever a nullable target field also carries a constructor default — base.x is then typed T?, which the non-null fallback: T overload cannot accept (issue #20). A null default and the type's null absence form coincide here, so source-null/sanctioned-null/broken all land on fallback (null in the common case), while a non-null declared default is still honoured (the ladder's "declared default" rung). Only Exceptions are absorbed: CancellationException and Errors always propagate.

Defaulted target, OnFail.Throw: broken → rethrow typed via toMappingException (hard); absent and sanctioned null → fallback, silent. CancellationException rethrows untouched.

Nullable-default variant of convertOrElseStrict (OnFail.Throw on a nullable defaulted target): broken → rethrow typed (hard); absent and sanctioned null → the (nullable) fallback. The same erasure-clash disambiguation as convertOrElse's nullable overload (issue #20). CancellationException rethrows untouched.

Hard cell (ladder rows 1/5, and OnFail.Throw on a non-null, no-default target), non-null receiver: ok → converted value; broken → typed MappingException via toMappingException. Nothing is reported — hard failures surface, they are not absorbed. CancellationException rethrows untouched (cancellation is a signal, never data).

Hard cell (ladder rows 1/5) with absence guard, nullable receiver: absent → MappingException.RequiredFieldMissing at path; otherwise behaves like the non-null convertOrFail.

Nullable target, Auto (ladder rows 3/7): absent → null silent; sanctioned null → null silent; broken → null + MappingDegradation.AbsorbedConversionError whose cause is the TYPED exception from toMappingException (metric pipelines stay pair-aware). Only Exceptions are absorbed: CancellationException and Errors always propagate.

Nullable target, OnFail.Throw: broken → rethrow typed via toMappingException (hard); absent and sanctioned null stay type-driven → null, silent. CancellationException rethrows untouched.

Compile-time diagnostic message for a type pair with no converter at all. Shared between the KSP MissingConverter diagnostic and any runtime reporting; there is intentionally NO MissingConverter exception type (compile-time-only).

Absence guard for Direct/seam-less landing sites: null receiver → MappingException.RequiredFieldMissing at path; non-null passes through unchanged.

Message for an intentionally-unsupported conversion direction. Used both by the KSP UnsupportedConversion diagnostic and by MappingException.UnsupportedConversion at runtime.