Document + test that FindAgentUriAsync resolves registered (not just live) projection shards (#3124)

[jeremydmiller]

Context

#3124 asks that IEventSubscriptionAgentFamily.FindAgentUriAsync(shardIdentity, tenantId, ct) be able to resolve a projection/subscription shard that is registered but not currently running (paused, stopped, crashed, or pre-start), so that admin operations (pause/restart/rebuild) can act on a non-running projection — which is exactly when they're needed.

Finding

On current main, FindAgentUriAsync already does this. It resolves from the registered subscription set:

FindAgentUriAsync → SupportedAgentsAsync() → EventStoreAgents.SupportedAgentsAsync()
                  → usage.Subscriptions.Where(Lifecycle == Async).SelectMany(ShardNames)

That set is the registered projection graph and is independent of run state, so a paused/stopped/not-yet-started shard still resolves. This behavior arrived with the event-subscription agent family in #3108 (after the 6.11.0 the issue was filed against).

The remaining problem was the contract documentation: both the interface and the Marten implementation still described the method as resolving the "live agent" and returning null when "no matching live agent is found" — the precise wording #3124 calls out as wrong/misleading.

Changes

• Correct the XML docs on IEventSubscriptionAgentFamily.FindAgentUriAsync and the Marten EventSubscriptionAgentFamily to state the run-state-independent (registered) behavior.
• Add regression tests (find_agent_uri_for_registered_projection) proving a registered shard resolves to its agent URI without a running agent, and that an unregistered shard returns null. Both pass.

Out of scope (noted for follow-up)

FindAgentUriAsync with a non-null tenantId currently handles only single-database per-tenant partitioning (tenant in the shard RelativeUrl). Database-per-tenant resolution (tenant → separate database, e.g. MultiTenantedWithShardedDatabases) needs a tenant→database mapping and is still deferred — happy to take that on as a separate change if CritterWatch needs per-tenant resolution in the sharded-database model.

🤖 Generated with Claude Code