#4667 Phase 3 — ProjectionDocumentSession routes user-code LoadAsync through projection-safe path

[jeremydmiller]

Phase 3 of #4667 — closes
the user-code escape hatch. Builds on #4669
(write path) and #4670
(read path on ProjectionStorage).

Background

When a user-supplied aggregation projection's Apply (or DetermineAction /
EvolveAsync) calls operations.LoadAsync<X>(...) from inside the daemon,
that call routed through IDocumentStorage<,>.LoadAsync(id, this, ct) →
BuildSelector(session) → per-row writes into _session.Versions /
_session.ItemMap / _session.ChangeTrackers. The async daemon shares one
IMartenSession across the 10-wide Block<EventSliceExecution> parallel
workers per (range, tenant); each row was a race on those shared dicts.

What changes

QuerySession (the load API base): introduces two protected internal virtual
chokepoints:

ExecuteLoadOneAsync<T, TId>(storage, id, token)
ExecuteLoadManyAsync<T, TId>(storage, ids, token)

All public LoadAsync<T> / LoadManyAsync<T> overloads (string / object /
int / long / Guid × single / params / IEnumerable × with / without
CancellationToken) now call through the chokepoints instead of
storage.LoadAsync(id, this, token) directly. Default impl preserves the
existing session-aware route — zero behavior change for non-projection
sessions.

ProjectionDocumentSession overrides both chokepoints with
UseIdentityMapForAggregates gating that mirrors Phase 1 + Phase 2:

UseIdentityMapForAggregates	Route
false (default in daemon)	LoadProjectedAsync / LoadManyProjectedAsync (fresh connection, no session-shared dict writes)
true (opt-in)	base session-aware route — preserves GH-3850 inline-projection-immutable-aggregate semantics; documented as not safe for parallel projection workers

Implementation note — the [return: MaybeNull] + bare Task<T> chokepoint
return shape: the override on ProjectionDocumentSession (a partial-class
chain not uniformly in #nullable enable context) loses the
reference-type-vs-Nullable<T> disambiguation of T? at the override site
(CS0508 + CS0453). The attribute form is unambiguous in either context and
produces the same call-site annotation. All public LoadAsync<T>
return-type Task<T?> is unchanged.

Regression test

Bug_4667_projection_load_async_parallel_no_race.cs runs 250 streams × 4
events through the async daemon's parallel Block<EventSliceExecution>
fanout against a SingleStreamProjection whose Apply does
session.LoadAsync<Bug4667Customer> per event. Pre-Phase 3 this path
per-row-wrote into the shared session's tracker dicts; post-Phase 3 it goes
through LoadProjectedAsync (fresh connection, no session state).

Acceptance criteria

• A regression test: a custom projection whose Apply calls operations.LoadAsync<X>(...)
  runs through a parallel Block fan-out with UseIdentityMapForAggregates = false — must
  not throw and must produce correct aggregates. ✅
• The same test with UseIdentityMapForAggregates = true still runs (the
  FetchLatest doesnt return the latest version of the aggregate after appending an event when working with record-types #3850 inline-projection path still uses the identity-map-aware route).
  ✅ (covered by the existing fetch_latest_async_aggregate,
  fetching_inline_aggregates_for_writing tests which all pass.)

Verification

Local on net9.0:

Suite	Result
DaemonTests	188 / 188 ✅ (+1 new regression test)
EventSourcingTests	1361 passed / 7 pre-existing skips ✅
CoreTests	421 passed / 1 pre-existing skip ✅

Out of scope (Phase 4 / follow-up)

• Query<T>() / LINQ — the issue lists Query<T> as a Phase 3 target, but
  the LINQ selector swap is more invasive than the LoadAsync chokepoint
  and the typical user-code escape hatch hits LoadAsync, not Query<T>.
  Defer to a focused follow-up once the load-harness in
  #4666 exposes a
  surviving Query<T> race.
• Phase 4 (per-slice scoped session) — only needed if a race survives
  Phases 1–3 per the issue's "Skip until Phases 1–3 ship" guidance.

🤖 Generated with Claude Code