Consume the lifted JasperFx.Events ProjectionScenario

[jeremydmiller]

Note

Reframed 2026-08-03. The original plan — hand-write the 15 missing overloads — is obsolete. ProjectionScenario has been lifted into JasperFx.Events so both stores share one implementation, which closes this gap without porting anything. The original gap analysis is preserved at the bottom; it is still the best record of what diverged.

What to do now

Consume JasperFx.Events.TestSupport.ProjectionScenario<TOperations, TQuerySession> (JasperFx/jasperfx#616, shipping in JasperFx.Events 2.38.0) instead of maintaining Polecat's own port.

Delete Polecat's seven Events/TestSupport/ files and replace them with one subclass closing the generic pair over Polecat's session types. Marten's equivalent adoption is JasperFx/marten#5133 — a ~70-line class, −692/+51 lines — and is the reference to copy.

The subclass implements seven abstract seam members, all one-liners:

Member	What it does
DeleteExistingDataAsync(ct)	Wipe event + projection storage
HasAnyAsyncProjections	Whether to stand up a daemon
BuildDaemonAsync(tenantId)	Build the projection daemon
OpenSession(tenantId)	Open a writable session
SaveChangesAsync(session, ct)	Commit (no shared interface declares it)
EventsFor(session)	Session's IEventOperations
LoadDocumentAsync<T>(session, object id, ct)	Load by id, dispatching on the id's runtime type

This should be nearly free for Polecat, because PolecatComplianceFixture already implements every one of these — the seam was deliberately shaped to match EventStoreComplianceFixture, including the object-id load dispatch. Lift the bodies straight across.

What the lift changes about the API

Worth knowing before adopting, since Polecat's port matches the old Marten shape:

• The 15 missing overloads simply exist now, inherited. Nothing to write.
• Append / StartStream return void, not StreamAction — the old return value was a throwaway disconnected from the queued operation. The StartStream overloads that generate their own id return that Guid.
• DocumentShouldExist<T> / DocumentShouldNotExist<T> take object ids — one overload each, not four per identity type. Typed call sites still compile.
• DoNotDeleteExistingData → DeleteExistingData (default true); no more double negative.
• Assertion failures throw ProjectionScenarioAssertionException; a failed action now stops the scenario instead of letting later steps run against unintended state; a scenario can only execute once; Timeout is configurable and the CancellationToken is honored.
• Execute → ExecuteAsync.

Background on why the shape changed first: JasperFx/marten#5127 and JasperFx/marten#5132.

Blocked on

JasperFx/jasperfx#616 merging and JasperFx.Events 2.38.0 publishing.

---

Original issue (2026-08-02): the 15-overload gap analysis

Polecat/Events/TestSupport/ProjectionScenario mirrors Marten's design file-for-file (same seven files, same type names, same entry point store.Advanced.EventProjectionScenario(...)), but the event-operations half is implemented much more shallowly. A test written against Marten's scenario API frequently will not compile against Polecat's.

Measured against Marten/Events/TestSupport/ at marten master and Polecat/Events/TestSupport/ at polecat main.

Assertions: already at parity

Nine members each, identical signatures — AssertAgainstProjectedData, DocumentShouldExist<T> and DocumentShouldNotExist<T> over Guid/int/long/string. The only difference is the generic constraint (where T : notnull in Marten, where T : class in Polecat), which is a deliberate divergence, not a gap.

Event operations: 11 members vs Marten's 28

Present in Marten, missing in Polecat:

Every IEnumerable<object> overload — Polecat is params object[] only:

StreamAction Append(Guid stream, IEnumerable<object> events);
StreamAction Append(string stream, IEnumerable<object> events);
StreamAction Append(string stream, long expectedVersion, IEnumerable<object> events);
StreamAction StartStream(IEnumerable<object> events);
StreamAction StartStream(Guid id, IEnumerable<object> events);
StreamAction StartStream(string streamKey, IEnumerable<object> events);
StreamAction StartStream<TAggregate>(IEnumerable<object> events);
StreamAction StartStream<TAggregate>(string streamKey, IEnumerable<object> events);

This is the one that bites in practice: a caller with a List<object> of events has to spread it at every call site.

The Type-argument aggregate overloads — for code that has a Type rather than a generic parameter:

StreamAction StartStream(Type aggregateType, IEnumerable<object> events);
StreamAction StartStream(Type aggregateType, params object[] events);
StreamAction StartStream(Type aggregateType, Guid id, IEnumerable<object> events);
StreamAction StartStream(Type aggregateType, Guid id, params object[] events);
StreamAction StartStream(Type aggregateType, string streamKey, IEnumerable<object> events);
StreamAction StartStream(Type aggregateType, string streamKey, params object[] events);

The no-identity generic overload:

StreamAction StartStream<TAggregate>(params object[] events);   // server-assigned id

Stream compacting — struck after reading Marten's implementation. Marten's two CompactStreamAsync<T> overloads exist only to satisfy IEventOperations and both bodies are:

throw new NotSupportedException();

So this is not a capability Polecat is missing; Polecat simply does not declare the stubs. Nothing to do here, and arguably Marten's shape is the worse of the two. Excluded from the count below.

Suggested scope

1. Add the IEnumerable<object> overloads — mechanical, and the highest value per line.
2. Add the Type-argument and no-identity StartStream overloads.

That is the whole gap: 15 overloads, all of them shape rather than capability.

Related

There is a standing question of whether ProjectionScenario should be lifted into JasperFx.Events generic on <TOperations, TQuerySession> instead of maintained twice — see the companion Marten issue. Closing this gap first is not wasted work either way: it establishes what the shared surface would have to cover, and it is useful immediately regardless of whether the lift happens.

Found by

Compliance wave 2 (marten#5118), while checking whether the two Events/TestSupport/ trees are duplicates. They are not — same design, different depth.

🤖 Generated with Claude Code

[jeremydmiller]

Recommend holding this rather than porting the missing overloads. The Marten surface these would mirror just changed shape in JasperFx/marten#5132 (the marten#5127 quality pass): the Append/StartStream methods no longer return a throwaway StreamAction (void, or the generated stream id Guid), the eight copy-pasted assertion bodies collapsed into two helpers, DoNotDeleteExistingData became DeleteExistingData, and assertion failures are now typed. The next step is lifting the whole scenario surface into JasperFx.Events for cross-store reuse — at which point Polecat consumes the shared implementation instead of maintaining a port, and this issue closes without any of the 15 overloads being written by hand.

🤖 Generated with Claude Code

[jeremydmiller]

Retitled and reframed above: the lift landed as JasperFx/jasperfx#616, so this becomes "subclass the shared type" rather than "write 15 overloads." The original gap analysis is preserved in the collapsed section at the bottom of the issue body.

Marten's adoption is JasperFx/marten#5133 (draft until JasperFx.Events 2.38.0 publishes) and is the reference implementation to copy — ~70 lines, all one-liners. Polecat's should be smaller still, since PolecatComplianceFixture already implements every seam member the scenario needs.

🤖 Generated with Claude Code

[jeremydmiller]

Unblocked — JasperFx.Events 2.38.0 is published, so the shared ProjectionScenario is available now.

Marten's adoption merged as JasperFx/marten#5133: seven files and ~690 lines of duplicated harness deleted, replaced by a ~70-line subclass. That's the reference to copy.

Two things Polecat should pick up in the same pass, since they came in the same release:

1. The scenario lift (this issue). Subclass JasperFx.Events.TestSupport.ProjectionScenario<TOperations, TQuerySession> and implement the seven seam members — PolecatComplianceFixture already has bodies for every one of them, including the object-id LoadDocumentAsync dispatch.
2. jasperfx#617 (Service-injected scoped/transient projections are not validated or usable by live aggregation / single stream rebuilds marten#5095): container-scoped single stream projections are only reachable from AggregatorFor if the store builds its wrapper through the new ScopedAggregationWrapper.Build(...) selector. Closing the wrapper type directly still gets the validation fix (it lives in the shared base constructor) but not the live-aggregation fix.

Also worth knowing if Polecat tracks the compliance suites: 2.38.0 carries compliance wave 3 (jasperfx#613), which does not compile without consumer adoption — new fixture members CorrelationIdFor/CausationIdFor/SetCorrelationId, a ComplianceStringPartyProjectionBase alias, and two new suites to enrol. Marten's adoption is in JasperFx/marten#5135; note that compiling is not sufficient, the fixture must also honour the new StreamIdentity and EnableCorrelationTracking config knobs or 7 of the 10 new tests fail.

🤖 Generated with Claude Code