Clarify ambiguity resolution during dynamic lookup

This attempts to clarify the current specification of `Instance.iterator()`,
`Instance.stream()` and `Instance.handles()` in presence of dependency
ambiguity. My understanding is that this modification is what has always
been intended and how current implementations already work.

spec/src/main/asciidoc/core/injectionandresolution.asciidoc

@@ -649,12 +649,18 @@ The `get()` method must:
 The `iterator()` method must:
 
 * Identify the set of beans that have the required type and required qualifiers and are eligible for injection into the class into which the parent `Instance` was injected, according to the rules of typesafe resolution, as defined in <<performing_typesafe_resolution>>, resolving ambiguities according to <<unsatisfied_and_ambig_dependencies>>.
-* Return an `Iterator`, that iterates over the set of contextual references for the resulting beans and required type, as defined in <<contextual_reference>>.
+* If typesafe resolution results in an unsatisfied dependency, the set of resulting beans is empty.
+  If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains at least one alternative, the set of resulting beans contains all beans that were not eliminated during ambiguity resolution.
+  If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains no alternative, the set of resulting beans contains all candidate beans.
+* Return an `Iterator`, that iterates over the set of contextual references for the resulting beans, as defined in <<contextual_reference>>.
 
 The `stream()` method must:
 
 * Identify the set of beans that have the required type and required qualifiers and are eligible for injection into the class into which the parent `Instance` was injected, according to the rules of typesafe resolution, as defined in <<performing_typesafe_resolution>>, resolving ambiguities according to <<unsatisfied_and_ambig_dependencies>>.
-* Return a `Stream`, that can stream over the set of contextual references for the resulting beans and required type, as defined in <<contextual_reference>>.
+* If typesafe resolution results in an unsatisfied dependency, the set of resulting beans is empty.
+  If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains at least one alternative, the set of resulting beans contains all beans that were not eliminated during ambiguity resolution.
+  If typesafe resolution results in an ambiguous dependency and the set of candidate beans contains no alternative, the set of resulting beans contains all candidate beans.
+* Return a `Stream`, that can stream over the set of contextual references for the resulting beans, as defined in <<contextual_reference>>.
 
 The methods `isUnsatisfied()`, `isAmbiguous()` and `isResolvable()` must:
 
@@ -671,12 +677,12 @@ An `UnsupportedOperationException` is thrown if the active context object for th
 The `getHandle()` method must:
 
 * Return an initialized contextual reference `Handle<T>` for a bean that has the required type and qualifiers and is eligible for injection. The contextual reference must be resolved lazily, i.e. when first needed. <<handle_interface>> is described in a separate paragraph.
-* Throw `UnsatisfiedResolutionException` if there is no bean with given type and qualifiers
-* Throw `AmbiguousResolutionException` if there is more than one bean given type and qualifiers
+* Throw `UnsatisfiedResolutionException` if there is no bean with given type and qualifiers.
+* Throw `AmbiguousResolutionException` if there is more than one bean given type and qualifiers.
 
 The `handles()` method must:
 
-* Allow iterating over contextual reference handles for all beans that have the required type and required qualifiers and are eligible for injection.
+* Allow iterating over contextual reference handles for all beans that would be produced by the `iterator()` (or `stream()`) method.
 * Return stateless `Iterable`. Therefore, each `Iterable#iterator()` produces a new set of handles.
 
 The `handlesStream()` is a `Stream` equivalent of the aforementioned `handles()` method.