   // ==== ---------------------------------------------------------------------
   // - MARK: Resolving actors by identity
 
-  /// Resolve a local or remote actor address to a real actor instance, or throw if unable to.
+  /// Resolves a local or remote ``ActorID`` to a reference to given actor, or throws if unable to.
+  ///
   /// The returned value is either a local actor or proxy to a remote actor.
   ///
-  /// Resolving an actor is called when a specific distributed actors `init(from:)`
-  /// decoding initializer is invoked. Once the actor's identity is deserialized
-  /// using the `decodeIdentity(from:)` call, it is fed into this function, which
-  /// is responsible for resolving the identity to a remote or local actor reference.
-  ///
-  /// If the resolve fails, meaning that it cannot locate a local actor managed for
-  /// this identity, managed by this transport, nor can a remote actor reference
-  /// be created for this identity on this transport, then this function must throw.
+  /// This function is not intended to be used directly, but instead is called by the Swift runtime
+  /// whenever ``DistributedActor/resolve(id:using:)` or  a concrete distributed actor's `init(from:)` is invoked.
+  ///
+  /// This function should either return an existing actor reference, or `nil` to signal that a remote distributed actor
+  /// "proxy" should be created for this ``ActorID``. If the resolve fails, meaning that it can neither locate a local
+  /// actor managed by this actor system, nor identify that the identity is located on some remote actor system, then
+  /// this function should throw.
+  ///
+  /// ```swift
+  /// distributed actor Worker { /* ... */ }
+  ///
+  /// // the following internally calls actorSystem.resolve(id: id, as: Worker.self)
+  /// let worker: Worker = try  Worker.resolve(id: id, using: actorSystem)
+  /// ```
   ///
   /// If this function returns correctly, the returned actor reference is immediately
   /// usable. It may not necessarily imply the strict *existence* of a remote actor

//  /// performs the actual distributed (local) instance method invocation.
//  mutating func decodeNextArgument<Argument: SerializationRequirement>() throws -> Argument

  mutating func decodeErrorType() throws -> Any.Type?

  /// Attempt to decode the known return type of the distributed invocation.


/// Decoder that must be provided to `executeDistributedTarget` and is used
/// by the Swift runtime to decode arguments of the invocation.
///
/// ### Protocol requirements
/// Similar to the ``DistributedTargetInvocationEncoder`` and its `recordArgument` and `recordReturnType` protocol requirements,
/// the `DistributedTargetInvocationDecoder` contains a method which is not possible to express in source due to
/// advanced use of generics combined with associated types. Specifically, the `decodeNextArgument`
/// method is not expressed in source as protocol requirement, but will be treated by the compiler as-if it was.
///
/// > Note: Although the `decodeNextArgument` method is not expressed as protocol requirement in source,
/// > the compiler will provide the same errors as-if it was declared explicitly in this protocol.
///
/// In addition to the compiler offering compile errors if this witness is missing in an adopting type,
/// we present its signature here for reference:
///
/// ```swift
/// /// Ad-hoc protocol requirement
/// ///
/// /// Attempt to decode the next argument from the underlying buffers into pre-allocated storage
/// /// pointed at by 'pointer'.
/// ///
/// /// This method should throw if it has no more arguments available, if decoding the argument failed,
/// /// or, optionally, if the argument type we're trying to decode does not match the stored type.
/// ///
/// /// The result of the decoding operation must be stored into the provided 'pointer' rather than
/// /// returning a value. This pattern allows the runtime to use a heavily optimized, pre-allocated
/// /// buffer for all the arguments and their expected types. The 'pointer' passed here is a pointer
/// /// to a "slot" in that pre-allocated buffer. That buffer will then be passed to a thunk that
/// /// performs the actual distributed (local) instance method invocation.
/// mutating func decodeNextArgument<Argument: SerializationRequirement>() throws -> Argument
/// ```
@available(SwiftStdlib 5.7, *)
public protocol DistributedTargetInvocationDecoder {
  /// The serialization requirement that the types passed to `decodeNextArgument` are required to conform to.
  /// The type returned by `decodeReturnType` is also expected to conform to this associated type requirement.
  associatedtype SerializationRequirement

  /// Decode all generic substitutions that were recorded for this invocation.
  ///
  /// The values retrieved from here must be in the same order as they were recorded by
  /// ``DistributedTargetInvocationEncoder/recordGenericSubstitution(_:)``.
  ///
  /// - Returns: array of all generic substitutions necessary to execute this invocation target.
  /// - Throws: if decoding substitutions fails.
  mutating func decodeGenericSubstitutions() throws -> [Any.Type]

//  /// Ad-hoc protocol requirement
