preventing unwanted eager instantiation and ensuring correct bean selection by exact definition

Author: Jarvx

inject/src/main/java/io/micronaut/context/DefaultBeanContext.java

@@ -2032,6 +2032,20 @@ protected void initializeContext(
                     throw new BeanInstantiationException(MSG_BEAN_DEFINITION + (ref == null ? "<ref discarded>" : ref.getName()) + MSG_COULD_NOT_BE_LOADED + e.getMessage(), e);
                 }
             }
+            // Prune eager beans that are replaced by any replacement bean in the application,
+            // regardless of the replacement scope.
+            List<BeanDefinition<Object>> replacementTypes = new ArrayList<>(4);
+            for (BeanDefinitionProducer producer : beanDefinitionsClasses) {
+                BeanDefinition<Object> def = producer.getDefinitionIfEnabled(this);
+                if (def != null && def.getAnnotationMetadata().hasStereotype(REPLACES_ANN)) {
+                    replacementTypes.add(def);
+                }
+            }
+            if (!replacementTypes.isEmpty()) {
+                //noinspection unchecked,rawtypes
+                eagerInit.removeIf(def -> checkIfReplacementExists(null, (List) replacementTypes, def));
+            }
+            // Also apply local replacement filtering amongst eager beans themselves.
             filterReplacedBeans(null, eagerInit);
             OrderUtil.sortOrdered(eagerInit);
             for (BeanDefinition eagerInitDefinition : eagerInit) {

inject/src/main/java/io/micronaut/context/SingletonScope.java

@@ -248,7 +248,8 @@ <T> BeanRegistration<T> findBeanRegistration(@NonNull BeanDefinition<T> beanDefi
                                                  @Nullable Qualifier<T> qualifier) {
         BeanRegistration<T> beanRegistration = singletonByBeanDefinition.get(BeanDefinitionIdentity.of(beanDefinition));
         if (beanRegistration == null) {
-            return findCachedSingletonBeanRegistration(beanType, qualifier);
+            // Do not fall back to cached registration by type/qualifier; we must respect the exact definition.
+            return null;
         }
         return beanRegistration;
     }

test-suite-kotlin-ksp/src/test/kotlin/io/micronaut/context/replacement/ContextBeanReplacementScopeTest.kt

@@ -0,0 +1,61 @@
+package io.micronaut.context.replacement
+
+import io.micronaut.context.ApplicationContext
+import io.micronaut.context.annotation.Context
+import io.micronaut.context.annotation.Replaces
+import io.micronaut.context.annotation.Requires
+import jakarta.inject.Singleton
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.Test
+import java.util.concurrent.atomic.AtomicInteger
+
+interface ReplacedApi
+
+@Context
+@Requires(property = "spec.name", value = "ContextBeanReplacementScopeTest")
+open class OriginalContextApi : ReplacedApi {
+    companion object {
+        @JvmField
+        val created = AtomicInteger(0)
+    }
+    init {
+        created.incrementAndGet()
+    }
+}
+
+@Singleton
+@Replaces(OriginalContextApi::class)
+@Requires(property = "spec.name", value = "ContextBeanReplacementScopeTest")
+open class ReplacementSingletonApi : ReplacedApi {
+    companion object {
+        @JvmField
+        val created = AtomicInteger(0)
+    }
+    init {
+        created.incrementAndGet()
+    }
+}
+
+class ContextBeanReplacementScopeTest {
+
+    @Test
+    fun replacingContextBeanWithSingletonShouldPreventOriginalInstantiation() {
+        // Reset counters for isolation
+        OriginalContextApi.created.set(0)
+        ReplacementSingletonApi.created.set(0)
+
+        val ctx = ApplicationContext.run(mapOf("spec.name" to "ContextBeanReplacementScopeTest"))
+        try {
+            // Expected: Replacing a @Context bean with a non-@Context bean should prevent eager instantiation
+            // Actual (bug): OriginalContextApi is still eagerly created at startup
+            assertEquals(0, OriginalContextApi.created.get(), "Original @Context bean should not be instantiated when replaced by a non-context bean")
+
+            val api = ctx.getBean(ReplacedApi::class.java)
+            assertTrue(api is ReplacementSingletonApi, "Injected bean should be the replacement")
+            assertEquals(1, ReplacementSingletonApi.created.get(), "Replacement bean should be constructed once on demand")
+            assertEquals(0, OriginalContextApi.created.get(), "Original bean must not be constructed at all")
+        } finally {
+            ctx.close()
+        }
+    }
+}