React to read model changes with IReadModelReactor

[woksin]

Summary

An IReadModelReactor reacts to a read model being added, modified or removed using convention-based handler methods — a convenience layer over the Watch APIs so you write a class instead of subscribing to an observable.

One nuance worth knowing: projection-backed read models get a precise, server-provided change type and the causing event's context; reducer-backed and [Materialized] read models infer the change type client-side (first sighting of a key → Added, thereafter Modified) and carry only the model key. Read-model-reactor side effects are best-effort (a read model reactor has no partition to fail), so design handlers to be idempotent.

Scope note: this PR previously sat at the top of a reactor stack. The reactor side-effect-append work (#3381) and reactor handler dependencies (#3358) shipped separately via #3383 and #3401 and are already in main. This PR is now scoped to the read-model reactor only.

Added

• React to read model changes with IReadModelReactor: methods named Added, Modified or Removed are invoked by convention with the changed read model (a single instance or a collection), an optional EventContext, and services, and may return events as side effects. (React to read model changes. #3359)
• [Materialized] opts a read model into materialized change tracking, deducing the change type by comparing successive materialized windows. (React to read model changes. #3359)

Changed

• Read model change notifications now carry the change type and the causing event's sequence number, occurred time and correlation id. (React to read model changes. #3359)

Known issue

• The for_ReadModelReactors integration test fails only on the outofprocess + postgresql matrix cell (passes on mongodb/mssql/sqlite and locally). The read model materializes correctly but the live changeset notification is not delivered to the watcher in that configuration. Under investigation; see the diagnosis notes for details.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Cratis Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: f41bb6e	Previous: 9c41e1c	Ratio
Cratis.Chronicle.Benchmarks.AppendManyBenchmark.AppendManyEvents(EventCount: 100)	225486424.65 ns (± 28388657.350109357)	68128824.7 ns (± 7671149.609764319)	3.31
Cratis.Chronicle.Benchmarks.AppendManyBenchmark.AppendManyEvents(EventCount: 1000)	1152342682.4 ns (± 106158111.52006766)	587439487.4 ns (± 115163188.51672608)	1.96

This comment was automatically generated by workflow using github-action-benchmark.

CC: @einari

[woksin]

Reacting to reducer-backed read models — fidelity concern (cc @einari)

This PR supports read-model reactors over reducer-backed read models as well as projection-backed ones. Flagging a semantic gap in the reducer path before we lean on it.

In ReadModelReactors.Subscribe<TReadModel>, projection-backed models get the precise change type (and the causing event's context) from the server, but reducer-backed models infer Added vs Modified from an in-memory set:

// Projections report the change type from the server; reducers compute changesets locally without one,
// so first-seen keys are tracked client-side to distinguish an addition from a modification.
var seenKeys = eventStore.Reducers.HasFor<TReadModel>()
    ? new HashSet<string>(StringComparer.Ordinal)
    : null;

seenKeys is created fresh on every Start() — including reconnects, which are routine — and Watch is a live stream (no replay on subscribe). So after a reconnect, the first change to a pre-existing instance is reported as Added instead of Modified. Combined with read-model-reactor side effects being best-effort / fire-and-forget (a read model reactor "has no partition to fail"), the canonical "do X once when an instance is created" use case becomes unsafe for reducer-backed models — e.g. a welcome-email reactor would re-fire for existing instances after a reconnect.

Removed is reliable (server flag) and projection-backed read models are unaffected (exact change type from the server).

Options:

1. Make it reliable — have the sink surface insert-vs-update for reducer-materialized writes (it already tracks this via __lastHandledEventSequenceNumber / upsert) so the change type doesn't depend on client memory. Then reducers are as trustworthy as projections.
2. Gate / warn — opt-in or a startup warning for reducer-backed read-model reactors, beyond the doc note in reacting-to-changes.md.
3. Restrict to projections — fail fast at registration for reducer-backed models and point reducer users at event reactors (full context + [OnceOnly] for exactly-once), which is the canonical answer for a reducer's inputs anyway.

@einari — do we want reducer-backed read-model reactors at all, and if so which direction do you prefer? Happy to implement whichever.