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

Short answer

1. No second pass is needed: macro expansion finishes before type inference begins, and inference runs once over the fully expanded program.
2. No: Crystal has no separate compilation units, so there is no library boundary at which a union must be "fully concrete." Everything is compiled whole-program from source.
3. Recursive types work, but there is no shared-library boundary for Crystal generics at all; complex recursive graphs may need explicit type annotations.

Why the premise doesn't quite apply

The question assumes a C/C++-style model with separate compilation units and a boundary between "library code" and "application code." Crystal does not work that way. The compiler always performs whole-program compilation: every reachable source file (via require) is parsed into a single program, and there is one semantic analysis pass over all of it. A generic in a shard and a union in your application are typed together, in the same pass.

The pipeline is roughly:

1. Parse + macro expansion. Including JSON::Serializable is a macro module: it expands from_json/to_json methods into the AST. This happens before any typing.
2. Semantic analysis / type inference. Runs once, over the already-expanded program. So types introduced by macro expansion are fully visible to inference — there is no "re-run inference after macros" step because inference only starts after expansion.
3. Codegen. Generic instantiations are only typed (and emitted) when used: Wrapper(T) is not compiled until something writes Wrapper(A | B).

Generic + union instantiation

When you write Wrapper(A | B), the compiler instantiates the generic once with T = (A | B) and types the body under that binding. Because compilation is whole-program, A and B can live in application code while Wrapper lives in a shard — it makes no difference. For JSON::Serializable, the generated deserialization for a union-typed field uses the stdlib's union path (try each member in order, first match wins), and that code is itself macro-expanded before typing, so application-defined union members are handled exactly like stdlib types.

Shared libraries and recursion

Crystal has no stable ABI and no way to ship a compiled generic Crystal API for separate instantiation — "across shared-library boundaries" does not apply. Recursive and mutually recursive types are supported (the stdlib's own JSON::Any is a recursive alias), and JSON::Serializable works with them. The practical limits are compile time and occasional recursive-type inference errors that require an explicit annotation (e.g., on an ivar or getter) to break the cycle.

Verify it yourself

# wrapper.cr
class Wrapper(T)
  include JSON::Serializable
  getter value : T
end

class A
  include JSON::Serializable
  getter x : Int32
end

class B
  include JSON::Serializable
  getter y : String
end

w = Wrapper(A | B).from_json(%({"value":{"y":"hi"}}))
pp w

crystal build wrapper.cr && ./wrapper
crystal tool expand -c wrapper.cr:3  wrapper.cr   # inspect generated code

crystal tool expand shows the macro output before typing, confirming expansion precedes inference. One caveat to test in your own code: for overlapping union members (e.g., Int32 | Float64 or two similar serializable types), deserialization tries members in order and the first match wins, which can surprise.

Version note: this describes Crystal's long-standing whole-program design (true across 1.x); exact pipeline internals are compiler-version sensitive. If you hit a recursive-inference error, the missing diagnostic is your Crystal version and the exact error message.