[Master] JasperFx.Events 2.0

[jeremydmiller]

Status: in-flight (alpha — JasperFx-side foundations shipped; descriptor surface stabilization continues alongside CritterWatch 1.0)
Target version: JasperFx.Events 2.0
Milestone: 2.0
Part of [Master] Critter Stack 2026 (#217).
Sibling: JasperFx 2.0 master plan (#215).
Pillars: cold-start (#212), AOT compliance (#213), dedupe Marten ↔ Polecat (#214).

JasperFx.Events holds the database-agnostic abstractions for event sourcing across the Critter Stack — projections, daemon plumbing, slicing/grouping, event metadata, and the descriptors that CritterWatch consumes. The 2.0 wave promotes it from "shared utility" toward "canonical home" for any event-sourcing concept that isn't database-specific, per the dedupe pillar's Rule 1.

Goals for 2.0

1. Canonical home for non-database event-sourcing logic. Anything currently duplicated between Marten and Polecat that satisfies Rule 1 of pillar [Pillar] Dedupe Marten ↔ Polecat #214 lives here, not in either product repo.
2. Stable public API. Abstractions that Marten 9 and Polecat 4 both consume — IInlineProjection, ProjectionBase, SliceGroup, daemon contracts, descriptors — finalized in shape before either product cuts its release.
3. AOT-clean. IsAotCompatible=true on the csproj; reflective surfaces annotated; no per-call generic instantiation on event-dispatch hot paths that isn't going through GenericFactoryCache or a source generator.
4. CritterWatch-driven descriptor surface stabilized. The descriptor types (EventStoreUsage, DocumentStoreUsage, IHttpGraphUsageSource, DbContextUsage, etc.) that CritterWatch consumes for diagnostics need their public contracts locked for 2.0.

Out of scope for JasperFx.Events 2.0

• Database-specific event-store implementations (those stay in Marten / Polecat).
• Package rename. JasperFx.Events keeps its name; name recognition lives with Marten today and will follow with Polecat (per pillar [Pillar] Dedupe Marten ↔ Polecat #214 Rule 5).

---

✅ Already shipped (2.0 branch)

API shape changes

• Widen IInlineProjection.ApplyAsync — propagates through JasperFxSingleStreamProjectionBase, JasperFxMultiStreamProjectionBase, JasperFxEventProjectionBase, and the ContainerScoped wrappers. Breaking signature change; justifies the major version bump on its own.
• Add GenerationRules.Clone — enables downstream products to fork the generation rules cleanly per projection / handler shard.
• Package version bumped to 2.0.0-alpha.1 alongside JasperFx (lockstep release).

Pre-2.0-cutover landings (shipped on main, now part of the 2.0 foundation)

• Event store explorer + Event Modeling foundations + projection step-through API (commit 4a01de7) — the diagnostic and authoring substrate CritterWatch builds against.
• ForEntityIds + MultiIdentityStep for fan-out enrichment (1-event-to-N-entities). PR Add ForEntityIds for fan-out enrichment (1-event-to-N-entities) #208.
• Defer aggregate cache compaction during composite projection execution. PR Defer aggregate cache compaction during composite projection execution #206.
• Expose SliceGroup.TryFindUpstreamCache for arbitrary upstream entity types. PR Expose SliceGroup.TryFindUpstreamCache for downstream projection enrichment #205.

CritterWatch descriptor surface (recent main commits, carried into 2.0)

• HTTP descriptor types (HttpGraphUsage, HttpChainDescriptor, AspNetEndpointDescriptor, OpenAPI sub-descriptors) + IHttpGraphUsageSource discovery interface — CritterWatch Added Version to EventStoreUsage. JasperFx.Events 1.3 #84.
• DbContextUsage + EntityDescriptor fields for EF Core diagnostics — CritterWatch Generated Files Should be maked with .g.cs extensions instead of .cs #102.
• DbContextUsage descriptor + IDbContextUsageSource discovery interface.
• Event-modeling descriptors + HWM diagnostics wire-format adds — PR Event-modeling descriptors + HWM diagnostics wire-format adds (unblocks CW#144 + CW#150 signals 2/3) #279 (unblocks CritterWatch trying to adjust the JasperFx.RuntimeCompiler Nuget constraints #144 + fix(AssemblyGenerator): refactor Compile method to be thread safe #150 signals 2/3).
• Lift IEventStream, session API + daemon contracts to JasperFx.Events — PR Lift IEventStream, session API + daemon contracts to JasperFx.Events … #268.
• Lift StreamCompactingRequest<T> into JasperFx.Events.Protected — PR Lift StreamCompactingRequest<T> into JasperFx.Events.Protected (#269) #274 (Lift StreamCompactingRequest<T> from Polecat to JasperFx.Events #269).
• Lift FetchForWritingByTags<T> + IEventBoundary<T> to JasperFx.Events — PR Lift FetchForWritingByTags<T> + IEventBoundary<T> to JasperFx.Events (#270) #275 (Lift FetchForWritingByTags<T> tags-aware fetch API to JasperFx.Events #270).
• Populate ShardState.SkippedEventsCount in MarkSkippingAsync + xmldoc fix — PR Populate SkippedEventsCount in tracker + fix MaxEventSequence xmldoc (closes #281) #282 (Populate ShardState.SkippedEventsCount in ShardStateTracker.MarkSkippingAsync + fix EventStoreUsage.MaxEventSequence xmldoc #281).

---

What's left

Dedupe pillar (#214) — JasperFx.Events as canonical home

Per pillar #214's Rule 1, the following abstractions are scoped to land or be confirmed here:

• API surface review — confirm the abstractions Marten + Polecat both consume are stable enough to be the canonical home. Some surfaces are still 1.x-shaped and should be revisited under the major-version window.
• Async daemon abstractions — confirm the JasperFx.Events surface is sufficient for both Marten 9 and Polecat 4 daemons; pull up anything that's still duplicated. (PR Lift IEventStream, session API + daemon contracts to JasperFx.Events … #268 lifted session API + daemon contracts.)
• Projection lifecycle / sharding — finalize ProjectionBase, IInlineProjection, slicers as the shared baseline.
• Event grouping / multi-stream slicing — SliceGroup is partially shared; finish the consolidation.
• Enum sweep — any enum present in both Marten and Polecat moves here (or to Weasel.Core if database-specific).

AOT (#213)

• IsAotCompatible=true on JasperFx.Events.csproj (paired with the JasperFx-side flag).
• Audit reflective call sites — projection discovery, event-type registry, slicer wiring — and either annotate with [RequiresDynamicCode] / [RequiresUnreferencedCode] or migrate to the source generator (JasperFx.Events.SourceGenerator). (PRs Annotate JasperFx.Events Aggregation cluster for AOT (#262, slice 1/4) #264 Aggregation, Annotate JasperFx.Events Projections cluster for AOT (#262, slice 2/4) #265 Projections, Annotate JasperFx.Events event-core cluster for AOT (#262, slice 3/4) #266 event-core, Annotate JasperFx.Events tail surfaces for AOT (#262, slice 4/4) #267 tail.)

Cold-start (#212)

• Audit per-call MakeGenericType / Activator.CreateInstance in event dispatch and projection-application hot paths; migrate to GenericFactoryCache or source-generated equivalents. (Covered by the AOT-slice annotation pass — PRs Annotate JasperFx.Events Aggregation cluster for AOT (#262, slice 1/4) #264–Annotate JasperFx.Events tail surfaces for AOT (#262, slice 4/4) #267.)

CritterWatch descriptor stabilization

• Lock public contracts on the descriptor types CritterWatch consumes (EventStoreUsage, DocumentStoreUsage, HTTP descriptors, DbContextUsage). Any breaking shape changes happen during 2.0 alpha; once 2.0 stabilizes, descriptor additions are additive only.
• Coordinate with the CritterWatch 1.0 master plan to fold in any in-flight descriptor PRs that should land in this wave (per the user's note: "I want to shift several of the ongoing pull requests meant for CritterWatch into this wave as well").

Documentation

• Migration notes for downstream projection / slicer authors covering the IInlineProjection.ApplyAsync widening and any surface that moves under the dedupe rules. (docs/migration-guide.md, "IInlineProjection<TOperations>.ApplyAsync parameter widened" section.)

---

Cross-product dependencies

• Marten 9 and Polecat 4 both consume the abstractions stabilized here. Their AOT audits cannot complete until JasperFx.Events 2.0's annotation pass is done.
• CritterWatch 1.0 consumes the descriptor surface — descriptor stabilization is a shared deliverable between this plan and the CritterWatch master plan.
• JasperFx 2.0 (sibling, [Master] JasperFx 2.0 #215) ships at the same version; both packages release together as the foundation.

Linked implementation work

• JasperFx 2.0 master plan — [Master] JasperFx 2.0 #215
• Cold-start pillar — [Pillar] Cold-start performance #212
• AOT pillar — [Pillar] AOT compliance #213
• Dedupe pillar — [Pillar] Dedupe Marten ↔ Polecat #214
• Marten 9 master plan — [Master] Marten 9.0 marten#4349
• Polecat 4 master plan — [Master] Polecat 4.0 polecat#46
• CritterWatch 1.0 master plan — deferred to a later planning phase

[jeremydmiller]

Status snapshot — 2026-05-13

The "What's left" checklist has been updated. All items in the dedupe / AOT / cold-start sections are now checked:

• Dedupe ([Pillar] Dedupe Marten ↔ Polecat #214): API surface review + async daemon abstractions + projection lifecycle/sharding + event grouping/multi-stream slicing + enum sweep — all landed via PR Lift IEventStream, session API + daemon contracts to JasperFx.Events … #268 (lifted IEventStream<T>, IQueryEventStore, IEventOperations, IEventStoreOperations, IEventFilter, IProjectionCoordinator, IProjectionDistributor, ConcurrencyStyle, SnapshotLifecycle) plus earlier enum relocations (BulkInsertMode, OperationRole, CascadeAction).
• AOT ([Pillar] AOT compliance #213): IsAotCompatible=true flipped (Set IsAotCompatible=true on JasperFx + JasperFx.Events (#213) #247). Full reflective-call-site annotation pass landed in PRs Annotate JasperFx.Events Aggregation cluster for AOT (#262, slice 1/4) #264 → Annotate JasperFx.Events tail surfaces for AOT (#262, slice 4/4) #267 (Aggregation → Projections → event-core → tail). JasperFx.Events.csproj builds clean under WarningsAsErrors=IL*.
• Cold-start ([Pillar] Cold-start performance #212): MakeGenericType / Activator.CreateInstance audit covered by Codegen snapshot invalidation contract (#243 Phase 1) #244 + the AOT slice work above.

Remaining items in this plan:

• CritterWatch descriptor lock — pending the CritterWatch master-plan phase (deferred per the umbrella).
• Downstream migration notes for projection / slicer authors — additive doc work.

Latest published alpha: JasperFx.Events 2.0.0-alpha.5 (#261).

Deferred dedupe lifts from #268 tracked in #269 (StreamCompactingRequest<T>), #270 (FetchForWritingByTags<T>), #271 (ProjectionDistributor concretes — blocked).

#262 closed as complete.