Compliance suite: strong-typed ids, required members and primary-constructor aggregates

[jeremydmiller]

Part of #5118 (compliance wave growth), epic #5110.

StringIdentitySingleStreamCompliance (wave 3) covers plain string-keyed aggregation. Two adjacent shape families are still tested twice, independently, in both repos:

1. Strong-typed identifiers on aggregates (Guid-backed and string-backed wrappers)
2. Modern C# aggregate shapes — required members and primary constructors — which exercise the source generator's construction path, not the storage layer

Both run through FetchForWriting<T, TId> / FetchLatest<T, TId> on the shared IEventStoreOperations plus ordinary snapshot registration, so this is portable with no seam addition. The strong-typed id types themselves must be declared in the shared source (they compile per consumer anyway, which the package already requires).

What each store tests today

Marten	Polecat
Aggregation/using_guid_based_strong_typed_id_for_aggregate_identity.cs	Projections/using_guid_based_strong_typed_id_for_aggregate_identity.cs
Aggregation/using_string_based_strong_typed_id_for_aggregate_identity.cs	Projections/using_string_based_strong_typed_id_for_aggregate_identity.cs
Aggregation/strong_typed_identifiers_on_aggregates_must_be_nullable.cs	Events/Bug_4214_identity_map_strong_typed_ids.cs
Bug_4542_required_members_primary_ctor.cs	Projections/required_member_primary_ctor_projection_tests.cs
Bug_4543_nullable_read_aggregate_param.cs	Events/aggregate_type_resolution_tests.cs

The Marten↔Polecat file names here are near-identical — this is the most literal duplication left in the two suites.

Scope

New AggregateIdentityShapeCompliance suite:

1. Guid-backed strong-typed id: start stream, FetchForWriting<T, TId>, FetchLatest<T, TId>, inline snapshot persisted under the unwrapped value
2. String-backed strong-typed id: same
3. The nullability rule (strong_typed_identifiers_on_aggregates_must_be_nullable) — settle whether it is a shared rule or Marten-specific before porting; if shared, it belongs here, if not, it stays in Marten
4. required-member aggregate builds and evolves
5. Primary-constructor aggregate builds and evolves
6. Nullable read-aggregate parameter (Bug_4543)

Acceptance

• Suite enrolled in both stores, zero capability gates
• Originals retired in both repos (five files each side)

[jeremydmiller]

Reclassification: the strong-typed id half is NOT portable-today

Probed while picking this up in wave 5. The issue groups this under "portable today — no seam change"; that holds for one half and not the other.

Modern aggregate shapes (required members, primary constructors) — portable, no seam change. These exercise the source generator's construction path, not storage, and both products already have equivalent tests (Marten Bug_4542, Polecat required_member_primary_ctor_projection_tests).

Strong-typed identifiers — needs a seam addition. The two products differ in how a custom value type becomes known to the store:

• Marten requires explicit registration: StoreOptions.RegisterValueType<T>() / RegisterValueType(Type) (src/Marten/StoreOptions.Identity.cs:111,124). Without it the type is not usable in LINQ or as an identity.
• Polecat has no such public API. It resolves value-typed ids automatically at DocumentMapping registration through JasperFx's ValueTypeInfo (src/Polecat/Storage/DocumentMapping.cs:171,499).

So a shared suite needs ComplianceStoreConfig.RegisterValueType<T>() routed through IComplianceStoreRegistrar — implemented on Marten, a no-op on Polecat. That is small and well-precedented: it is exactly the shape of the existing LiveAggregation<T>() member, which Polecat also no-ops because it derives live aggregators automatically (SupportsLiveAggregationRegistration => false).

There is a second, smaller wrinkle: Marten's own strong-typed-id tests lean on the StronglyTypedId source-generator package, which is a test-only PackageReference and is not available to the compliance library. The shared suite has to hand-roll its wrapper types against the documented shape (a single public get-able property wrapping one primitive), which is fine but means the suite is testing the documented contract rather than that package's output.

Suggested split

• Keep the required-member / primary-constructor cases in the portable group — I can land those without touching the seam.
• Move the strong-typed-id cases to the seam-addition group alongside Compliance suite: flat-table event projections — needs a table-inspection capability on the fixture #5147–Compliance suite: IEventStoreInstrumentation and the append observer #5152.

Not acting on the split unilaterally since it changes the epic's grouping; flagging for a call. #5110's checklist is where it would be reflected.

[jeremydmiller]

Built — 11 tests, both stores green. Plus one thing that needs a decision.

StrongTypedIdentityCompliance, Marten 11/11, Polecat 11/11, no capability gates. Deliberately broad per Jeremy's steer that this area has been problematic: {Guid-backed, string-backed} × {live, inline, async} × {AggregateStream, FetchForWriting, FetchForExclusiveWriting, FetchLatest}, plus an unknown-id empty handle and a two-identities-don't-collide check.

Seam addition, as predicted

