Optimize Cold Start Times

[jeremydmiller]

When we do code generation, also generate a handler/endpoint loader type that can be used to speed up cold starts by eliminating any reflection at bootstrapping. Mostly worried about making Wolverine better for serverless scenarios, but this might get us a bit closer to AOT compliance too

Longer term thing. Might pair this w/ Lamar improvements as well.

This could potentially:

• Turn off assembly scanning to find handlers and/or HTTP endpoints
• Assembly scanning for Fluent Validation validators
• Maybe generates an executor finder that eliminates the usage of Reflection at runtime (just where Wolverine does a GetType(), then looks up in an ImHashMap).
• Eliminates having to scan an assembly to find pre-built types
• Maybe eliminates all assembly scanning for IoC registrations, but only for Lamar most likely

[lukedukeus]

+1 for AOT support & removing reflection

[Afischbacher]

A big +1 from me.

I’m currently integrating Wolverine into an Azure Functions project, and the cold start times for non-generated code (dynamic type loading) are a real performance issue. In some cases, HTTP requests take more than 30 seconds to respond before having it actively cached in the instance, which forces me to rely on static pre-generated types (something I’m actively working to implement).

Reducing this startup time would be a huge win, not only for AWS Lambda and Azure Functions users, but also for those running on Azure Container Apps or other serverless container platforms where cold starts are equally problematic.

[jeremydmiller]

Little more context I guess.

1. We want to optimize code start time enough that Wolverine is a good fit for serverless usages
2. AOT compliance is probably not feasible, but we'll get closer at least

[jeremydmiller]

Cold Start + Reflection Elimination: Analysis & Plan

After a deep audit of Wolverine + JasperFx, here's where we stand and a phased plan to get to a fully reflection-free startup, runtime GetType() elimination, and a v6 AOT story.

TL;DR: The IWolverineTypeLoader scaffolding is already in place but unimplemented. Most of the work is (a) writing a Roslyn source generator that fills it in, (b) wiring the existing fallback paths to actually short-circuit when the loader is present, and (c) replacing the per-message GetType() dispatch in HandlerPipeline with generated code. AOT is a v6 milestone gated on replacing JasperFx.RuntimeCompiler (Roslyn-at-runtime) with build-time codegen.

---

1. Current State: What Already Exists

The skeleton for "no scanning at startup" is already merged but inert:

File	Status
src/Wolverine/Runtime/IWolverineTypeLoader.cs	Interface defined: DiscoveredHandlerTypes, DiscoveredMessageTypes, DiscoveredHttpEndpointTypes, DiscoveredExtensionTypes, PreGeneratedHandlerTypes
src/Wolverine/Attributes/WolverineTypeManifestAttribute.cs	Assembly-level attribute for source generators to mark their loader type
src/Wolverine/ExtensionLoader.cs:74-79, 103-125, 131-146	Phase E: bypass extension scanning when a type loader is registered
src/Wolverine/Runtime/Handlers/HandlerGraph.cs:76, 405-440	compileWithTypeLoader() path that uses pre-discovered handler/message types
src/Wolverine/Runtime/Handlers/HandlerChain.cs:285-307	Phase D: O(1) lookup in PreGeneratedHandlerTypes with O(N) assembly.ExportedTypes fallback

No source generator exists yet to populate any of this. That's the first deliverable.

---

2. Reflection Inventory (Startup)

2a. Assembly scanning hotspots — full Assembly.GetExportedTypes() walks

Site	Trigger	Bypass exists?
HandlerDiscovery.cs:163, 176, 184 — _messageQuery.Find(Assemblies), HandlerQuery.Find(Assemblies)	HandlerGraph.compileWithRuntimeScanning()	✅ Loader path exists at line 405
HandlerDiscovery.cs:208 — type.GetMethods(BindingFlags.Instance | Public | Static) per candidate	Per-handler-type	❌ Source gen could emit (handlerType, methodInfo) pairs directly
HandlerDiscovery.cs:195-202 — AssemblyFinder.FindAssemblies(a => a.HasAttribute<WolverineHandlerModuleAttribute>())	DiscoverHandlerModules()	❌ Disabled by default
ExtensionLoader.cs:51-56 — AssemblyFinder.FindAssemblies() for [WolverineModule]	FindExtensionAssemblies()	✅ Phase E bypass at line 74
ExtensionLoader.cs:93, 107, 140 — Activator.CreateInstance on extension types	Per extension	⚠️ AOT-hazardous; needs [DynamicallyAccessedMembers]
Http/Wolverine.Http/HttpChainSource.cs:23, 29 — assembly.ExportedTypes + GetMethods	HttpChainSource.FindActions()	❌ Loader has DiscoveredHttpEndpointTypes but HttpGraph ignores it
HandlerChain.cs:297 — assembly.ExportedTypes.FirstOrDefault(x => x.Name == TypeName) linear scan in Static mode fallback	Per chain attaching pre-built type	✅ Phase D bypass exists if PreGeneratedHandlerTypes populated
Wolverine.FluentValidation/WolverineFluentValidationExtensions.cs:86, 101 — AssemblyScanner.FindValidatorsInAssemblies and services.Scan(...)	RegistrationBehavior.DiscoverAndRegisterValidators (default)	✅ RegistrationBehavior.ExplicitRegistration exists

