Compliance suite: IEventStoreInstrumentation and the append observer

[jeremydmiller]

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

JasperFx.Events.IEventStoreInstrumentation is a shared interface (JasperFx.Events/IEventStoreInstrumentation.cs) that both products implement and register — Marten hangs the append observer off EventGraph (Marten/Events/EventGraph.cs:248), Polecat registers it in DI (PolecatServiceCollectionExtensions.cs:86-94, its #177). It exists specifically so external tooling (CritterWatch) can observe appends without knowing which store it is talking to.

That makes it a contract with an out-of-repo consumer and no cross-store test — the same argument that makes the explorer surface worth pinning.

Seam additions required

1. ComplianceStoreConfig.Instrumentation — an IEventStoreInstrumentation instance the fixture wires in at store-build time. Fixture-owned property (the registration point differs: options object vs DI), same precedent as MaxConcurrentRebuildsPerDatabase.

Everything asserted is on the shared interface.

What each store tests today

Marten	Polecat
CoreTests/Events/EventGraph_IEventStoreInstrumentation.cs	Events/event_store_instrumentation_tests.cs
EventSourcingTests/event_append_observation.cs	Events/event_store_instrumentation_di_tests.cs
EventSourcingTests/get_committed_events_from_listener_Tests.cs	Events/event_append_observer_tests.cs, Events/event_append_counter_tests.cs
	Events/advanced_tracking_propagation_tests.cs

Scope

New EventStoreInstrumentationCompliance suite:

1. The append observer is invoked once per committed append, with the committed events and their assigned sequences/versions
2. It is not invoked when SaveChangesAsync rolls back or when there is no outstanding work
3. Ordering relative to the inline projection write
4. Counts across multiple streams in one unit of work
5. Whatever advanced_tracking_propagation_tests pins on the Polecat side that Marten's advanced_async_tracking.cs also pins — reconcile the pair and take the stronger

Acceptance

• One config property added; suite enrolled in both stores
• Originals retired for the absorbed behavior in both repos
• Any behavioral difference found here is triaged against CritterWatch's expectations before either side is changed

[jeremydmiller]

Attempted, and parked on a design decision — the seam this issue proposes does not exist on Marten

Built the suite (6 tests) and an abstract Instrumentation member on the fixture. It passes nothing on Marten, and the reason is a genuine cross-store divergence rather than anything the suite can absorb.

IEventStoreInstrumentation is implemented in structurally different places

	Where
Polecat	EventStoreOptions : IEventStoreInstrumentation (Polecat/StoreOptions.cs:367) — the store's live options
Marten	Nowhere on the store. Only internal class SetEventStoreInstrumentation : IConfigureMarten, IEventStoreInstrumentation (MartenServiceCollectionExtensions.cs:1112) — a DI-time configuration shim

EventGraph's declaration (Marten/Events/EventGraph.cs:42-44) does not list the interface. Casting to it compiles and throws InvalidCastException at runtime, which is how this surfaced.

Marten's shim is write-only and build-time: its Configure pushes ExtendedProgressionEnabled and AppendObserver onto EventGraph when the store is built, and it is only registered by AddMarten(...). So on Marten there is no object representing "this store's live instrumentation state" to hand a compliance fixture — reading ExtendedProgressionEnabled back off the shim tells you what you asked for, not what the store has.

A second divergence underneath it

Even granting a way to set AppendObserver, the two stores fire it differently:

• Polecat — DocumentSessionBase.SaveChangesAsync calls NotifyAppendObserver() directly (Internal/DocumentSessionBase.cs:618). Setting the delegate is sufficient.
• Marten — the observer is invoked by AppendEventObservationListener, which is only added to Listeners when options.EnableAdvancedTracking is on (StoreOptions.cs:347-358). Setting EventGraph.AppendObserver alone does nothing.

The interface's own doc says "an implementing store stores the delegate and invokes it (best-effort, after commit)" — no mention of a second opt-in.

The doc is wrong

IEventStoreInstrumentation's summary claims it is "Implemented by Marten's EventGraph and Polecat's equivalent options." The Marten half is false. That is the second documented-but-wrong contract this program has caught, after IEventStream<T>.StartingVersion in wave 4.

Why this matters beyond the test

This interface exists so CritterWatch can observe a store without referencing concrete store types. Resolving IEventStoreInstrumentation from DI today yields a configuration object on Marten and the live store options on Polecat. Those are not the same thing, and nothing tests the difference.

Options

A. Marten implements it on EventGraph and keeps the DI shim as a configuration front-end. Makes the doc true, gives the fixture a live surface, and makes the two stores answer the same question the same way. Product change in Marten.

B. Make the observer contract unconditional on Marten — invoke AppendObserver whenever it is set, rather than only under EnableAdvancedTracking. Could ship with or without A; without A there is still no live surface to read state back from.

C. Reshape the seam to build-time only — ComplianceStoreConfig.Instrumentation as this issue originally proposed, with the fixture wiring it in at store construction. Testable on both, but it pins the configuration path and cannot assert what a monitoring consumer actually reads at runtime, which is the whole point.

D. Fix the doc, close this. Accept that the interface is a configuration contract on Marten and a live one on Polecat.

Recommend A + B. They are what would make the interface mean the same thing in both products, which is the only reason it is shared. But both are Marten product changes and this is a call to make, not a defect to fix quietly.

Suite is parked on branch compliance/5152-instrumentation in jasperfx, committed as WIP so it is not lost.

[jeremydmiller]

Decision: not doing this — closing

Jeremy's call. Recording why, and what the attempt turned up, so this is not rediscovered later.

What blocked it

IEventStoreInstrumentation is implemented in structurally different places, and no compliance seam can paper over that:

	Where
Polecat	EventStoreOptions : IEventStoreInstrumentation (Polecat/StoreOptions.cs:367) — the store's live options
Marten	Nowhere on the store. Only internal class SetEventStoreInstrumentation : IConfigureMarten, IEventStoreInstrumentation (MartenServiceCollectionExtensions.cs:1112) — a write-only, build-time DI shim

EventGraph's declaration (Marten/Events/EventGraph.cs:42-44) does not list the interface; casting to it compiles and throws InvalidCastException at runtime.

A second divergence sits underneath: Polecat invokes AppendObserver directly from SaveChangesAsync (Internal/DocumentSessionBase.cs:618), while Marten only wires it through AppendEventObservationListener, added when options.EnableAdvancedTracking is on (StoreOptions.cs:347-358). Setting the delegate is sufficient on one store and a no-op on the other.

Two things that remain true regardless

1. The interface's own doc is wrong. Its summary says it is "Implemented by Marten's EventGraph and Polecat's equivalent options." The Marten half is false. Worth fixing on its own merits whoever gets there — it is the second documented-but-wrong contract this program has caught, after IEventStream<T>.StartingVersion.
2. CritterWatch resolves this interface from DI and gets a different kind of object depending on the store — a configuration object on Marten, live options on Polecat. Not a test problem, and closing this issue does not make it go away. If it ever bites, this comment is the explanation.

The suite is preserved rather than deleted, on branches compliance/5152-instrumentation in jasperfx and marten, both marked WIP/PARKED in their commit messages.

Closing as not planned.