ComplianceStoreConfig.RegisterValueType<T>() + the registrar member. No-op on Polecat, which derives value types from ValueTypeInfo when it builds the document mapping; Marten needs the type registered before it can use it in LINQ and identity mapping. Same shape as the existing LiveAggregation<T>() precedent, which exists for the mirror-image reason.

The wrappers are hand-rolled, and that turned out to be easy

Both products' own tests declare these with the StronglyTypedIds source generator, which this library cannot require of a consumer. JasperFx.Core.Reflection.ValueTypeInfo.ForType documents what a store actually needs:

exactly one public gettable instance property, plus either a constructor taking that property's type or a public static builder taking it

A readonly record struct CompliancePaymentId(Guid Value) satisfies both clauses and brings equality and ToString along free. No package dependency, and it doubles as a written-down statement of the supported shape.

⚠️ The generic <T, TId> overload throws on a strong-typed id

This is the part that needs a call.

await session.Events.FetchForWriting<CompliancePayment, CompliancePaymentId>(
    new CompliancePaymentId(streamId), ct);

→ System.NullReferenceException inside Marten.Events.Fetching.FetchInlinedPlan<TDoc,TId>.FetchForWriting (and FetchAsyncPlan<,>.FetchForReading for the async lifecycle). Not nullability — reproduced with both PaymentId and PaymentId?.

It is an unexercised path, not a regression. Every strong-typed-id test in both repos passes the raw value:

• Marten Aggregation/using_guid_based_strong_typed_id_for_aggregate_identity.cs:70 — FetchForWriting<Payment>(id)
• Marten's own doc sample explicitly unwraps: FetchForWriting<Payment>(id.Value) (sample_use_fetch_for_writing_with_strong_typed_identifier)
• Polecat Projections/using_guid_based_strong_typed_id_for_aggregate_identity.cs:150 — FetchForWriting<Payment>(streamId)

So nobody has ever called it with the wrapper. But FetchForWriting<T, TId>(TId id) is declared on the shared IEventStoreOperations, it is generic over the identity type, and handing it the aggregate's actual identity type is the obvious thing a user reaches for — arguably the whole point of having a strong-typed id. Failing with a bare NRE is the worst of the available outcomes.

Options

A. Make it work. The overload resolves the identity strategy for TId; teach it to unwrap a registered value type to its simple type. Most useful, most work.

B. Fail helpfully. Throw an explanatory exception naming the value type and pointing at .Value. Cheap, and turns a mystery NRE into an answer.

C. Document raw-only. Say on the overload that a strong-typed id must be unwrapped first, matching what both products already sample.

Recommend A, falling back to B if the identity-strategy plumbing does not make A cheap. Worth checking whether Polecat has the same hole before deciding — I did not test the wrapper overload there once Marten failed.

The suite ships covering the supported form and does not soften around this; when it is settled, the wrapper case is a one-test addition.

Not yet covered

The required-member / primary-constructor half of this issue is still outstanding — that exercises the source generator's construction path rather than the storage layer, and is independent of everything above. Happy to add it as a follow-up.

[jeremydmiller]

"Make it work" — done in both frameworks

Per Jeremy's call. Two PRs, and the root cause turned out to be differently shaped in each product, which is worth recording because a single explanation would have been wrong.

	PR	How it failed	Root cause
Marten	#5193	bare NullReferenceException	determineFetchPlan sends any non-Guid/string TId down the natural-key branch, which passes null! as the identity strategy. The three lifecycle planners match on the projection alone, never look at the identity, and stored the null. LiveFetchPlanner always matches, so nothing ever fell through to the existing "unable to determine a fetch plan" error.
Polecat	polecat#418 (polecat#417)	misleading No natural key definition found for aggregate type…	All three overloads assumed TId meant natural key unconditionally and went straight to FindNaturalKeyDefinition<T>().

Marten's is the broader bug. It was never specific to strong-typed ids — any non-Guid/string TId that was not a natural key produced a plan that could not work.

The distinction both products were missing

A strong-typed id is the stream identity, just wrapped. A natural key is a domain value resolved to a stream through a lookup table. Both arrive as a non-Guid/string TId; neither product distinguished them.

Both fixes make a registered natural key win first, then unwrap a value type over Guid/string and reuse the raw-identity path. Existing natural-key behaviour is untouched by construction.

Marten additionally gets UnwrappedIdentityFetchPlan, a pure forwarder — IAggregateFetchPlan<TDoc, in TId> is contravariant and every member takes the identity as input, so forwarding is sufficient and no parallel plan is needed. Its lifecycle planners now also decline a null identity, so any remaining unsupported TId gets the helpful error instead of a crash.

Verification

• Marten: 6 regression tests, verified failing on master first (5 × NRE). Full EventSourcingTests 1694 / 0 / 7.
• Polecat: 4 regression tests, verified failing on main first (4/4, natural-key error).

Follow-up here

Once both merge, StrongTypedIdentityCompliance switches from raw identities to the wrapper overloads — the shape it should have had from the start, and the shape that now carries forward to Fisher (#5156). That is a small edit to the suite plus a bump.

Still outstanding on this issue: the required-member / primary-constructor half, which exercises the source generator's construction path and is independent of all of the above.