2b. Bootstrap-time reflection that runs even with pre-generated code

• Activator.CreateInstance for extensions (ExtensionLoader.cs:93, 107) and handlers (HandlerChain.cs:307 via container.QuickBuild)
• typeof(FanoutMessageHandler<>).MakeGenericType(messageType) — HandlerGraph.cs:326 (and Marten integration at 510). Per discovered message type at startup, not per message.
• typeof(IValidator<>).MakeGenericType(chain.MessageType) + typeof(FluentValidationExecutor).GetMethod().MakeGenericMethod() — Wolverine.FluentValidation/FluentValidationPolicy.cs:20, 25-26. AOT-hazardous; per validated message type at compile.

2c. "Optimized code start mode" today

TypeLoadMode.Static (JasperFx.CodeGeneration.GenerationRules) skips Roslyn compilation but still:

• Scans all assemblies (HandlerDiscovery still runs unless IWolverineTypeLoader is registered — and no generator populates it)
• Loads pre-built types via Assembly.GetExportedTypes() then linear name search (HandlerChain.cs:297)
• Calls Activator.CreateInstance on each handler type

So today's "Static" mode reduces compile cost, not scanning cost.

---

3. Reflection Inventory (Runtime / Per-Message)

These are the per-message GetType() calls — the user's specific concern.

Rank	Site	Pattern	Fix
1	HandlerPipeline.cs:203	_executors[envelope.Message!.GetType()] — every dispatched message	Generate a switch on Envelope.MessageType (string already populated by sender) → IExecutor. Eliminates GetType() and the LightweightCache<Type, IExecutor> lookup.
2	Envelope.cs:50, 228	MessageType = message?.GetType().ToMessageTypeName() — every outgoing envelope	Pre-populate WolverineMessageNaming._typeNames ImHashMap from IWolverineTypeLoader.DiscoveredMessageTypes at startup. First-occurrence cost goes from ~µs (attribute reflection + interface walk) to direct lookup.
3	RateLimiting/RateLimiter.cs:65	_settings.TryFindForMessageType(envelope.Message.GetType(), ...) — per rate-limited message	Switch keyed on envelope.MessageType string; or FrozenDictionary<Type, RateLimitSettings> (.NET 8+) populated at compile.
4	Runtime/MessageContext.cs:613, 662, 669	message.GetType() == Envelope.ResponseType, ResolveTypedAsyncEnumerableCascader(message.GetType()), message.GetType().ToMessageTypeName() — cascading messages	Cache message type once in a local at the top of the cascading helper. Pre-populate _typedEnumerableCascadeMethods ImHashMap at startup using discovered message types.
5	Runtime/Handlers/MessageHandler.cs:78-81	outgoingMessage.GetType() for causation tracking	Fold into the same switch dispatch generated for #1; type info attached at envelope creation.

HandlerPipeline.cs:117 (DetermineSerializer) — string-keyed dictionary lookup; not GetType-driven, but cache the result on the envelope.

---

4. JasperFx Codegen Mechanics (What Wolverine Can Build On)

4a. What's there

• JasperFx.RuntimeCompiler — Roslyn at runtime via AssemblyGenerator. AOT-incompatible. Works for "Auto" and "Dynamic" modes; "Static" mode skips it.
• JasperFx.SourceGeneration — already has incremental Roslyn generators for commands: CommandDiscoveryGenerator emits DiscoveredCommands.g.cs with a Type[] manifest. This is the exact pattern to copy for handlers.
• JasperFx.SourceGenerator — DescriptionGenerator emits partial-class IDescribeMyself.ToDescription() implementations.
• JasperFx.Events.SourceGenerator — AggregateEvolverGenerator discovers aggregate types with Apply() / Create() / Evolve(). Used by Marten today; the discovery pattern is reusable for handler conventions.

