fix(serde): reject lossy float-to-int coercion and document the SerdeException contract

The strict-coercion config rejected string/boolean into integer fields but had
no rule for a floating-point JSON value into an integer field, so {"n":1.5}
silently bound into an Int as 1. That truncation turns a contract-violating
payload into a quietly wrong value, the exact class of bug the lockdown exists
to prevent. Add CoercionInputShape.Float to the LogicalType.Integer fail list
and pin the rejection with a test.

Also document the failure contract on the SPI itself: the core Serializer /
Deserializer interfaces now carry @throws SerializationException /
DeserializationException notes, and the internal Jackson overrides mirror them,
so a reader of the SPI sees the expected stable failure type rather than
learning it only from the Jackson adapter.

Author: OmarAlJarrah

sdk-core/src/main/kotlin/org/dexpace/sdk/core/serde/Deserializer.kt

@@ -23,15 +23,27 @@ import java.io.InputStream
  * For parametric targets (`List<MyDto>`, `Map<String, MyDto>`) the raw [Class] token is
  * insufficient; adapter modules expose their own type-reference entry points (e.g.
  * `sdk-serde-jackson`'s `JacksonSerde.deserializeAs`).
+ *
+ * Implementations surface decode failures as [DeserializationException] (a [SerdeException]
+ * subtype), chaining the backing codec's error as the cause, so callers catch a single stable SDK
+ * type without naming the underlying library.
  */
 public interface Deserializer {
-    /** Decode a complete document of [type] from the in-memory [input] string. */
+    /**
+     * Decode a complete document of [type] from the in-memory [input] string.
+     *
+     * @throws DeserializationException if [input] is malformed or does not match [type].
+     */
     public fun <T> deserialize(
         input: String,
         type: Class<T>,
     ): T
 
-    /** Decode a complete document of [type] from the in-memory [input] byte array. */
+    /**
+     * Decode a complete document of [type] from the in-memory [input] byte array.
+     *
+     * @throws DeserializationException if [input] is malformed or does not match [type].
+     */
     public fun <T> deserialize(
         input: ByteArray,
         type: Class<T>,
@@ -40,6 +52,9 @@ public interface Deserializer {
     /**
      * Decode a complete document of [type] by streaming from [inputStream]. The implementation owns
      * reading to EOF but **does not** close the stream — the caller retains ownership.
+     *
+     * @throws DeserializationException if the payload is malformed or does not match [type]. A
+     *   genuine stream-read [java.io.IOException] propagates unwrapped.
      */
     public fun <T> deserialize(
         inputStream: InputStream,

sdk-core/src/main/kotlin/org/dexpace/sdk/core/serde/Serializer.kt

@@ -17,15 +17,32 @@ import java.io.OutputStream
  * fresh `ByteArray`, stream into a caller-owned `OutputStream`, or stream into a caller-owned
  * scratch buffer. Stream / buffer overloads do **not** close their targets — the caller retains
  * ownership.
+ *
+ * Implementations surface encode failures as [SerializationException] (a [SerdeException] subtype),
+ * chaining the backing codec's error as the cause, so callers catch a single stable SDK type
+ * without naming the underlying library.
  */
 public interface Serializer {
-    /** Encode [input] and return the result as a new string. */
+    /**
+     * Encode [input] and return the result as a new string.
+     *
+     * @throws SerializationException if [input] cannot be encoded.
+     */
     public fun serialize(input: Any): String
 
-    /** Encode [input] and return the result as a freshly-allocated byte array. */
+    /**
+     * Encode [input] and return the result as a freshly-allocated byte array.
+     *
+     * @throws SerializationException if [input] cannot be encoded.
+     */
     public fun serializeToByteArray(input: Any): ByteArray
 
-    /** Stream [input]'s encoding into [outputStream]. The caller owns closing the stream. */
+    /**
+     * Stream [input]'s encoding into [outputStream]. The caller owns closing the stream.
+     *
+     * @throws SerializationException if [input] cannot be encoded. A genuine stream-write
+     *   [java.io.IOException] propagates unwrapped.
+     */
     public fun serialize(
         input: Any,
         outputStream: OutputStream,
@@ -38,6 +55,7 @@ public interface Serializer {
      * @throws IndexOutOfBoundsException when [offset] is negative or beyond [buffer]'s length, or
      *   when the encoded payload does not fit in the remaining space (`buffer.size - offset`). The
      *   buffer contents are unspecified after an overflow throw.
+     * @throws SerializationException if [input] cannot be encoded.
      */
     public fun serialize(
         input: Any,

sdk-serde-jackson/src/main/kotlin/org/dexpace/sdk/serde/jackson/JacksonObjectMappers.kt

@@ -95,12 +95,14 @@ public object JacksonObjectMappers {
      * so the rejection holds regardless of how a given scalar target consults coercion config:
      *
      *  - string → integer / floating-point / boolean (the headline `"5"` → numeric case),
+     *  - floating-point → integer (the lossy `1.5` → `1` narrowing),
      *  - boolean ↔ integer,
      *  - integer / floating-point / boolean → string.
      *
      * Untouched on purpose: numeric **widening** (an integer JSON value into a floating-point
      * field) stays legal because it is a representation-preserving conversion, not a shape mismatch;
-     * and genuinely typed values bind exactly as before.
+     * and genuinely typed values bind exactly as before. The inverse — a floating-point JSON value
+     * into an integer field — is rejected because it silently truncates (`1.5` → `1`).
      */
     private fun applyStrictScalarCoercion(builder: JsonMapper.Builder) {
         fun JsonMapper.Builder.failOn(
@@ -112,8 +114,14 @@ public object JacksonObjectMappers {
             }
 
         builder
-            // string "5"/"1.5"/"true" must not flow into numeric or boolean fields.
-            .failOn(LogicalType.Integer, CoercionInputShape.String, CoercionInputShape.Boolean)
+            // string "5"/"1.5"/"true" must not flow into numeric or boolean fields, and a
+            // floating-point value must not be lossily narrowed into an integer field (1.5 -> 1).
+            .failOn(
+                LogicalType.Integer,
+                CoercionInputShape.String,
+                CoercionInputShape.Boolean,
+                CoercionInputShape.Float,
+            )
             .failOn(LogicalType.Float, CoercionInputShape.String)
             .failOn(LogicalType.Boolean, CoercionInputShape.String, CoercionInputShape.Integer)
             // a non-string scalar must not be stringified into a textual field.

sdk-serde-jackson/src/main/kotlin/org/dexpace/sdk/serde/jackson/JacksonSerde.kt

@@ -112,10 +112,13 @@ public class JacksonSerde private constructor(
 internal class JacksonSerializer internal constructor(
     private val mapper: ObjectMapper,
 ) : Serializer {
+    /** @throws SerializationException if [input] cannot be encoded. */
     override fun serialize(input: Any): String = serializing { mapper.writeValueAsString(input) }
 
+    /** @throws SerializationException if [input] cannot be encoded. */
     override fun serializeToByteArray(input: Any): ByteArray = serializing { mapper.writeValueAsBytes(input) }
 
+    /** @throws SerializationException if [input] cannot be encoded. */
     override fun serialize(
         input: Any,
         outputStream: OutputStream,
@@ -129,6 +132,11 @@ internal class JacksonSerializer internal constructor(
         }
     }
 
+    /**
+     * @throws IndexOutOfBoundsException for a bad [offset] or overflow (thrown unwrapped, outside
+     *   the encode wrapper).
+     * @throws SerializationException if [input] cannot be encoded.
+     */
     override fun serialize(
         input: Any,
         buffer: ByteArray,
@@ -168,16 +176,19 @@ internal class JacksonSerializer internal constructor(
 internal class JacksonDeserializer internal constructor(
     private val mapper: ObjectMapper,
 ) : Deserializer {
+    /** @throws DeserializationException if [input] is malformed or does not match [type]. */
     override fun <T> deserialize(
         input: String,
         type: Class<T>,
     ): T = deserializing { mapper.readValue(input, type) }
 
+    /** @throws DeserializationException if [input] is malformed or does not match [type]. */
     override fun <T> deserialize(
         input: ByteArray,
         type: Class<T>,
     ): T = deserializing { mapper.readValue(input, type) }
 
+    /** @throws DeserializationException if the payload is malformed or does not match [type]. */
     override fun <T> deserialize(
         inputStream: InputStream,
         type: Class<T>,

sdk-serde-jackson/src/test/kotlin/org/dexpace/sdk/serde/jackson/JacksonObjectMappersTest.kt

@@ -116,4 +116,13 @@ class JacksonObjectMappersTest {
         // int -> double is a numeric widening, not a cross-shape coercion: it must keep working.
         assertEquals(Numbers(1, 2.0), mapper.readValue<Numbers>("""{"count":1,"ratio":2}"""))
     }
+
+    @Test
+    fun `floating-point for an integer field is rejected, not truncated`() {
+        val mapper = JacksonObjectMappers.defaultObjectMapper()
+        // 1.5 -> Int would silently truncate to 1; the lossy narrowing must fail loudly instead.
+        assertFailsWith<MismatchedInputException> {
+            mapper.readValue<Numbers>("""{"count":1.5,"ratio":2.0}""")
+        }
+    }
 }