Epic: cross-store event sourcing compliance test library (test harness standardization Phase 3)

[jeremydmiller]

Part of the program master issue #5119. Tracking issue for Phase 3 of the test-harness standardization program. Phases 1–2 (PRs #5098–#5107, all merged 2026-08-01) standardized Marten's own harnesses; Phase 3 lifts shared behavioral event sourcing tests into a compliance library consumed by Marten (PostgreSQL), Polecat (SQL Server), and eventually a planned Sqlite-based minimal store (JasperFx.Events + Weasel.Storage + Weasel.Sqlite). Marten is the tracking repository; cross-repo items are marked in their issues.

Why

Polecat carries ~25–35 hand-mirrored Marten test files, and they have already drifted: Polecat's inline-snapshot tests read back via live re-fold and never assert document persistence; its assign_tag_where_by_stream_id assertion was weakened; Polecat has an OR-across-distinct-tag-types INNER JOIN regression test that Marten lacks entirely. A shared suite makes this class of drift impossible.

Verified ground facts

• Marten's ES-side test projects and Polecat.Tests are on identical xunit.v3 3.2.2, TFMs net9.0;net10.0 in both repos. Runner differs (VSTest vs MTP) — invisible to a library referencing only xunit.v3.extensibility.core.
• Package skew is routine (Marten JasperFx 2.37.0/Weasel 9.23.0 vs Polecat 2.36.3/9.21.0).
• The seam is ~90% shared already: every event-store call in the three seed test pairs resolves to JasperFx.Events.IEventStoreOperations / IEventOperations / IQueryEventStore via session.Events on both sides.
• The stores close IEventStore<,> differently — Marten IEventStore<IDocumentOperations, IQuerySession>, Polecat IEventStore<IDocumentSession, IQuerySession> — and convergence is a non-goal.
• Shared-source distribution is forced (not preferred): the JasperFx.Events source generator emits aggregate dispatchers per consuming assembly and binds each product's session type, so suite/aggregate sources must compile inside each consumer (and aggregates be declared partial for Polecat).

Decisions (settled 2026-08-01)