4b. What's missing

• No source generator that emits IWolverineTypeLoader implementations. The scaffolding waits for one.
• No source generator that emits per-message strongly-typed dispatch (the switch-on-MessageType replacement for _executors[type]).
• No source-generated JsonSerializerContext for system-text-json (required for AOT).
• No "metadata-only" codegen mode. Today, Static mode means "code is in your assembly already and Wolverine still uses reflection to find it". A "Manifest" mode would be: source generator emits both the code and the lookup table that finds it, eliminating GetExportedTypes() entirely.

4c. Generated code itself

The generated handler chains (MessageHandlerN.cs in Internal/Generated/) are already strongly-typed — no reflection in their bodies. The reflection cost is entirely in finding them, not running them.

---

5. AOT Compliance Audit (v6 Roadmap)

5a. Hard blockers

1. JasperFx.RuntimeCompiler (Roslyn at runtime) — fundamentally incompatible with Native AOT. Pulls in ~100MB of trimming-hostile code.
   • v6 path: source generator becomes mandatory in AOT mode. JasperFx.RuntimeCompiler reference becomes optional/dev-only.
2. Assembly scanning — AssemblyFinder.FindAssemblies(), Assembly.GetExportedTypes() — under trimming, only statically-referenced types survive.
   • v6 path: source-generated IWolverineTypeLoader is the only discovery path under AOT.
3. MakeGenericType / MakeGenericMethod — HandlerGraph.cs:326 (FanoutMessageHandler<>), FluentValidation policy at :20-26, ~46 occurrences across codegen frames.
   • v6 path: source generator emits concrete specializations for every discovered T at compile time. Codegen frames disappear in static mode anyway.
4. System.Text.Json reflection-based serialization — Runtime/Serialization/SystemTextJsonSerializer.cs:29 calls JsonSerializer.Deserialize(Type) with dynamic types.
   • v6 path: require user-supplied JsonSerializerContext, or auto-emit one via source generator. MemoryPack / MessagePack extensions are already AOT-friendly fallbacks.

5b. Soft blockers

5. Activator.CreateInstance(Type) — ~9 sites in ExtensionLoader.cs, HandlerChain.cs. Add [DynamicallyAccessedMembers(PublicConstructors)] annotations on the Type parameters.
6. Type.GetType(string) — emit a static Dictionary<string, Type> from the source generator instead.

5c. Analysis gaps

• Zero uses of [DynamicallyAccessedMembers], [RequiresUnreferencedCode], [UnconditionalSuppressMessage] in the codebase. No AOT analysis has been run.
• No <IsAotCompatible>true</IsAotCompatible> test project. We can't catch regressions until one exists.

5d. DI container note

Wolverine.csproj does not reference Lamar — default integration is Microsoft.Extensions.DependencyInjection, which is AOT-friendly. Lamar appears only in samples. ✅

---

6. Internal Performance Optimizations (Bonus)

Beyond reflection, these are quick wins on the message pipeline:

#	Impact	Site	Fix
1	Med (5–10% latency)	All await in MessageContext, HandlerPipeline, TracingExecutor	Add ConfigureAwait(false) library-wide. Only ~24 instances exist today; should be in the hundreds.
2	Med (GC pressure)	Runtime/Serialization/SystemTextJsonSerializer.cs	Cache JsonSerializerOptions; serialize through pooled IBufferWriter<byte> (Utf8JsonWriter) instead of SerializeToUtf8Bytes.
3	High (if contention)	Runtime/MessageContext.cs:160+ lock (_outstandingLock)	Profile first; if real contention (e.g., GH-2529), switch to lock-free Channel<Envelope> or single-writer pattern.
4	Low–Med	Activity.SetTag(...) calls in MessageContext.cs:276 and elsewhere	Use the existing MaybeSetTag() helper from WolverineTracing.cs:200 consistently — avoids tag-dictionary allocation when tracing disabled.
5	Low	LightweightCache<Type, IExecutor> after #1 in §3 is fixed	Becomes obsolete once dispatch is generated; otherwise consider FrozenDictionary for read-only after compile.
6	Low (death by 1k)	_outstanding.ToArray() in MessageContext.cs:163, LINQ .ToArray() in routing	Snapshot only when needed; prefer List<T> enumeration over array materialization.

