ArC: document InstanceHandle.close() behavior

docs/src/main/asciidoc/cdi-reference.adoc

@@ -1331,6 +1331,28 @@ public void register(RegistrationContext context) {
 
 <1> The argument is the bindings source class.
 
+=== `Instance.Handle.close()` Behavior
+
+Per the CDI specification, the `Instance.Handle.close()` method always delegates to `destroy()`.
+In ArC, this is only true in the <<strict_mode>>.
+
+In the default mode, the `close()` method only delegates to `destroy()` when the bean is `@Dependent` (or when the instance handle does not represent a CDI contextual object).
+When the instance handle represents a bean of any other scope, the `close()` method does nothing; the bean is left as is and will be destroyed whenever its context is destroyed.
+
+This is to make the following code behave as one would naively expect:
+
+[source,java]
+----
+Instance<T> instance = ...;
+try (Instance.Handle<T> handle : instance.getHandle()) {
+   T value = handle.get();
+   ... use value ...
+}
+----
+
+The `@Dependent` beans are destroyed immediately, while other beans are not destroyed at all.
+This is important when multiple beans of different scopes might be returned by the `Instance`.
+
 [[reactive_pitfalls]]
 == Pitfalls with Reactive Programming
 

independent-projects/arc/runtime/src/main/java/io/quarkus/arc/InstanceHandle.java

@@ -61,10 +61,12 @@ default InjectableBean<T> getBean() {
     /**
      * Delegates to {@link #destroy()} if the handle does not represent a CDI contextual instance or if it represents a
      * {@link Dependent} CDI contextual instance.
+     * <p>
+     * Note that in the strict compatibility mode, this method delegates to {@link #destroy()} always,
+     * for compatibility with the CDI specification.
      */
     @Override
     default void close() {
-        // https://github.com/quarkusio/quarkus/issues/33665
         if (Arc.container().strictCompatibility()) {
             destroy();
             return;