[Master] JasperFx 2.0

[jeremydmiller]

Status: in-flight (alpha — JasperFx-side foundations largely shipped; [Obsolete] sweep continues per #273)
Target version: JasperFx 2.0
Milestone: 2.0
Part of [Master] Critter Stack 2026 (#217).
Pillars: cold-start (#212), AOT compliance (#213), dedupe Marten ↔ Polecat (#214).

JasperFx is the foundational layer of the Critter Stack — CLI framework, runtime/source-generator code generation, multi-tenancy primitives, descriptors, IoC conventions, and shared utilities. JasperFx 2.0 is the substrate that the rest of the 2026 wave (Marten 9, Wolverine 6, Polecat 4, CritterWatch 1.0, JasperFx.Events 2.0) builds against.

Goals for 2.0

1. AOT-clean foundation. All JasperFx + JasperFx.Events public APIs either compile AOT-clean or carry precise [RequiresDynamicCode] / [RequiresUnreferencedCode] annotations so downstream apps can publish with PublishAot=true.
2. Roslyn becomes opt-in. Apps in Static TypeLoadMode do not transitively reference Microsoft.CodeAnalysis.* in their production deployment. The JasperFx.RuntimeCompiler package is the explicit opt-in.
3. Deterministic, byte-stable codegen. dotnet run -- codegen write produces source files that are byte-identical to the in-memory output of Dynamic mode, so pre-generated code is a reliable build artifact.
4. Breaking-change cleanup. Accumulated obsoletes and shape mismatches that have been waiting for a major version are removed in this wave.

Out of scope for JasperFx 2.0

• New unrelated features. 2.0 is a foundation release; greenfield features wait for 2.x.
• Native-AOT-publishing the Roslyn pipeline itself (the AssemblyGenerator is dev-time only by design).

---

✅ Already shipped (2.0 branch)

Foundation cutover

• 1.0 maintenance branch frozen at the last 1.x main commit
• 2.0 becomes the new main; all packages versioned 2.0.0-alpha.1
  • JasperFx, JasperFx.Events, JasperFx.Events.SourceGenerator, JasperFx.SourceGeneration, JasperFx.SourceGenerator
  • JasperFx.RuntimeCompiler intentionally left at 4.5.0 until its own next version
• Drop .NET 8 support. Target frameworks are now net9.0;net10.0. net11.0 will be added when the runtime ships.
• CI workflows + Nuke build script updated; dead ActivityExtensions.AddException polyfill removed; obsolete NET8_0_OR_GREATER #if blocks inlined.

Pillar work (see pillar issues for full detail)

• PR AOT prep: introduce ITypeLoader abstraction so the Roslyn pipeline is excludable under PublishAot #190 — ITypeLoader abstraction (Static / Dynamic / Auto loaders), JasperFx.RuntimeCompiler package split, services.AddRuntimeCompilation() is the single opt-in seam. Cold-start ([Pillar] Cold-start performance #212) + AOT ([Pillar] AOT compliance #213).
• PR AOT prep: annotate CloseAndBuildAs<T> + add a delegate-factory escape hatch for hot-path callers #191 — CloseAndBuildAs<T> carries [RequiresDynamicCode] / [RequiresUnreferencedCode]. New GenericFactoryCache provides delegate-cached, AOT-friendly hot-path generic instantiation. AOT ([Pillar] AOT compliance #213) + cold-start ([Pillar] Cold-start performance #212).
• PR Stabilize codegen ordering for byte-identical output across runs #196 — deterministic codegen ordering (sort AllInjectedFields / Setters by stable, process-independent keys). Prerequisite for byte-stable pre-generated source. Cold-start ([Pillar] Cold-start performance #212).

---

What's left

Cold-start (#212)

• Audit remaining JasperFx + JasperFx.Events hot paths for per-call MakeGenericType / Activator.CreateInstance and migrate to GenericFactoryCache or source-generator equivalents.
• CLI: confirm dotnet run -- codegen write produces byte-identical output to Static mode reads — investigate residual asymmetry around namespace ordering and TFM-conditional emit.

AOT (#213)

• Set IsAotCompatible=true on JasperFx.csproj and JasperFx.Events.csproj so the AOT analyzer runs in our own CI.
• Audit every remaining MakeGenericType / Activator.CreateInstance / Type.GetMethod(...).Invoke in JasperFx + JasperFx.Events; annotate or migrate.
• Audit reflective discovery in JasperFx.CommandLine (assembly scanning for IJasperFxCommand) — annotate or replace with the existing source generator.
• Add an AOT-clean smoke-test consumer project in CI: tiny app referencing JasperFx + JasperFx.Events in Static mode with IsAotCompatible=true. Build fails on any IL2026/IL3050 warning.

Dedupe (#214) — JasperFx-side foundations

• JasperFx.Events API surface review: confirm the abstractions Marten + Polecat both consume are stable enough to be the canonical home. (Detailed in the JasperFx.Events 2.0 master plan.)
• Promote any JasperFx-side helpers showing up in both Marten and Polecat (multi-tenancy, descriptors, codegen primitives) into clearly-named modules so the boundary is obvious to consumers.

Breaking-change cleanup

Pre-existing 2.0 milestone issues — folded in here for tracking:

• Code Gen attemps to load assemblies that don't exist (Oracle EF Core) #188 — Codegen attempts to load assemblies that don't exist (Oracle EF Core scenario).
• IAggregateGrouper.Group: change IEnumerable<IEvent> to IReadOnlyList<IEvent> #201 — IAggregateGrouper.Group: change IEnumerable<IEvent> → IReadOnlyList<IEvent>. Breaking signature.
• OptionsDescription.Children + Sets aren't being serialized — public fields, not properties #203 — OptionsDescription.Children + Sets aren't being serialized — public fields, not properties.
• Sweep for accumulated [Obsolete] APIs and remove the ones that have been deprecated since the previous major. (Tracked in [Obsolete] sweep — coordinated removals across the Critter Stack 2026 wave #273 — safe removals shipped via PRs 2.0 cleanup sweep — [Obsolete] removals + TPL Dataflow removal from JasperFx #272, Reclassify perf-nag [Obsolete] + remove dead ShardStateTracker.Publish (#273) #277, Remove no-consumer OaktonAsyncCommand / OaktonCommand shims (#273) #278; remaining steps need coordinated Marten / Polecat / Wolverine sample updates.)

Documentation

• End-to-end "publish AOT with JasperFx" guide (Static mode, no AddRuntimeCompilation, code pre-generated via codegen write).
• Migration guide from JasperFx 1.x → 2.0 (TFM bump, RuntimeCompiler package split, API removals). (PR Add JasperFx 1.x → 2.0 migration guide #242, docs/migration-guide.md.)

---

Cross-product dependencies

• Marten 9 / Wolverine 6 / Polecat 4 / CritterWatch 1.0 all build against this. The shape of JasperFx 2.0's public API and AOT annotations needs to stabilize before downstream products can finalize their own AOT audits.
• JasperFx.Events 2.0 (separate master plan) ships in lockstep with JasperFx 2.0 — same package version line.

Linked implementation work

• JasperFx.Events 2.0 master plan — [Master] JasperFx.Events 2.0 #216
• Cold-start pillar — [Pillar] Cold-start performance #212
• AOT pillar — [Pillar] AOT compliance #213
• Dedupe pillar — [Pillar] Dedupe Marten ↔ Polecat #214
• Pre-existing 2.0 milestone items — Code Gen attemps to load assemblies that don't exist (Oracle EF Core) #188, IAggregateGrouper.Group: change IEnumerable<IEvent> to IReadOnlyList<IEvent> #201, OptionsDescription.Children + Sets aren't being serialized — public fields, not properties #203

[jeremydmiller]

Status update — 2026-05-12

JasperFx 2.0.0-alpha.6 is now live on NuGet (and the rest of the package family at matching versions).

Package	Version
JasperFx	2.0.0-alpha.6
JasperFx.Events	2.0.0-alpha.3
JasperFx.RuntimeCompiler	2.0.0-alpha.2
JasperFx.SourceGeneration	2.0.0-alpha.2
JasperFx.SourceGenerator	2.0.0-alpha.2
JasperFx.Events.SourceGenerator	2.0.0-alpha.2

What's in alpha.6 since alpha.5 / alpha.2 / alpha.1

• RecentlyUsedCache: deterministic LRU via Interlocked counter (#231) #234 (closes Flaky: RecentlyUsedCache tests depend on DateTimeOffset.UtcNow resolution #231) — RecentlyUsedCache deterministic LRU via Interlocked counter
• OptionsDescription: Children + Sets as properties so JSON serializes them (#203) #236 (closes OptionsDescription.Children + Sets aren't being serialized — public fields, not properties #203) — OptionsDescription Children + Sets as properties so JSON serializes them
• ScopedContainerCreation: gate await-using on AsyncMode.AsyncTask (#228) #238 (closes GetServiceFromScopedContainerFrame emits 'await using' without promoting the host method to async #228) — ScopedContainerCreation: gate await using on AsyncMode.AsyncTask
• Codegen CLI: enforce ServiceLocationPolicy per file (#227) #239 (closes Codegen CLI commands (preview / write / test) bypass ServiceLocationPolicy enforcement #227) — Codegen CLI enforces ServiceLocationPolicy per file
• AssemblyGenerator: tolerate missing referenced assemblies (#188) #235 (closes Code Gen attemps to load assemblies that don't exist (Oracle EF Core) #188) — AssemblyGenerator tolerates missing referenced assemblies (Oracle EF Core satellites)
• Use IReadOnlyList for aggregate grouper events #202 (closes IAggregateGrouper.Group: change IEnumerable<IEvent> to IReadOnlyList<IEvent> #201) — IJasperFxAggregateGrouper.Group takes IReadOnlyList<IEvent> (breaking — downstream-only)
• Package metadata hygiene: PackageIcon + PackageReadmeFile (closes #221, #222) #233 (closes Replace deprecated <PackageIconUrl> with <PackageIcon> across all packaged projects #221, Add PackageReadmeFile to all published packages #222) — Package metadata refresh: PackageIcon + PackageReadmeFile + per-project README

Downstream propagation

• Marten — PR #4369 (open, CI green) bumps the JasperFx pins to alpha.6 / alpha.3 / alpha.2, absorbs the IAggregateGrouper.Group: change IEnumerable<IEvent> to IReadOnlyList<IEvent> #201 breaking change across 8 grouper implementations, and closes marten#4368 (migration-guide bullet + 8 doc samples in multi-stream-projections.md).
• Polecat — PR #60 (open, CI green) bumps the JasperFx pins to alpha.6 / alpha.3 / alpha.2. Zero source impact from IAggregateGrouper.Group: change IEnumerable<IEvent> to IReadOnlyList<IEvent> #201 (grep-verified no grouper implementations).
• Wolverine — still on the 1.x line (5.39 just shipped). 6.0 cutover + JasperFx 2.x adoption is its own piece of work tracked under wolverine#2715.