Benchmarking gap: src/Testing/ has BenchmarkDotNet scaffolding but no published baseline for per-message overhead. Recommend adding a "1k-message round-trip" benchmark (allocation count, p50/p99 latency, GC stops) as the regression gate before doing any of this.

---

7. Phased Plan

Phase 1 — Source generator MVP (v5.x, non-breaking)

Deliverable: A Wolverine.SourceGeneration project that emits an IWolverineTypeLoader implementation + [assembly: WolverineTypeManifest].

• Discovers handler types (suffix conventions, IWolverineHandler, [WolverineHandler], sagas) at compile time
• Discovers message types ([WolverineMessage], types referenced as handler-method parameters)
• Discovers HTTP endpoint types
• Discovers extension types (assemblies with [WolverineModule] referenced from the consuming project)
• Pattern-matches JasperFx.SourceGeneration.CommandDiscoveryGenerator exactly — that pattern's already proven in-repo

Wiring:

• Already-existing bypass paths in ExtensionLoader.cs:74, HandlerGraph.cs:76, HandlerChain.cs:285 light up automatically
• New wiring needed: HttpGraph.DiscoverEndpoints() (src/Http/Wolverine.Http/HttpGraph.cs:96) is the missing link — needs the same IWolverineTypeLoader short-circuit as HandlerGraph
• Make handler/message scanning short-circuit fully in WolverineRuntime.HostService.cs:74-89 — today the typeLoader check is partial

Phase 2 — Eliminate runtime GetType() in dispatch (v5.x, non-breaking)

• Source-gen a GeneratedExecutorRegistry : IExecutorRegistry that exposes IExecutor Find(string messageType, Type? fallbackType)
• Replace _executors[envelope.Message!.GetType()] at HandlerPipeline.cs:203 with _registry.Find(envelope.MessageType, envelope.Message?.GetType())
• Pre-populate WolverineMessageNaming._typeNames from the type loader at startup
• Same pattern for RateLimiter.cs:65 and the cascading helpers in MessageContext.cs:613, 662, 669

Phase 3 — Validator + auto-discovery extension support (v5.x)

• Source-gen a manifest of IValidator<T> types in the application assembly
• Add RegistrationBehavior.SourceGenerated in Wolverine.FluentValidation that consumes it
• Make this the default when a Wolverine.SourceGeneration reference is detected

Phase 4 — AOT preview (v5.x late)

• Add [DynamicallyAccessedMembers] annotations on Activator.CreateInstance call sites
• Add an IsAotCompatible=true smoke-test project that publishes a minimal Wolverine app with PublishAot=true
• Document known gaps (Roslyn, JsonSerializerContext)

Phase 5 — v6: AOT-ready

• New mode OptimizationMode.AotStatic that forbids runtime Roslyn and any reflective scanning
• Replace MakeGenericType codegen frames with source-generator-emitted concrete specializations
• Require JsonSerializerContext when using STJ under AOT (or auto-emit it)
• JasperFx.RuntimeCompiler becomes an optional dev-time dependency
• <IsAotCompatible>true</IsAotCompatible> on the core Wolverine and Wolverine.Http projects

Phase 6 — Performance pass (any version)

• Library-wide ConfigureAwait(false)
• JsonSerializerOptions caching + pooled buffers
• Profile and address _outstandingLock contention if real
• Consistent MaybeSetTag() for OTel
• BenchmarkDotNet baseline + regression gate in CI

---

8. Effort + Risk

Phase	Effort	Risk	Reverses anything?
1	Medium (1–2 weeks)	Low — opt-in, no API change	No
2	Small (~1 week)	Low — switch is generated, fallback to current path	No
3	Small	Low	No
4	Small (annotations + test project)	Low	No
5	Major (2–3 sprints, ~250 files touch codegen)	Medium — major version, public API surface for codegen frames may change	Possibly removes JasperFx.CodeGeneration runtime API in AOT mode
6	Ongoing	Low–Med (ConfigureAwait change is mechanical but huge diff)	No

Key insight: phases 1–4 are all additive and non-breaking. The bulk of the cold-start win lands in Phase 1 (scanning) and Phase 2 (dispatch) — both shipping under v5.x. AOT (Phase 5) is the v6 milestone.

