feat(runtime): generalize cluster service views and ownership

Orleans.slnx

@@ -207,6 +207,8 @@
     <Project Path="test/Misc/TestSerializerExternalModels/TestSerializerExternalModels.csproj" />
   </Folder>
   <Folder Name="/test/TestInfrastructure/">
+    <Project Path="test/TestInfrastructure/Orleans.GrainDirectory.Compatibility.CurrentHost/Orleans.GrainDirectory.Compatibility.CurrentHost.csproj" />
+    <Project Path="test/TestInfrastructure/Orleans.GrainDirectory.Compatibility.ReleaseHost/Orleans.GrainDirectory.Compatibility.ReleaseHost.csproj" />
     <Project Path="test/TestInfrastructure/Orleans.TestingHost.Tests/Orleans.TestingHost.Tests.csproj" />
     <Project Path="test/TestInfrastructure/TestExtensions/TestExtensions.csproj" />
   </Folder>

docs/AGENTS.md

@@ -24,6 +24,7 @@ These rules apply recursively to documentation, snippets, and samples under
 ## Links
 
 - Retain useful authoritative references when rewriting or condensing a page.
+- Refer to external papers and articles by their titles or recognizable short names, rather than author names. Link every mention, including repeated references after the first citation.
 - Orleans documentation links should be relative so they work under `https://dotnet.github.io/orleans`.
 - External documentation links must be fully qualified. For example, use the locale-neutral canonical form `https://learn.microsoft.com/azure/...`, not `/azure/...` or a hard-coded locale such as `/en-us/`.
 - Don't carry migrated repository `.md` suffixes into published links.
@@ -99,10 +100,13 @@ tutorial into a reference or burying architecture detail inside a how-to.
 - Rewrite guidance around affirmative runtime behavior and outcomes. Describe relevant triggers, runtime actions, resulting states, and operator responses when those details help readers understand or operate the feature.
 - Assign each responsibility to the mechanism which performs it. For example, an autoscaler changes cluster capacity, placement selects an activation host, and a rebalancer migrates activations.
 - State what a feature is and does. Remove obvious statements and descriptions framed around what the feature isn't, doesn't do, or doesn't replace.
+- Use direct, conversational technical prose and assume an engaged reader. Name models and mechanisms plainly, keep the article's central idea in focus, and give supporting implementation choices proportionate space. Tie qualifications to concrete assumptions or behavior.
+- Prefer good pedagogy over minimum word count. Keep motivation, worked examples, and useful reinforcement when they help readers build the mental model; trim repetition that adds no explanatory value.
 - Prefer correcting or enhancing useful content over deleting it. Preserve
   authoritative references during rewrites, and remove them only when obsolete,
   redundant, or replaced with a clearer current source.
 - Preserve and expand architecture and implementation detail, and keep it distinct from conceptual and task-oriented how-to guidance.
+- Architecture and implementation-detail pages should cite primary papers and other authoritative technical sources for the underlying protocols. Explain which mechanisms Orleans adopts and the assumptions supplied by each runtime layer, and preserve useful research links from source comments.
 - Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.
 - Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.
 

docs/site/src/content/docs/implementation/cluster-management.md

@@ -113,7 +113,7 @@ Official providers adapt transactions, ETags, lightweight transactions, or compa
 Membership is deliberately separate from the services which consume it:
 
 - `LocalGrainDirectory` adjusts consistent-hash ownership after view changes.
-- the experimental distributed directory runs an explicit range-transfer protocol.
+- the experimental distributed directory uses [view-synchronous cluster services](view-synchronous-cluster-services.md) to coordinate range transfer, recovery, and fencing.
 - placement removes unavailable or overloaded candidates.
 - clients refresh the gateway list.
 - persistent-stream queue balancers redistribute queue responsibility.

docs/site/src/content/docs/implementation/grain-directory.md

@@ -55,10 +55,12 @@ Custom directories own their consistency, availability, and cleanup behavior. Th
 
 <xref:Orleans.Hosting.CoreHostingExtensions.AddDistributedGrainDirectory*?displayProperty=nameWithType> opts into a view-synchronous directory marked with compiler warning **`ORLEANSEXP003`**:
 
-It is not the default. The experimental status allows its API and protocol to evolve.
+Its experimental status allows the API and protocol to evolve.
 
 <a name="partitioning-strategy"></a>
