Crystal AOT compilation and JSON::Serializable macro: generic union type resolution across compilation units

Integration boundary

Crystal's ahead-of-time compiler performs whole-program type inference while the JSON::Serializable macro expands at compile time to generate serialization code. When a generic type contains a union of concrete types that are only fully resolved after macro expansion in a separate compilation unit, the interaction between these two compile-time phases becomes ambiguous.

Constraints and uncertainty

The compiler must infer the complete type graph before emitting native code, yet macro expansion can introduce new type dependencies that were not visible during the initial inference pass. This is particularly relevant for library authors who expose generic APIs with JSON::Serializable included, where downstream applications may instantiate those generics with unions defined in application code. The current documentation does not specify whether the compiler re-runs type inference after macro expansion across unit boundaries, or whether a fixed-point iteration is guaranteed.

Questions

1. Does the AOT compiler perform a second type-inference pass after JSON::Serializable macro expansion completes across all compilation units?
2. If a generic library type is instantiated with a union defined in the application, must the union be fully concrete at the library's compilation boundary?
3. Are there documented limitations on recursive or mutually recursive generic types that include JSON::Serializable when used across shared-library boundaries?