1. Full generics: EventStoreComplianceFixture<TOperations, TQuerySession> where TOperations : TQuerySession, IStorageOperations, mirroring the JasperFx closure. Marten closes <IDocumentOperations, IQuerySession>; Polecat <IDocumentSession, IQuerySession>.
2. Extraction target: source-only NuGet JasperFx.Events.ComplianceTests in the jasperfx repo (contentFiles C# sources, no compiled lib), after the seam proves out in Marten.Testing.
3. Upstream additives now: generic AddEventType<T>()/EventMappingFor<T>() DIMs on IEventRegistry, and a shared batch-DCB query interface.
4. Marten-side consumption: compliance subclasses run inside EventSourcingTests (linked source, no new project in P3.1).
5. Strongest assertion wins when absorbing drifted pairs — adoption may surface real product gaps; that is the point.
6. P3.1 includes one async-daemon suite to prove the daemon seam members before extraction freezes the API.

Constraints the library must honor

C# 13 ceiling (Marten pins LangVersion 13); explicit usings (Marten has ImplicitUsings off); reference xunit.v3.extensibility.core only (never xunit.v3 — it forces OutputType=Exe); zero InternalsVisibleTo (assert via IEventRegistry.EventMappingFor(Type) → IEventType, never Marten's internal generic); cancellation via an overridable fixture member; capability gates (virtual bool Supports... + xunit v3 dynamic skip) for per-store feature holes (e.g. Polecat native-JSON gate).

Child issues

• Compliance seam: EventStoreComplianceFixture<TOperations, TQuerySession> in Marten.Testing (P3.1a) #5111 — P3.1a: compliance seam EventStoreComplianceFixture<TOperations, TQuerySession> in Marten.Testing
• Seed the compliance suites: self-aggregating evolve, DCB tag query/consistency, AssignTagWhere (P3.1b) #5112 — P3.1b: seed the three suites + strongest-assertion drift fixes
• Async-daemon compliance suite (P3.1c) #5113 — P3.1c: async-daemon compliance suite
• [jasperfx] Additive IEventRegistry generic DIMs: AddEventType<T>() and EventMappingFor<T>() (P3.2a) #5114 (closed, not planned) — P3.2a: [jasperfx] IEventRegistry generic DIMs
• [jasperfx] Shared batch-DCB query interface + Marten/Polecat implementations (P3.2b) #5115 (closed, not planned) — P3.2b: [jasperfx] shared batch-DCB query interface
• Extract the compliance library as source-only NuGet JasperFx.Events.ComplianceTests (P3.3) #5116 — P3.3: extract as source-only NuGet JasperFx.Events.ComplianceTests
• [polecat] Adopt JasperFx.Events.ComplianceTests and retire the mirrored test files (P3.4) #5117 — P3.4: [polecat] adopt + retire mirrored test files
• Compliance wave 2: grow suite coverage from the remaining ported pairs (P3.5) #5118 — P3.5: wave 2 suite growth

Sequencing: #5111 → (#5112, #5113 in either order) → #5116 → #5117 → #5118. #5114/#5115 are parallel upstream tracks; #5114 should land before #5116 so the extracted sources use the generic forms, #5115's shape is finalized against #5112's real usage.

Future (not yet issued): the Sqlite-based minimal document db + event store becomes the third fixture implementation and the first true test that the seam carries no PostgreSQL/SQL Server residue.

🤖 Generated with Claude Code

---

---

Status as of 2026-08-04

The library sits at 14 suites / 105 tests, enrolled in Marten and Polecat with zero capability gates on either store.

Wave	Suites	Shipped in
1 (#5111–#5113, #5116)	seed suites + async daemon	JasperFx 2.37.1
2 (#5118)	AutoDiscoveredAggregate, EventProjectionRegistration, EventProjectionEnrichment, RebuildConcurrencyCap	2.37.2
3	ActivityCorrelation, StringIdentitySingleStream	2.38.0
4	FetchForWriting, StreamRead, EventMetadata, LiveAggregation	2.39.1 (#620)

ProjectionScenario was lifted into JasperFx.Events separately (#5127, #5132, #5133). Consumer adoptions: marten#5122, #5123, #5129, #5135, #5176; polecat#393, #400, #407, #410.

Remaining backlog

Portable today — no seam change:

• Compliance suite: FetchForWriting, WriteToAggregate and stream concurrency #5137 — write handles, WriteToAggregate, stream concurrency (wave 4)
• Compliance suite: stream reads — FetchStreamAsync, time travel, stream state #5139 — stream reads, time travel, stream state (wave 4)
• Compliance suite: live aggregation and AggregateStreamToLastKnownAsync #5141 — live aggregation, AggregateStreamToLastKnownAsync (wave 4)
• Compliance suite: the IEvent metadata contract #5143 — the IEvent metadata contract (wave 4)
• Compliance suite: FetchLatest / ProjectLatest across projection lifecycles #5138 — FetchLatest / ProjectLatest across lifecycles
• Compliance suite: stream archiving and its consequences #5140 — stream archiving and its consequences
• Compliance suite: snapshot lifecycle equivalence (Inline / Async / Live) #5142 — snapshot lifecycle equivalence (Inline / Async / Live)
• Compliance suite: strong-typed ids, required members and primary-constructor aggregates #5144 — strong-typed ids, required members, primary constructors
• Compliance suite: multi-stream projections #5145 — multi-stream projections
• Compliance suite: event store explorer surface (GetRecentStreamsAsync / GetStreamMetadataAsync / TryCreateUsage) #5146 — event store explorer surface

Needs a seam addition:

• Compliance suite: flat-table event projections — needs a table-inspection capability on the fixture #5147 — flat-table event projections (a table-inspection design decision first)
• Compliance suite: conjoined event tenancy — needs a tenant-scoped session seam #5148 — conjoined event tenancy
• Compliance suite: dead letters and the projection error path #5149 — dead letters and the projection error path
• Compliance suite: projection rebuild and catch-up semantics #5150 — projection rebuild and catch-up (sequence after Compliance suite: conjoined event tenancy — needs a tenant-scoped session seam #5148)
• Compliance suite: subscriptions #5151 — subscriptions
• Compliance suite: IEventStoreInstrumentation and the append observer #5152 — IEventStoreInstrumentation and the append observer

Needs an upstream jasperfx lift first:

• Lift CompactStreamAsync<T> onto the shared operations surface, then a stream-compacting compliance suite #5153 — lift CompactStreamAsync<T> onto IEventStoreOperations
• Lift IEventDataMasking into JasperFx.Events.Protected, then an event data masking compliance suite #5154 — lift IEventDataMasking into JasperFx.Events.Protected

Program:

• Adopt distinct ported:/parity: provenance markers in both repos #5155 — marker convention (the README/coverage-boundary half is done, see the issue)
• Sqlite minimal store as the third compliance consumer #5156 — Sqlite minimal store as the third consumer
• Should the high-water progression identity grammar be a compliance suite? Two stores compose it independently and nothing pinned it #5177 — open question, not queued work: does the high-water progression identity grammar belong here?

Exit criterion

Superseded by #5155. "No file carries a ported-from-Marten marker" cannot converge — provenance citations (marten#NNNN) grow with every parity feature, so the count moves away from zero as parity work succeeds. The replacement is the child-suite checklist above.

Dev loop

Both consumers accept -p:ComplianceSourceDir=/path/to/jasperfx/src/JasperFx.Events.ComplianceTests, which swaps the published suites for a working copy. That is what makes a wave verifiable against both stores before the JasperFx release rather than after.

[jeremydmiller]

Phase 3 is delivered. Both consumer PRs merged 2026-08-02:

• marten#5122 → master as 4cfe6c5a2 — closes Compliance seam: EventStoreComplianceFixture<TOperations, TQuerySession> in Marten.Testing (P3.1a) #5111, Seed the compliance suites: self-aggregating evolve, DCB tag query/consistency, AssignTagWhere (P3.1b) #5112, Async-daemon compliance suite (P3.1c) #5113, Extract the compliance library as source-only NuGet JasperFx.Events.ComplianceTests (P3.3) #5116
• polecat#393 → main as a05338e2b — closes [polecat] Adopt JasperFx.Events.ComplianceTests and retire the mirrored test files (P3.4) #5117, fixes polecat#392
• jasperfx#607 merged and published — JasperFx.Events.ComplianceTests ships in the 2.37.1 line

Marten and Polecat now run the same 42 compliance tests. Post-merge suites: Marten ES 1613/0/7, Polecat 1629/0/3, both verified against the published packages rather than a local feed. No capability gates were needed — neither store skips a single compliance test, which is a better outcome than the design anticipated.

Epic status

Leaving this open for #5118 (wave 2), now unblocked with both stores on the library.

#5114 and #5115 should be closed without implementing — full reasoning is on each issue. #5114's DIMs collide with existing EventGraph members and cannot land without a source-breaking change to AddEventType<T>(). #5115 would not retire IComplianceBatch, because Execute(ct) belongs to the batch rather than the queries — the exact question this epic asked P3.1b to settle, now settled by real usage. Neither is a prerequisite for anything; the seam needs zero InternalsVisibleTo as designed and the batch adapter is ~10 lines per store.

What the epic's premise bought

Every prediction in the "Why" section was confirmed by adoption, in both directions:

• Marten gained two tests it never had (can_query_events_across_distinct_tag_types_with_or, fetch_for_writing_appends_to_existing_tag_derived_stream_without_collision), both green day one.
• Polecat failed 5/42 on first contact. Two were the real bug the weakened assign_tag_where_by_stream_id mirror had been hiding. The other three were exception shape, absorbed by the seam and now tracked as polecat#394.
• A ninth drift item the design's list of eight missed, plus two Polecat API-parity gaps (polecat#394, polecat#395).

Carry-forward for the Sqlite consumer

• Each consumer supplies global using ComplianceQuerySession = <Store>.IQuerySession; — the source generator resolves the EvolveAsync session parameter by type name, so an alias is enough.
• Assert.Skip needs xunit.v3.assert; it is not in xunit.v3.extensibility.core. The declarative [Fact(SkipUnless=...)] cannot be used for capability gates — xunit v3 requires a static property, which cannot consult a per-store fixture instance.
• Doc snippets stay repo-owned permanently. Both products keep a dcb_documentation_samples.cs for the sample_*_dcb_* blocks, because after extraction mdsnippets cannot reach the suite sources.