-The implementation divides the hash ring into configurable ranges, analogous to the virtual-node partitioning described by [Dynamo](https://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf). <xref:Orleans.Configuration.GrainDirectoryOptions.PartitionsPerSilo?displayProperty=nameWithType> defaults to **1**, not 30. A partition normally serves requests locally. During a membership view change, old and new owners coordinate range locks, snapshots, and ownership transfer. The design applies the [virtually synchronous methodology for dynamic service replication](https://www.microsoft.com/en-us/research/publication/virtually-synchronous-methodology-for-dynamic-service-replication/) and has similarities to [Vertical Paxos and primary-backup replication](https://www.microsoft.com/en-us/research/publication/vertical-paxos-and-primary-backup-replication/).
+The directory uses hash-ring partitioning with a configurable number of virtual nodes per silo, the partitioning scheme described by [Dynamo](https://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf). Each virtual node is a directory partition. <xref:Orleans.Configuration.GrainDirectoryOptions.PartitionsPerSilo?displayProperty=nameWithType> defaults to **1**.
+
+A partition normally serves requests independently. During a membership view change, old and new owners coordinate range gates, snapshots, and ownership transfer using the [Virtual Synchrony approach](https://www.microsoft.com/en-us/research/publication/virtually-synchronous-methodology-for-dynamic-service-replication/). [Vertical Paxos and Primary-Backup Replication](https://www.microsoft.com/en-us/research/publication/vertical-paxos-and-primary-backup-replication/) explains the separation of configuration authority from the work needed to carry state into a new configuration.
 
 <a name="view-change-procedure"></a>
 ```mermaid
@@ -80,6 +82,12 @@ sequenceDiagram
 <a name="recovery-process"></a>
 Requests and responses carry view information. A range cannot serve a request under an incompatible ownership view. If an orderly transfer is impossible, the new owner recovers registrations by querying active silos rather than assuming the failed owner's state.
 
+The runtime's cluster-service topology maps a membership snapshot to partition owners. Membership refreshes complete once the requested version is available in the local projection, propagate underlying refresh failures, and cancel pending waits when the projection stops. Each directory partition installs versioned transition gates synchronously when it observes an ownership change. The partition's scheduler serializes local state access, while the gates keep affected requests waiting across asynchronous transfer and recovery steps. Successive transitions wait for overlapping work from earlier views before reading or installing state.
+
+An inbound transition opens its gate after installing state and establishing the directory's fencing conditions. Recovery after an ungraceful failure can also install a timed safety lease which continues to defer new registrations until expiration. An outbound transition drains earlier work and retains a snapshot for a contiguous handoff. An unexpected transition failure keeps the range blocked and reaches the silo's fatal-error handler, allowing cluster membership and the surviving owners to drive recovery. Shutdown cancels outstanding range waits.
+
+For the internal component contracts, transition state machine, registration/recovery race, fencing assumptions, and annotated research references, see [View-synchronous cluster services](view-synchronous-cluster-services.md).
+
 API: <xref:Orleans.Hosting.CoreHostingExtensions.AddDistributedGrainDirectory*?displayProperty=nameWithType> and <xref:Orleans.Configuration.GrainDirectoryOptions>. Implementation: [hosting registration](https://github.com/dotnet/orleans/blob/main/src/Orleans.Runtime/Hosting/CoreHostingExtensions.cs) and [`DistributedGrainDirectory`](https://github.com/dotnet/orleans/blob/main/src/Orleans.Runtime/GrainDirectory/DistributedGrainDirectory.cs).
 
 ## Tradeoffs

docs/site/src/content/docs/implementation/index.md

@@ -38,6 +38,7 @@ Use this runtime map and the following topic list to choose the required depth.
 - [Runtime architecture](runtime-architecture.md) follows a call through client, messaging, placement, directory, activation, and scheduling components.
 - [Activation lifecycle and migration](activation-lifecycle.md) explains creation, activation, collection, deactivation, and state transfer.
 - [Cluster membership](cluster-management.md) describes the failure detector, membership table, ordered views, and death-vote protocol.
+- [View-synchronous cluster services](view-synchronous-cluster-services.md) connects ownership transitions, state continuity, recovery, and fencing to the underlying research and runtime implementation.
 - [Grain directory](grain-directory.md) distinguishes the default `LocalGrainDirectory` DHT from the experimental distributed directory.
 - [Scheduling and turn execution](scheduler.md) explains `WorkItemGroup`, continuations, interleaving, and single-threaded execution.
 - [Messaging and delivery semantics](messaging-delivery-guarantees.md) traces requests and explains why a timeout has an unknown outcome.