As a principal engineer, when would you mandate @Contextual over @Serializable(with=...) across a large/multiplatform codebase, and what are the systemic risks and governance practices?

## The core trade-off `@Serializable(with = ...)` binds a serializer at **compile time** — safe, fixed, no module. `@Contextual` binds at **runtime** via a `SerializersModule` — flexible, pluggable, but can throw `SerializationException` when resolution fails. At scale, the question is when the flexibility is worth surrendering compile-time guarantees. ## When to mandate @Contextual - **Multiplatform divergence**: a `commonMain` data class references `Instant`/`Date`-like types whose ideal serializer differs per target (JVM vs JS vs Native), or you want each platform to register its own. `@Contextual` lets `commonMain` stay neutral while each platform supplies a module. - **Library pluggability**: you publish data classes and want consumers to decide how a type serializes without forking your code. Expose `@Contextual` and document the expected module registration. - **Multi-format systems**: the same type must be a Long in CBOR storage but an ISO string in public JSON. One data class, two modules, two formats — `@Contextual` is the only clean way. - **Cross-cutting policy**: e.g. money types serialized per-locale or per-tenant, decided at request time. ## When to forbid it If exactly one strategy is ever used, `@Serializable(with=...)` (or a `typealias` with the serializer) is strictly better: the compiler proves the serializer exists, and you cannot ship a missing-registration bug. ## Systemic risks ```kotlin // Risk: forgotten module => runtime explosion deep in a rare path val json = Json { /* serializersModule not set! */ } ``` 1. **Runtime-failure surface**: each contextual type is a path that can throw if unregistered; rare paths hide the bug until production. 2. **Module drift**: service A registers Date-as-Long, service B as ISO string → cross-service encode/decode breaks. The wire contract now lives in scattered module code, not the data class. 3. **Descriptor stability**: changing a contextual serializer's `descriptor` (name/kind) silently changes the schema; consumers and stored data break. 4. **Composition hazards**: `moduleA + moduleB` throws on duplicate class registration; `overwriteWith` silently overrides — both are easy to get wrong as modules proliferate. 5. **Polymorphism interplay**: contextual and polymorphic registrations in the same module must not collide; large modules grow accidental conflicts. ## Governance practices - **One canonical module**: define a single `appSerializersModule` (composed from sub-modules) and inject it everywhere; forbid ad-hoc `Json { }` without it (lint/architecture test). - **Test every contextual path**: a round-trip test per contextual type so missing registrations fail in CI, not production. - **Pin descriptors as contract**: treat serial names/kinds as part of the public schema; review changes like API changes. - **Document the registry**: a living list of contextual types + their serializers + rationale, so engineers know what's late-bound. - **Prefer with= by default**: make `@Contextual` an opt-in that requires justification in review. ## Bottom line `@Contextual` is dependency injection for serializers. Use it where genuine variability or pluggability exists, govern it like shared infrastructure, and default to compile-time binding everywhere else.