GH-4594: document capacity-aware agent assignment

[jeremydmiller]

Closes #4594.

A new Capacity-Aware Agent Assignment section on docs/guide/durability/leadership-and-troubleshooting.md, sitting right after Solo Mode, plus three compiling samples in DocumentationSamples.

The prose is a draft for you to review

The issue said "Text should be in Jeremy's voice -- flagging this as an issue rather than drafting the prose." I took that as the docs-page case rather than the descriptive-text case and drafted it, calibrating against cascading.md, middleware.md and durability/index.md first. The wording is still yours to approve or rewrite -- I would rather you edit a draft than start from a blank page, but I am not assuming the register landed.

Mechanically it follows the house style: second person, opens from the reader's problem, -- rather than em dashes (grepped, zero in the new section), asides in ::: tip / ::: warning callouts rather than parentheticals, plain headings.

Three of the issue's bullets were obsolete

The issue was filed before this week's follow-ups landed, so I wrote the page against what actually shipped rather than the bullet list:

Issue said	Reality now
"PostgreSQL-only today, and silently inert elsewhere (#4593)"	Every store advertises as of #4603. A store that cannot warns at startup
"only affects even distribution -- not group affinity, not blue/green (#4592)"	All three capability-aware paths are capacity-aware as of #4598
"Pending #4589, likely to become required rather than defaulted"	It is required; #4596 made startup refuse without a monitor

The remaining bullets are all covered, and I leaned hardest on the one with the nastiest failure mode. The page does not just say "you must supply an INodeLoadMonitor", it says why that is a startup exception instead of a fallback: a node advertising nothing is read by the leader as having unlimited headroom, so a broken monitor does not make the feature inert on that node, it makes that node the cluster's favourite place to put new work. That is the sentence I would least want a reader to miss.

Also covered, because each is its own way to get burned: the load_factor migration under AutoCreate.None; MemoryPressureLoadMonitor needing a real memory limit to exist; the two thresholds and why one would oscillate; why the overload line is hard in DistributeEvenly but only a preference in the capability-aware paths (an empty candidate set there is a shard database with nothing running against it, not an agent that waits); and that "nobody has headroom" is a quiet symptom worth alerting on.

The issue also asked for the larger framing, so the section closes on where this is heading -- the cluster having an opinion about how much work a node takes being the foundation for having an opinion about how many nodes there should be -- hedged, so it does not read as a promise.

Samples

src/Samples/DocumentationSamples/CapacityAwareAssignment.cs, three snippets, all compiling: turning it on with MemoryPressureLoadMonitor, writing your own INodeLoadMonitor, and wiring a custom one up. The custom-monitor sample carries the two warnings in its comments -- it runs on every heartbeat so it must not block, and null means "no signal", not "lightly loaded".

A note on the diff

mdsnippets rewrites 89 docs files in this repo, not just the one you touched. This commit contains only leadership-and-troubleshooting.md and the new sample file; the other 87 were reverted before committing.

One thing to check

The version badge is a guess: <Badge type="tip" text="6.40" />. Directory.Build.props is on 6.39.1 and the feature merged after that bump, so 6.40 is my assumption rather than something I can verify.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VDUrBeB4tTnKj4AExCS1nj