Cross-stage document visibility docs + TryFindUpstreamCache support (#4329)

[jeremydmiller]

Summary

Two-part response to #4329 — a documentation gap and a missing public API surface.

A composite projection runs all of its stages against a single in-memory IProjectionBatch that flushes to the database once, after every stage completes. Document writes produced by an upstream stage are not yet visible to a SQL query issued from a downstream stage of the same batch — the query goes to PostgreSQL, which has not received them. During RebuildProjectionAsync the trap is even easier to fall into because no documents have been committed yet. The user in #4329 hit this when they wrote querySession.Query<Appointment>().ToList() inside EnrichUsingEntityQuery and got an empty result for documents an upstream stage was producing.

Docs

• New Cross-stage document visibility section in composite.md explaining the rule and pointing at the four supported ways to read upstream stage output.
• :::warning callout on the EnrichUsingEntityQuery section in enrichment.md at the API surface where the trap is easiest to fall into.

New supported pattern

The doc above lists three pre-existing options (Updated<T> events, EnrichWith<T>().AddReferences(), ReferencePeerView<T>()) plus a fourth, new option:

• group.TryFindUpstreamCache<TId, T>(out var cache) — exposed in JasperFx/jasperfx#205, shipped as JasperFx.Events 1.34.0. Lets a custom enrichment callback (notably inside EnrichUsingEntityQuery) reach into the upstream stage's in-memory aggregate cache for arbitrary entity types — not only the TEntity of the enclosing EnrichWith<T>.

Bumps + new integration test

• JasperFx 1.29.0 → 1.29.1, JasperFx.Events 1.33.1 → 1.34.0 in Directory.Packages.props.
• New Bug_4329_try_find_upstream_cache integration test running the exact Composite projections: Query result of documents of upstream projection always empty #4329 shape (one composite batch, stage 1 produces an Order, stage 2 reads it inside EnrichEventsAsync). The test fails the visibility-empty path the user reported and now passes via TryFindUpstreamCache. The doc sample is sourced from this test's #region sample_try_find_upstream_cache block.

Test plan

• Bug_4329_try_find_upstream_cache.downstream_stage_can_read_upstream_in_flight_order_via_upstream_cache passes on net10.0
• All DaemonTests/Composites/* (6 tests) pass on net10.0 with the bumped package versions
• npm run docs renders the new section, anchor link, and sample_try_find_upstream_cache snippet

🤖 Generated with Claude Code