[jeremydmiller]

Follow-up: Yes, JasperFx.RuntimeCompiler can be a development-time-only dependency

Concrete answer to "can we make JasperFx.RuntimeCompiler dev-only?": yes, and the surface area is surprisingly small. Posting findings here so the work is scoped before anyone starts.

The key fact

IAssemblyGenerator is defined in JasperFx.CodeGeneration — /jasperfx/src/JasperFx/CodeGeneration/IAssemblyGenerator.cs:6. The Roslyn-backed AssemblyGenerator implementation is the only thing in JasperFx.RuntimeCompiler that Wolverine actually binds to.

Translation: the contract Wolverine compiles against is already in the trimming-friendly package. Only the impl needs to move out.

Wolverine's actual JasperFx.RuntimeCompiler references

The whole footprint, post-grep:

File	Line	What it does
src/Wolverine/Wolverine.csproj	24	<PackageReference>
src/Wolverine/HostBuilderExtensions.cs	20, 104	using + services.AddSingleton<IAssemblyGenerator, AssemblyGenerator>()
src/Wolverine/Runtime/Handlers/HandlerGraph.cs	9	using — appears to be a stale import; no AssemblyGenerator/RuntimeCompiler token elsewhere in the file
src/Http/Wolverine.Http/HttpChain.EndpointBuilder.cs	5	using — same: stale import
src/Wolverine.Grpc/WolverineGrpcExtensions.cs	6	using — same: stale import

That's it. One real reference (HostBuilderExtensions.cs:104), three dead imports, and three csproj package references (Wolverine, Wolverine.Http, Wolverine.Grpc).

IAssemblyGenerator itself is only invoked from inside JasperFx.CodeGeneration extension methods (CodeFileExtensions.InitializeSynchronously at jasperfx repo line ~99), and only when TypeLoadMode == Dynamic (or Auto falling through to dynamic). In Static mode, Roslyn is never called.

Marten comparison (cautionary)

Marten has it worse, not better:

• MartenServiceCollectionExtensions.cs:170, 287 — same DI registration
• Internal/ProviderGraph.cs:8, Internal/SecondaryStoreConfig.cs:10, DocumentStore.CompiledQueryCollection.cs:10 — using imports
• Events/CodeGeneration/EventDocumentStorageGenerator.cs:47 — direct new AssemblyGenerator() instantiation

Marten directly news up the Roslyn compiler at runtime. Wolverine doesn't, which is what makes Wolverine's split feasible without coordinating a Marten release first. (We could push a similar split into Marten later as a follow-on.)

Recommended split: Option B (separate assembly), refined

Concrete refactor plan, ranked by effort:

The minimum cut

1. Remove stale using lines in HandlerGraph.cs:9, HttpChain.EndpointBuilder.cs:5, WolverineGrpcExtensions.cs:6. (Mechanical; one PR.)
2. Drop JasperFx.RuntimeCompiler from Wolverine.Http.csproj and Wolverine.Grpc.csproj once the stale usings are gone — they don't need it. (Verify with a clean build.)
3. Create Wolverine.RuntimeCompilation package:
   • References JasperFx.RuntimeCompiler and Wolverine
   • Single API: WolverineOptions.UseRuntimeCompilation() (or services.AddWolverineRuntimeCompilation()) — registers IAssemblyGenerator → AssemblyGenerator
4. Remove services.AddSingleton<IAssemblyGenerator, AssemblyGenerator>() from HostBuilderExtensions.cs:104, drop JasperFx.RuntimeCompiler from Wolverine.csproj, drop the using at line 20.
5. Add a startup guard: if GenerationRules.TypeLoadMode != Static and no IAssemblyGenerator is registered, throw a clear exception:

   Wolverine cannot generate handler code at runtime because no IAssemblyGenerator is registered. Either: (a) install Wolverine.RuntimeCompilation and call opts.UseRuntimeCompilation() for dev-time codegen, or (b) pre-generate code with 'dotnet run -- codegen write' and set GenerationRules.TypeLoadMode = TypeLoadMode.Static.

Where to put UseRuntimeCompilation for ergonomics

The dev-loop story matters. Easiest UX: the Wolverine project templates (and wolverinefx.net docs) reference Wolverine.RuntimeCompilation by default, with a comment explaining "remove this package and call UseRuntimeCompilation() only in Development env to ship a smaller production binary." Production-grade users opt out; serverless/AOT users opt out and use pre-generated code.

