Rebuild concurrency cap wiring + per-cell cancellation contract (closes #4710)

[jeremydmiller]

Closes #4710. Marten-side wiring for the per-database rebuild concurrency cap (#420 / #463, epic #486 WS3), consuming JasperFx 2.23.0.

What's here

1. Resolved rebuild cap on the store (IEventStore.MaxConcurrentRebuildsPerDatabase override)

DocumentStore resolves the effective per-database rebuild cap that the projections rebuild CLI path (ProjectionHost.TryRebuildShardsAsync) reads:

• Explicit configuration wins: StoreOptions.Projections.MaxConcurrentRebuildsPerDatabase (the new DaemonSettings knob from Address Dictionary query generation #463, inherited via ProjectionGraph — no new Marten surface needed). Zero/negative opts back into the historical unbounded fan-out.
• Derived default: max(1, MaxPoolSize / 8) from the default database's Npgsql connection string — a 100-connection pool (Npgsql default) allows 12 concurrent rebuild cells, a 20-connection pool allows 2. Conservative by design to leave pool headroom for application traffic during rebuild windows.
• Fallback: null (unbounded, the historical behavior) when no pool signal is reachable.

The --max-concurrent CLI flag still overrides everything per operation (that precedence lives in JasperFx.Events).

2. Descriptor population (#434 companion)

TryCreateUsage now populates EventStoreUsage.MaxConcurrentRebuildsPerDatabase with the resolved cap so monitoring tools (CritterWatch#309's rebuild dispatcher) can size their orchestration off the wire instead of falling back to a conservative 1.

3. Per-cell rebuild cancellation contract (#4710 part 2) — verified + pinned

The contract CritterWatch#309's auto-resume path depends on, now documented in rebuilding.md and pinned by per_tenant_rebuild_cancellation (TenantPartitionedEventsTests):

• Cancelling RebuildProjectionAsync(name, tenantId, ct) mid-flight leaves the cell's mt_event_progression in a consistent state (unchanged or actual partial position — never torn).
• A subsequent rebuild of the same (projection, tenant) cell completes successfully with no manual repair.

The mid-flight test is deterministic: the projection's ApplyAsync is TCS-gated, so cancellation provably fires while the rebuild is parked inside an apply — no sleeps, no drain loops. A pre-cancelled-token variant covers the trivial edge.

4. Docs

New rebuilding.md sections: Capping Rebuild Concurrency (knob, derived default + examples, two-layer concurrency model, rebuild-only scope vs the continuous-catch-up governors, --max-concurrent, descriptor surfacing) and Cancelling a Rebuild (the contract above).

Tests

• rebuild_concurrency_cap_resolution (EventSourcingTests, 5): configured knob wins; non-positive disables; derived default = pool/8 (64 → 8); floors at 1 (pool 5 → 1); usage descriptor carries the effective cap.
• per_tenant_rebuild_cancellation (TenantPartitionedEventsTests, 2): the contract tests above.
• Full EventSourcingTests + TenantPartitionedEventsTests + CoreTests green on net9.0 (results below).

Follow-ups (not here)

• Polecat companion: same override + descriptor population on Polecat's DocumentStore (Patching API should allow adding and removing properties #434 companion list).
• Extending the cap to the intra-projection tenant/shard cross-product fan-out in JasperFxAsyncDaemon (tracked on New mechanism for adding arbitrary database operations to the unit of work batch in DocumentSession #420's follow-up list).

🤖 Generated with Claude Code