WolverineFx.AI: source-generated response schemas so LLM callouts are AOT-clean

[jeremydmiller]

WolverineFx.AI ships with <IsAotCompatible>false</IsAotCompatible>. This is the follow-up to make it trim- and AOT-clean.

Why it isn't today

A callout names its response type as a string on the message (LlmCallout.ResponseType) rather than as a type parameter — see decision 7 on #4227 for why. LlmCalloutExecutor then does two reflective things with the Type it resolves from that string, neither of which the trimmer can follow from any static call site:

1. AIJsonUtilities.CreateJsonSchema(responseType, ...) — walks the response type's properties to build the schema handed to the model as ChatResponseFormat.ForJsonSchema.
2. JsonSerializer.Deserialize(text, responseType, options) — turns the model's answer back into the response type.

LlmCalloutExecutor carries [RequiresUnreferencedCode] / [RequiresDynamicCode] rather than a suppression, deliberately: a suppression here would claim a guarantee the design cannot make. Under a trimmed publish the response type's properties can be trimmed away, and the schema and the deserialization both silently degrade rather than failing loudly.

Note that this is not the same problem the non-generic decision solved. That one was about resolving a name to a Type at all on a cold start, and it is fixed. This one is about what the trimmer can prove about that type once resolved, and it is unchanged by the message's shape — a generic LlmCallout<T> would need exactly the same work here.

What it would take

• Source-generated JSON schemas. Discover the response types an application actually asks for and emit their schemas at compile time, so CreateJsonSchema never runs at all in an AOT app. The natural trigger is the Ask<TResponse>(...) call sites, which are statically visible in the common handler and HTTP-endpoint cases; a [LlmResponse]-style attribute would be the escape hatch for the cases a call-site scan cannot see (a callout constructed inside a projection's RaiseSideEffects, say).
• A generated JsonSerializerContext over the same set, fed to LlmCalloutOptions.JsonSerializerOptions so the deserialization is source-generated too.
• A runtime lookup keyed by the same identifier the message already carries, so the executor consults the generated table first and falls back to reflection only on the non-AOT path.
• Flip IsAotCompatible to true, drop the [Requires*] annotations, and cover it in the AOT publishing guide.

Worth doing alongside, or after, whatever shape the tier 2 agents work (#4226) needs — tool schemas have the same generation problem, and it would be a shame to build the generator twice.

[jeremydmiller]

The schema generator isn't needed

I wrote this issue assuming source-generated schemas were the requirement. They are not. AIJsonUtilities.CreateJsonSchema(Type, ...) carries no trim or AOT annotations at all — it builds the schema from whatever JsonTypeInfo the supplied JsonSerializerOptions resolve, so handing it options backed by an ordinary source-generated JsonSerializerContext already makes schema generation reflection-free. No new generator, and nothing for Wolverine to emit.

Verified rather than inferred from an absent attribute: a native AOT publish (TrimMode=full, IL codes as errors) generates the correct schema from a Type pulled out of a dictionary at runtime, complete with camelCase property names and required:

{"type":"object","properties":{"severity":{"type":"string"},...},"required":["severity",...]}

What actually blocked AOT was three narrower things, and the analyzer found one of them that this issue never mentioned:

1. JsonSerializer.Deserialize(string, Type, JsonSerializerOptions) is the annotated overload. The JsonTypeInfo one is not. Resolving options.GetTypeInfo(responseType) first is the whole fix.
2. Type.GetType(string) for the identifier. Replaced by an explicit registration table, ai.RegisterResponseType<T>(), consulted before the message type registry and before the reflective fallback — which is now narrowly suppressed at its own call site rather than by annotating the entire executor.
3. LlmCallout.Ask(prompt, context) serializes an arbitrary object — a site I missed when writing this up, because it is on the authoring path rather than the execution path. A static factory cannot reach the application's JsonSerializerContext, so this one keeps its annotation and gains a trim-clean sibling: .WithContext(context, typeInfo), plus .WithContext(json) for context that is already JSON or was never a CLR object.

What that means for the source generator

The generator is now an ergonomics question, not a correctness one. All it would remove is two lines per response type — the [JsonSerializable] attribute and the RegisterResponseType<T>() call — and applications targeting AOT are already writing JsonSerializerContexts by hand for everything else they serialize. I'd leave it unbuilt unless the ceremony proves annoying in practice, and revisit it alongside #4226, where tool schemas have a genuinely harder version of the same problem.

Two things worth knowing

The failure mode is silent. A JsonSerializerContext that does not cover a response type does not throw. CreateJsonSchema returns an empty schema, the model is handed a constraint that constrains nothing, it usually still answers, and the answer usually still parses. It reads as a quality regression rather than a configuration error. The new Wolverine.AI.AotSmoke project is therefore run in CI as well as built, and asserts on the rendered schema's contents — a build-only gate would sail straight past the exact regression it exists to catch. It exercises the real LlmResponseBinder that LlmCalloutExecutor delegates to, not a copy of it.

A bug fell out of the AOT work. AIJsonUtilities.DefaultOptions sets WriteIndented, so every callout carrying context was pretty-printing that context into its prompt. Indentation in a prompt is billed input tokens buying nothing, and it inflated every character counted against LlmBudget.MaximumPromptCharacters. Context is now serialized compactly, with the naming policy and null handling left identical so what the model is shown does not otherwise change.