Even simpler alternative: keep Wolverine.RuntimeCompilation referenced by default in the template, but have it self-register conditionally:

if (env.IsDevelopment())
    opts.UseRuntimeCompilation();

This matches the existing dev-time-codegen pattern.

Production deployment shape after the split

Scenario	Packages installed	Roslyn loaded?
Dev box / hot-reload	Wolverine + Wolverine.RuntimeCompilation	Yes (intentional)
Pre-generated production (today's "Static" mode)	Wolverine only	No
AOT / serverless	Wolverine only, <PublishAot>true</PublishAot>	No
dotnet run -- codegen write (CI step)	Wolverine + Wolverine.RuntimeCompilation	Yes (in build agent only)

The "pre-generated production" row is what most teams want today and don't realize they could already have if they pre-gen — this split makes it the default deployment shape.

What this doesn't solve

This split removes Roslyn from the production deployment but doesn't itself eliminate the per-message GetType() reflection or the assembly-scanning at startup. Those are Phases 1 and 2 from the prior comment. They're independent: you can do this split without source generators, and source generators without this split. But shipping both is what unlocks AOT.

Updated dependency on Phase 5 of the previous plan

This finding decouples Phase 5 (AOT-ready) from a v6 major version. The Wolverine.RuntimeCompilation split is non-breaking on v5.x as long as the existing default behavior is preserved (template references the new package and auto-registers in dev). AOT compatibility for the core Wolverine.dll becomes feasible inside v5.

Suggested re-shuffle:

• Phase 5a (v5.x, non-breaking): Wolverine.RuntimeCompilation split. Stale-import cleanup. Startup guard.
• Phase 5b (v6): Mandatory source-generated discovery in AOT mode; MakeGenericType/MakeGenericMethod elimination via concrete-specialization codegen; JsonSerializerContext requirement; <IsAotCompatible>true</IsAotCompatible> on Wolverine.dll.

Estimated effort for Phase 5a

• Stale using cleanup + dependency drop in 3 csprojs: trivial (1 hr)
• New Wolverine.RuntimeCompilation package + extension method: small (half-day)
• Startup guard + clear error message: small (1 hr)
• Docs/template updates: small (half-day)
• Test: integration test that builds Wolverine without the RC reference and verifies Static mode works end-to-end: small (half-day)

Total: ~1–2 days of work for a v5.x release that removes Roslyn from production deployments.

[jeremydmiller]

Status update — what's landed, what's pending

This wraps up the open analysis on this issue with a concrete checklist of remaining work, since the picture has shifted as PRs landed.

Landed / in review

• JasperFx #194 (merged → JasperFx 1.28 / JasperFx.RuntimeCompiler 4.5 published) — moves Initialize / InitializeSynchronously / WriteCodeFile extensions from the JasperFx.RuntimeCompiler namespace into JasperFx.CodeGeneration, removes the silent ?? new AssemblyGenerator() fallback, marks the originals [Obsolete].
• Wolverine #2613 — AOT annotations on WolverineTypeManifest/WolverineModule LoaderType properties; pre-populate WolverineMessageNaming cache during startup; pack Wolverine.SourceGeneration analyzer into the WolverineFx NuGet output; ConfigureAwait(false) across 117 awaits in 8 hot-path files.
• Wolverine #2614 — bumps to JasperFx 1.28 / RuntimeCompiler 4.5, drops using JasperFx.RuntimeCompiler; from 3 files (resolves to the new non-deprecated JasperFx.CodeGeneration extensions), introduces the new WolverineFx.RuntimeCompilation opt-in package with UseRuntimeCompilation() / AddWolverineRuntimeCompilation() extensions, adds a v6 migration note above the existing default IAssemblyGenerator registration.

Pending — v5.x (additive, non-breaking)

• Phase 1: Source generator MVP — end-to-end verification. The Wolverine.SourceGeneration project exists in-tree, the analyzer DLL is now packed into the WolverineFx NuGet, but in-repo ProjectReference doesn't transitively flow analyzers — so we haven't actually exercised the generator's output against a downstream consumer. Need either (a) a separate smoke-test project that consumes the packed NuGet locally, or (b) per-test-project ProjectReference to the source generator with OutputItemType="Analyzer". Once verified, the source generator becomes the runtime-scanning bypass for handler / message / extension discovery.
• Phase 2: Eliminate per-message GetType() in dispatch. Generate a GeneratedExecutorRegistry : IExecutorRegistry that exposes IExecutor Find(string messageType, Type? fallbackType), and replace _executors[envelope.Message!.GetType()] at HandlerPipeline.cs:203 with a call through it. Same pattern for RateLimiter.cs:65 and the cascading helpers in MessageContext.cs:613, 662, 669. Depends on Phase 1.
• Phase 3: FluentValidation source-generated registry. Source-gen a manifest of IValidator<T> types in the application assembly. Add RegistrationBehavior.SourceGenerated in Wolverine.FluentValidation that consumes it. Make this the default when a Wolverine.SourceGeneration reference is detected.
• Templates and docs updates pointing users at WolverineFx.RuntimeCompilation + opts.UseRuntimeCompilation(). Recommended pattern: templates reference the new package by default and call if (env.IsDevelopment()) opts.UseRuntimeCompilation();.

Pending — v6 (breaking)

The non-breaking work in #2614 set up the opt-in. v6 is when we actually drop the default registration:

• Drop services.AddSingleton<IAssemblyGenerator, AssemblyGenerator>() from HostBuilderExtensions.cs:104. The line currently carries an explanatory comment marking it for removal.
• Drop the using JasperFx.RuntimeCompiler; at HostBuilderExtensions.cs:20 once the registration is gone.
• Drop <PackageReference Include="JasperFx.RuntimeCompiler" /> from src/Wolverine/Wolverine.csproj. After this, Wolverine.dll no longer depends on Roslyn — production deployments using TypeLoadMode.Static ship without it.
• Add a startup guard: if GenerationRules.TypeLoadMode != Static and no IAssemblyGenerator is registered, throw a clear, actionable exception:

  Wolverine cannot generate handler code at runtime because no IAssemblyGenerator is registered. Either: (a) install the WolverineFx.RuntimeCompilation package and call opts.UseRuntimeCompilation() inside UseWolverine(...) for dev-time codegen, or (b) pre-generate code with 'dotnet run -- codegen write' and set GenerationRules.TypeLoadMode = TypeLoadMode.Static.

• Coordinated Marten migration:
  • 4 using statements (MartenServiceCollectionExtensions.cs:16, Internal/ProviderGraph.cs:8, Internal/SecondaryStoreConfig.cs:10, DocumentStore.CompiledQueryCollection.cs:10) need the same swap to using JasperFx.CodeGeneration; to clear the [Obsolete] warnings.
  • The direct new AssemblyGenerator() instantiation at Events/CodeGeneration/EventDocumentStorageGenerator.cs:47 needs a refactor to resolve IAssemblyGenerator from DI (so Marten can also be Roslyn-free under Static mode). This is a separate Marten-side decision.
• MakeGenericType / MakeGenericMethod elimination for full AOT compatibility. Source generator emits concrete specializations for every discovered T at compile time. Affects ~46 occurrences (mostly codegen frames, which disappear in static mode anyway). Highest-impact site: typeof(FanoutMessageHandler<>).MakeGenericType(messageType) at HandlerGraph.cs:326.
• JsonSerializerContext requirement under AOT. Either require users to provide one for all message types, or auto-emit one via the source generator. MemoryPack / MessagePack extensions remain AOT-friendly fallbacks.
• <IsAotCompatible>true</IsAotCompatible> on the core Wolverine and Wolverine.Http projects, plus an IsAotCompatible=true smoke-test project that publishes a minimal Wolverine app with PublishAot=true to catch regressions in CI.

Production deployment shape after v6

Scenario	Packages installed	Roslyn loaded at runtime?
Dev box / hot-reload	WolverineFx + WolverineFx.RuntimeCompilation	Yes (intentional)
Pre-generated production (Static mode)	WolverineFx only	No
AOT / serverless	WolverineFx only, <PublishAot>true</PublishAot>	No
dotnet run -- codegen write (CI step)	WolverineFx + WolverineFx.RuntimeCompilation	Yes (build agent only)

Won't ship (out of scope of this issue)

• Performance pass items beyond ConfigureAwait(false) (e.g., JsonSerializerOptions pooled buffers, _outstandingLock contention investigation, BenchmarkDotNet baseline) — they're real but tracked separately.
• Wolverine.RuntimeCompilation becoming a hard dependency for any specific feature path — keeping it strictly opt-in is the AOT story.