rubydex 0.2.6 → 0.2.8

data/rust/rubydex/src/resolution.rs

@@ -19,26 +19,37 @@ use crate::model::{
 };
 
 enum Outcome {
-    /// The constant was successfully resolved to the given declaration ID. The second optional tuple element is a
-    /// declaration that still needs to have its ancestors linearized
-    Resolved(DeclarationId, Option<DeclarationId>),
-    /// We had everything we needed to resolved this constant, but we couldn't find it. This means it's not defined (or
-    /// defined in a way that static analysis won't discover it). Failing to resolve a constant may also uncovered
-    /// ancestors that require linearization, which is the second element
-    Unresolved(Option<DeclarationId>),
-    /// We couldn't resolve this constant right now because certain dependencies were missing. For example, a constant
-    /// reference involved in computing ancestors (like an include) was found, but wasn't resolved yet. We need to place
-    /// this back in the queue to retry once we have progressed further. The optional declaration ID is an ancestor that
-    /// needs to be linearized before we can retry.
-    Retry(Option<DeclarationId>),
+    /// The constant was successfully resolved to the given declaration ID.
+    Resolved(DeclarationId),
+    /// We had everything we needed to resolve this constant (all relevant ancestor chains are complete), but the member
+    /// isn't there. This is definitive: the unit can be dropped and a diagnostic emitted.
+    Unresolved,
+    /// We couldn't resolve this constant right now because a dependency was missing, so it may succeed later. The unit
+    /// must be placed back in the queue and retried once we have progressed further. `partial` is `true` when the
+    /// blocker was a still-partial ancestor chain (the member may appear once the chain completes); `false` when it was
+    /// a plain missing dependency (an unresolved parent scope, alias, or lexical nesting).
+    Retry { partial_ancestors: bool },
 }
 
 impl Outcome {
     fn is_resolved_or_retry(&self) -> bool {
-        matches!(self, Outcome::Resolved(_, _) | Outcome::Retry(_))
+        matches!(self, Outcome::Resolved(_) | Outcome::Retry { .. })
     }
 }
 
+/// Controls how `get_or_create_singleton_class` schedules linearization of the singleton it touches.
+#[derive(Clone, Copy)]
+enum SingletonAncestors {
+    /// Linearize the ancestors inline, immediately. Should only be used after the convergence loop, when every
+    /// namespace is already resolved.
+    Eager,
+    /// Enqueue a `Unit::Ancestors` so the convergence loop linearizes it on a later pass.
+    Enqueue,
+    /// Do nothing: the caller is already mid-linearization and will linearize this singleton inline
+    /// within the current `LinearizationContext`, so a separate unit would be pure duplicate work.
+    Deferred,
+}
+
 struct LinearizationContext {
     descendants: IdentityHashSet<DeclarationId>,
     seen_ids: IdentityHashSet<DeclarationId>,
@@ -140,8 +151,8 @@ impl<'a> Resolver<'a> {
     /// the Ruby API
     pub fn resolve_constant(&mut self, name_id: NameId) -> Option<DeclarationId> {
         match self.resolve_constant_internal(name_id) {
-            Outcome::Resolved(id, _) => Some(id),
-            Outcome::Unresolved(_) | Outcome::Retry(_) => None,
+            Outcome::Resolved(id) => Some(id),
+            Outcome::Unresolved | Outcome::Retry { .. } => None,
         }
     }
 
@@ -186,45 +197,40 @@ impl<'a> Resolver<'a> {
                 };
                 let str_id = *method.str_id();
                 match self.graph.definition_id_to_declaration_id(*def_id) {
-                    Some(&owner_decl_id) => match self.get_or_create_singleton_class(owner_decl_id, false) {
-                        Some(singleton_id) => {
-                            self.create_declaration(str_id, id, singleton_id, |name| {
-                                Declaration::Method(Box::new(MethodDeclaration::new(name, singleton_id)))
-                            });
-                            Outcome::Resolved(singleton_id, None)
+                    Some(&owner_decl_id) => {
+                        match self.get_or_create_singleton_class(owner_decl_id, SingletonAncestors::Enqueue) {
+                            Some(singleton_id) => {
+                                self.create_declaration(str_id, id, singleton_id, |name| {
+                                    Declaration::Method(Box::new(MethodDeclaration::new(name, singleton_id)))
+                                });
+                                Outcome::Resolved(singleton_id)
+                            }
+                            // Owner is a non-promotable constant — method is orphaned
+                            None => Outcome::Unresolved,
                         }
-                        // Owner is a non-promotable constant — method is orphaned
-                        None => Outcome::Unresolved(None),
-                    },
+                    }
                     // Owning class not resolved yet — retry next pass
-                    None => Outcome::Retry(None),
+                    None => Outcome::Retry {
+                        partial_ancestors: false,
+                    },
                 }
             }
             _ => panic!("Expected constant or singleton method definitions"),
         };
 
         match outcome {
-            Outcome::Retry(None) => {
-                // There might be dependencies we haven't figured out yet, so we need to retry
+            Outcome::Retry { .. } => {
                 self.unit_queue.push_back(unit_id);
             }
-            Outcome::Unresolved(None) => {
+            Outcome::Unresolved => {
                 // We couldn't resolve this name. Emit a diagnostic
             }
-            Outcome::Retry(Some(id_needing_linearization)) | Outcome::Unresolved(Some(id_needing_linearization)) => {
-                self.unit_queue.push_back(unit_id);
-                self.unit_queue.push_back(Unit::Ancestors(id_needing_linearization));
-            }
-            Outcome::Resolved(id, None) => {
+            Outcome::Resolved(id) => {
                 if needs_linearization {
                     self.unit_queue.push_back(Unit::Ancestors(id));
                 }
                 self.made_progress = true;
             }
-            Outcome::Resolved(_, Some(id_needing_linearization)) => {
-                self.unit_queue.push_back(Unit::Ancestors(id_needing_linearization));
-                self.made_progress = true;
-            }
         }
     }
 
@@ -233,24 +239,17 @@ impl<'a> Resolver<'a> {
         let constant_ref = self.graph.constant_references().get(&id).unwrap();
 
         match self.resolve_constant_internal(*constant_ref.name_id()) {
-            Outcome::Retry(None) | Outcome::Unresolved(None) => {
-                // Retry: dependencies not resolved yet, or name genuinely unknown
-                // (which can be temporary during incremental invalidation when the
-                // parent namespace was deleted but will be re-added).
-                self.unit_queue.push_back(unit_id);
-            }
-            Outcome::Retry(Some(id_needing_linearization)) | Outcome::Unresolved(Some(id_needing_linearization)) => {
-                self.unit_queue.push_back(unit_id);
-                self.unit_queue.push_back(Unit::Ancestors(id_needing_linearization));
-            }
-            Outcome::Resolved(declaration_id, None) => {
+            Outcome::Resolved(declaration_id) => {
                 self.graph.record_resolved_reference(id, declaration_id);
                 self.made_progress = true;
             }
-            Outcome::Resolved(resolved_id, Some(id_needing_linearization)) => {
-                self.graph.record_resolved_reference(id, resolved_id);
-                self.made_progress = true;
-                self.unit_queue.push_back(Unit::Ancestors(id_needing_linearization));
+            Outcome::Retry { .. } => {
+                self.unit_queue.push_back(unit_id);
+            }
+            Outcome::Unresolved => {
+                // If we had everything we needed to resolve this constant and still failed, then remember it as work
+                // for the next incremental resolution pass, but avoid trying again in this cycle
+                self.graph.push_work(unit_id);
             }
         }
     }
@@ -291,7 +290,9 @@ impl<'a> Resolver<'a> {
                                 continue;
                             };
 
-                            let Some(singleton_id) = self.get_or_create_singleton_class(receiver_decl_id, true) else {
+                            let Some(singleton_id) =
+                                self.get_or_create_singleton_class(receiver_decl_id, SingletonAncestors::Eager)
+                            else {
                                 continue;
                             };
 
@@ -395,7 +396,9 @@ impl<'a> Resolver<'a> {
                                 };
 
                                 // Instance variable in singleton method - owned by the receiver's singleton class
-                                let Some(owner_id) = self.get_or_create_singleton_class(receiver_decl_id, true) else {
+                                let Some(owner_id) =
+                                    self.get_or_create_singleton_class(receiver_decl_id, SingletonAncestors::Eager)
+                                else {
                                     continue;
                                 };
                                 {
@@ -453,7 +456,9 @@ impl<'a> Resolver<'a> {
                                 .copied()
                                 .unwrap_or(*OBJECT_ID);
 
-                            let Some(owner_id) = self.get_or_create_singleton_class(nesting_decl_id, true) else {
+                            let Some(owner_id) =
+                                self.get_or_create_singleton_class(nesting_decl_id, SingletonAncestors::Eager)
+                            else {
                                 continue;
                             };
                             {
@@ -483,7 +488,7 @@ impl<'a> Resolver<'a> {
                                 continue;
                             };
                             let owner_id = self
-                                .get_or_create_singleton_class(singleton_class_decl_id, true)
+                                .get_or_create_singleton_class(singleton_class_decl_id, SingletonAncestors::Eager)
                                 .expect("singleton class nesting should always be a namespace");
                             {
                                 debug_assert!(
@@ -524,7 +529,8 @@ impl<'a> Resolver<'a> {
                                 continue;
                             };
 
-                            let Some(owner_id) = self.get_or_create_singleton_class(decl_id, true) else {
+                            let Some(owner_id) = self.get_or_create_singleton_class(decl_id, SingletonAncestors::Eager)
+                            else {
                                 continue;
                             };
 
@@ -652,7 +658,9 @@ impl<'a> Resolver<'a> {
             };
 
             let owner_id = if is_singleton {
-                let Some(singleton_id) = self.get_or_create_singleton_class(lexical_owner_id, true) else {
+                let Some(singleton_id) =
+                    self.get_or_create_singleton_class(lexical_owner_id, SingletonAncestors::Eager)
+                else {
                     continue;
                 };
                 singleton_id
@@ -710,18 +718,8 @@ impl<'a> Resolver<'a> {
                     offset,
                     format!("undefined method `{owner_name}#{method_name}` for visibility change"),
                 );
-                if is_singleton {
-                    // Document-scoped: the singleton class may be synthetic (created by this
-                    // visibility resolution) and won't be cleaned up on file delete, so attaching
-                    // the diagnostic to the declaration would leave it orphaned.
-                    self.graph.add_document_diagnostic(uri_id, diagnostic);
-                } else {
-                    self.graph
-                        .declarations_mut()
-                        .get_mut(&owner_id)
-                        .unwrap()
-                        .add_diagnostic(diagnostic);
-                }
+
+                self.graph.add_document_diagnostic(uri_id, diagnostic);
             }
         }
 
@@ -855,19 +853,20 @@ impl<'a> Resolver<'a> {
     /// If the declaration is a `Constant` with all-promotable definitions, it is automatically promoted to a `Class`
     /// namespace before creating the singleton. Returns `None` if the declaration is not a namespace and cannot be
     /// promoted (e.g., `FOO = 42`).
-    /// When `eager_ancestors` is `true`, ancestor chains are linearized inline (used after the convergence loop when all
-    /// namespaces are resolved). When `false`, a `Unit::Ancestors` item is enqueued for the convergence loop to process.
+    /// `ancestors` controls how the singleton's ancestor chain is scheduled for linearization —
+    /// inline now (`Eager`), enqueued for the convergence loop (`Enqueue`), or left to the caller
+    /// that is already linearizing it inline (`Deferred`). See [`SingletonAncestors`].
     fn get_or_create_singleton_class(
         &mut self,
         attached_id: DeclarationId,
-        eager_ancestors: bool,
+        mode: SingletonAncestors,
     ) -> Option<DeclarationId> {
         let attached_decl = self.graph.declarations().get(&attached_id).unwrap();
 
         // If the attached object is a constant alias, follow the alias chain to find the actual namespace
         if matches!(attached_decl, Declaration::ConstantAlias(_)) {
             return match self.resolve_to_namespace(attached_id) {
-                Some(id) => self.get_or_create_singleton_class(id, eager_ancestors),
+                Some(id) => self.get_or_create_singleton_class(id, mode),
                 None => None,
             };
         }
@@ -878,11 +877,7 @@ impl<'a> Resolver<'a> {
                     Declaration::Namespace(Namespace::Module(Box::new(ModuleDeclaration::new(name, owner_id))))
                 });
 
-                if eager_ancestors {
-                    let _ = self.ancestors_of(attached_id);
-                } else {
-                    self.unit_queue.push_back(Unit::Ancestors(attached_id));
-                }
+                self.schedule_singleton_ancestors(attached_id, mode);
             } else {
                 return None;
             }
@@ -910,15 +905,26 @@ impl<'a> Resolver<'a> {
             )))),
         );
 
-        if eager_ancestors {
-            let _ = self.ancestors_of(decl_id);
-        } else {
-            self.unit_queue.push_back(Unit::Ancestors(decl_id));
-        }
+        self.schedule_singleton_ancestors(decl_id, mode);
 
         Some(decl_id)
     }
 
+    /// Schedules linearization of a singleton's ancestor chain according to the requested policy.
+    fn schedule_singleton_ancestors(&mut self, id: DeclarationId, mode: SingletonAncestors) {
+        match mode {
+            SingletonAncestors::Eager => {
+                let _ = self.ancestors_of(id);
+            }
+            SingletonAncestors::Enqueue => {
+                self.unit_queue.push_back(Unit::Ancestors(id));
+            }
+            // The caller is already linearizing this singleton inline within the current
+            // `LinearizationContext`, so a separate unit would be redundant work.
+            SingletonAncestors::Deferred => {}
+        }
+    }
+
     /// Linearizes the ancestors of a declaration, returning the list of ancestor declaration IDs
     ///
     /// # Panics
@@ -1021,7 +1027,7 @@ impl<'a> Resolver<'a> {
 
         // Ensure that we create the singleton and enqueue it for linearization if we see an extend
         if has_extends && !is_singleton_class {
-            self.get_or_create_singleton_class(declaration_id, false);
+            self.get_or_create_singleton_class(declaration_id, SingletonAncestors::Enqueue);
         }
 
         let (linearized_prepends, linearized_includes) =
@@ -1261,15 +1267,17 @@ impl<'a> Resolver<'a> {
             // `set_singleton_class_id`, not `add_member`, so a TODO receiver would never gain a
             // member. Emit Retry so the unit is preserved for a later resolve where the receiver
             // may exist.
-            Outcome::Unresolved(None) if singleton => Outcome::Retry(None),
-            Outcome::Unresolved(None) => Outcome::Resolved(self.create_todo_for_parent(name_id), None),
+            Outcome::Unresolved if singleton => Outcome::Retry {
+                partial_ancestors: false,
+            },
+            Outcome::Unresolved => Outcome::Resolved(self.create_todo_for_parent(name_id)),
             other => other,
         };
 
         // The name of the declaration is determined by the name of its owner, which may or may not require resolution
         // depending on whether the name has a parent scope
         match outcome {
-            Outcome::Resolved(owner_id, id_needing_linearization) => {
+            Outcome::Resolved(owner_id) => {
                 let mut fully_qualified_name = self.graph.strings().get(&str_id).unwrap().to_string();
 
                 // If the owner is a promotable constant and something is being defined inside it, promote it to a
@@ -1294,7 +1302,7 @@ impl<'a> Resolver<'a> {
                 // Foo = 1
                 // class << Foo; end
                 if singleton && !owner_is_namespace {
-                    return Outcome::Unresolved(None);
+                    return Outcome::Unresolved;
                 }
 
                 // We don't prefix declarations with `Object::`
@@ -1324,7 +1332,7 @@ impl<'a> Resolver<'a> {
                 }
 
                 self.graph.record_resolved_name(name_id, declaration_id);
-                Outcome::Resolved(declaration_id, id_needing_linearization)
+                Outcome::Resolved(declaration_id)
             }
             other => other,
         }
@@ -1344,12 +1352,14 @@ impl<'a> Resolver<'a> {
             // If we have `A::B`, the owner of `B` is whatever `A` resolves to.
             // If `A` is an alias, resolve through to get the actual namespace.
             match self.resolve_constant_internal(parent_scope) {
-                Outcome::Resolved(id, linearization) => self.resolve_to_primary_namespace(id, linearization),
+                Outcome::Resolved(id) => self.resolve_to_primary_namespace(id),
                 // The parent scope is genuinely unknown — not a circular alias or pending
                 // linearization, but a name that doesn't exist anywhere in the graph.
-                Outcome::Unresolved(None) => Outcome::Unresolved(None),
-                Outcome::Retry(None) if !preserve_retry => Outcome::Unresolved(None),
-                other => other,
+                Outcome::Unresolved => Outcome::Unresolved,
+                Outcome::Retry {
+                    partial_ancestors: false,
+                } if !preserve_retry => Outcome::Unresolved,
+                retry @ Outcome::Retry { .. } => retry,
             }
         } else if let Some(nesting_id) = name_ref.nesting()
             && !name_ref.parent_scope().is_top_level()
@@ -1360,16 +1370,18 @@ impl<'a> Resolver<'a> {
             //   end
             // If `ALIAS` points to `Outer`, `CONST` should be owned by `Outer::Target`, not `ALIAS::Target`.
             match self.graph.names().get(nesting_id).unwrap() {
-                NameRef::Resolved(resolved) => self.resolve_to_primary_namespace(*resolved.declaration_id(), None),
+                NameRef::Resolved(resolved) => self.resolve_to_primary_namespace(*resolved.declaration_id()),
                 NameRef::Unresolved(_) => {
                     // The only case where we wouldn't have the nesting resolved at this point is if it's available through
                     // inheritance or if it doesn't exist, so we need to retry later
-                    Outcome::Retry(None)
+                    Outcome::Retry {
+                        partial_ancestors: false,
+                    }
                 }
             }
         } else {
             // Any constants at the top level are owned by Object
-            Outcome::Resolved(*OBJECT_ID, None)
+            Outcome::Resolved(*OBJECT_ID)
         }
     }
 
@@ -1390,7 +1402,7 @@ impl<'a> Resolver<'a> {
         // promotes it correctly. Using nesting would incorrectly create `SomeModule::A`.
         let parent_owner_id = if parent_has_parent_scope {
             match self.name_owner_id(parent_scope, false) {
-                Outcome::Resolved(id, _) => id,
+                Outcome::Resolved(id) => id,
                 _ => self.create_todo_for_parent(parent_scope),
             }
         } else {
@@ -1398,8 +1410,8 @@ impl<'a> Resolver<'a> {
         };
 
         // Ensure we follow constant aliases if that's the parent
-        let parent_owner_id = match self.resolve_to_primary_namespace(parent_owner_id, None) {
-            Outcome::Resolved(id, _) => id,
+        let parent_owner_id = match self.resolve_to_primary_namespace(parent_owner_id) {
+            Outcome::Resolved(id) => id,
             _ => *OBJECT_ID,
         };
 
@@ -1428,16 +1440,14 @@ impl<'a> Resolver<'a> {
 
     /// Resolves a declaration ID through any alias chain to get the primary (first) namespace.
     /// Returns `Retry` if the primary alias target hasn't been resolved yet.
-    fn resolve_to_primary_namespace(
-        &self,
-        declaration_id: DeclarationId,
-        linearization: Option<DeclarationId>,
-    ) -> Outcome {
+    fn resolve_to_primary_namespace(&self, declaration_id: DeclarationId) -> Outcome {
         let resolved_ids = self.resolve_alias_chains(declaration_id);
 
         // Get the primary (first) resolved target
         let Some(&primary_id) = resolved_ids.first() else {
-            return Outcome::Retry(None);
+            return Outcome::Retry {
+                partial_ancestors: false,
+            };
         };
 
         // Check if the primary result is still an unresolved alias
@@ -1445,15 +1455,18 @@ impl<'a> Resolver<'a> {
             self.graph.declarations().get(&primary_id),
             Some(Declaration::ConstantAlias(_))
         ) {
-            return Outcome::Retry(None);
+            return Outcome::Retry {
+                partial_ancestors: false,
+            };
         }
 
-        Outcome::Resolved(primary_id, linearization)
+        Outcome::Resolved(primary_id)
     }
 
     /// Attempts to resolve a constant reference against the graph. Returns the fully qualified declaration ID that the
     /// reference is related to or `None`. This method mutates the graph to remember which constants have already been
     /// resolved
+    #[allow(clippy::too_many_lines)]
     fn resolve_constant_internal(&mut self, name_id: NameId) -> Outcome {
         let name_ref = self.graph.names().get(&name_id).unwrap().clone();
 
@@ -1463,7 +1476,7 @@ impl<'a> Resolver<'a> {
                     ParentScope::TopLevel => {
                         let result = self.search_ancestors(*OBJECT_ID, *name.str());
 
-                        if let Outcome::Resolved(declaration_id, _) = result {
+                        if let Outcome::Resolved(declaration_id) = result {
                             self.graph.record_resolved_name(name_id, declaration_id);
                         }
 
@@ -1471,7 +1484,9 @@ impl<'a> Resolver<'a> {
                     }
                     ParentScope::Attached(parent_scope_id) => {
                         let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
-                            return Outcome::Retry(None);
+                            return Outcome::Retry {
+                                partial_ancestors: false,
+                            };
                         };
 
                         let mut target_decl_id = *parent_scope.declaration_id();
@@ -1485,13 +1500,15 @@ impl<'a> Resolver<'a> {
                             if resolved_ids.iter().any(|id| {
                                 matches!(self.graph.declarations().get(id), Some(Declaration::ConstantAlias(_)))
                             }) {
-                                return Outcome::Retry(None);
+                                return Outcome::Retry {
+                                    partial_ancestors: false,
+                                };
                             }
 
                             let Some(&namespace_id) = resolved_ids.iter().find(|id| {
                                 matches!(self.graph.declarations().get(id), Some(Declaration::Namespace(_)))
                             }) else {
-                                return Outcome::Unresolved(None);
+                                return Outcome::Unresolved;
                             };
 
                             target_decl_id = namespace_id;
@@ -1499,17 +1516,21 @@ impl<'a> Resolver<'a> {
 
                         // If we found a singleton reference with a resolved attached object parent scope, we
                         // automatically create the singleton class
-                        let Some(singleton_id) = self.get_or_create_singleton_class(target_decl_id, false) else {
-                            return Outcome::Unresolved(None);
+                        let Some(singleton_id) =
+                            self.get_or_create_singleton_class(target_decl_id, SingletonAncestors::Enqueue)
+                        else {
+                            return Outcome::Unresolved;
                         };
                         self.graph.record_resolved_name(name_id, singleton_id);
-                        Outcome::Resolved(singleton_id, Some(singleton_id))
+                        // `get_or_create_singleton_class` already enqueued the singleton's ancestors on
+                        // creation, so there is nothing to hand back for re-enqueueing.
+                        Outcome::Resolved(singleton_id)
                     }
                     ParentScope::None => {
                         // Otherwise, it's a simple constant read and we can resolve it directly
                         let result = self.run_resolution(&name);
 
-                        if let Outcome::Resolved(declaration_id, _) = result {
+                        if let Outcome::Resolved(declaration_id) = result {
                             self.graph.record_resolved_name(name_id, declaration_id);
                         }
 
@@ -1517,7 +1538,9 @@ impl<'a> Resolver<'a> {
                     }
                     ParentScope::Some(parent_scope_id) => {
                         let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
-                            return Outcome::Retry(None);
+                            return Outcome::Retry {
+                                partial_ancestors: false,
+                            };
                         };
 
                         // Resolve the namespace in case it's an alias (e.g., ALIAS::CONST where ALIAS = Foo)
@@ -1525,29 +1548,36 @@ impl<'a> Resolver<'a> {
                         let resolved_ids = self.resolve_alias_chains(*parent_scope.declaration_id());
 
                         // Search each resolved target for the constant. Return early if found.
-                        let mut missing_linearization_id = None;
+                        let mut missing_partial = false;
                         let mut found_namespace = false;
 
                         for &id in &resolved_ids {
                             match self.graph.declarations().get(&id) {
                                 Some(Declaration::ConstantAlias(_)) => {
                                     // Alias not fully resolved yet
-                                    return Outcome::Retry(None);
+                                    return Outcome::Retry {
+                                        partial_ancestors: false,
+                                    };
                                 }
                                 Some(Declaration::Namespace(_)) => {
                                     found_namespace = true;
 
                                     match self.search_ancestors(id, *name.str()) {
-                                        Outcome::Resolved(declaration_id, missing_linearization_id) => {
+                                        Outcome::Resolved(declaration_id) => {
                                             self.graph.record_resolved_name(name_id, declaration_id);
-                                            return Outcome::Resolved(declaration_id, missing_linearization_id);
+                                            return Outcome::Resolved(declaration_id);
+                                        }
+                                        Outcome::Retry {
+                                            partial_ancestors: true,
+                                        } => {
+                                            missing_partial = true;
                                         }
-                                        Outcome::Retry(Some(needs_linearization_id))
-                                        | Outcome::Unresolved(Some(needs_linearization_id)) => {
-                                            missing_linearization_id.get_or_insert(needs_linearization_id);
+                                        Outcome::Unresolved => {}
+                                        Outcome::Retry {
+                                            partial_ancestors: false,
+                                        } => {
+                                            unreachable!("search_ancestors never returns a non-partial Retry")
                                         }
-                                        Outcome::Unresolved(None) => {}
-                                        Outcome::Retry(_) => unreachable!("search_ancestors never returns Retry"),
                                     }
                                 }
                                 _ => {
@@ -1558,15 +1588,19 @@ impl<'a> Resolver<'a> {
 
                         // If no namespaces were found, this constant path can never resolve.
                         if !found_namespace {
-                            return Outcome::Unresolved(None);
+                            return Outcome::Unresolved;
                         }
 
-                        // Member not found in any namespace yet - retry in case it's added later
-                        missing_linearization_id.map_or(Outcome::Retry(None), |id| Outcome::Unresolved(Some(id)))
+                        // Member not found in any namespace yet - retry in case it's added later. `partial` records
+                        // whether the miss was due to a still-partial ancestor chain, so the unit is re-checked once
+                        // that chain completes.
+                        Outcome::Retry {
+                            partial_ancestors: missing_partial,
+                        }
                     }
                 }
             }
-            NameRef::Resolved(resolved) => Outcome::Resolved(*resolved.declaration_id(), None),
+            NameRef::Resolved(resolved) => Outcome::Resolved(*resolved.declaration_id()),
         }
     }
 
@@ -1639,13 +1673,15 @@ impl<'a> Resolver<'a> {
             let (ancestor_outcome, nesting_decl_id) = match self.graph.names().get(nesting).unwrap() {
                 NameRef::Resolved(nesting_name_ref) => {
                     let resolved_ids = self.resolve_alias_chains(*nesting_name_ref.declaration_id());
-                    let mut result = Outcome::Unresolved(None);
+                    let mut result = Outcome::Unresolved;
                     let mut decl_id = None;
 
                     for &id in &resolved_ids {
                         match self.graph.declarations().get(&id) {
                             Some(Declaration::ConstantAlias(_)) => {
-                                result = Outcome::Retry(None);
+                                result = Outcome::Retry {
+                                    partial_ancestors: false,
+                                };
                                 break;
                             }
                             Some(Declaration::Namespace(_)) => {
@@ -1659,7 +1695,12 @@ impl<'a> Resolver<'a> {
 
                     (result, decl_id)
                 }
-                NameRef::Unresolved(_) => (Outcome::Retry(None), None),
+                NameRef::Unresolved(_) => (
+                    Outcome::Retry {
+                        partial_ancestors: false,
+                    },
+                    None,
+                ),
             };
 
             if matches!(ancestor_outcome, Outcome::Resolved(..)) {
@@ -1674,18 +1715,18 @@ impl<'a> Resolver<'a> {
                     Some(Declaration::Namespace(Namespace::Module(_) | Namespace::Todo(_)))
                 )
             });
-            let chain_incomplete = matches!(ancestor_outcome, Outcome::Retry(Some(_)) | Outcome::Unresolved(Some(_)));
+            let chain_incomplete = matches!(
+                ancestor_outcome,
+                Outcome::Retry {
+                    partial_ancestors: true
+                }
+            );
 
             if is_module || chain_incomplete {
                 let object_outcome = self.search_ancestors(*OBJECT_ID, str_id);
 
-                if let Outcome::Resolved(decl_id, _) = object_outcome {
-                    // Preserve the linearization ID so the chain gets re-checked once complete
-                    let linearization_id = match ancestor_outcome {
-                        Outcome::Retry(id) | Outcome::Unresolved(id) => id,
-                        Outcome::Resolved(..) => unreachable!("guarded by early return above"),
-                    };
-                    return Outcome::Resolved(decl_id, linearization_id);
+                if let Outcome::Resolved(decl_id) = object_outcome {
+                    return Outcome::Resolved(decl_id);
                 }
             }
 
@@ -1712,12 +1753,12 @@ impl<'a> Resolver<'a> {
                             .as_namespace()
                             .unwrap()
                             .member(&str_id)
-                            .map(|id| Outcome::Resolved(*id, None))
+                            .map(|id| Outcome::Resolved(*id))
                     } else {
                         None
                     }
                 })
-                .unwrap_or(Outcome::Unresolved(None)),
+                .unwrap_or(Outcome::Unresolved),
             Ancestors::Partial(ids) => {
                 for ancestor_id in ids {
                     match ancestor_id {
@@ -1725,7 +1766,9 @@ impl<'a> Resolver<'a> {
                             // Stop at unresolved ancestors to avoid resolving to a later one.
                             // Skip if the name matches what we're searching for.
                             if *self.graph.names().get(&name_id).unwrap().str() != str_id {
-                                return Outcome::Retry(Some(declaration_id));
+                                return Outcome::Retry {
+                                    partial_ancestors: true,
+                                };
                             }
                         }
                         Ancestor::Complete(ancestor_id) => {
@@ -1738,12 +1781,14 @@ impl<'a> Resolver<'a> {
                                 .unwrap()
                                 .member(&str_id)
                             {
-                                return Outcome::Resolved(*id, Some(declaration_id));
+                                return Outcome::Resolved(*id);
                             }
                         }
                     }
                 }
-                Outcome::Unresolved(Some(declaration_id))
+                Outcome::Retry {
+                    partial_ancestors: true,
+                }
             }
         }
     }
@@ -1760,16 +1805,18 @@ impl<'a> Resolver<'a> {
                     && let Some(namespace) = self.graph.declarations().get(&namespace_id).unwrap().as_namespace()
                     && let Some(member) = namespace.member(&str_id)
                 {
-                    return Outcome::Resolved(*member, None);
+                    return Outcome::Resolved(*member);
                 }
 
                 current_name = nesting_name_ref.name();
             } else {
-                return Outcome::Retry(None);
+                return Outcome::Retry {
+                    partial_ancestors: false,
+                };
             }
         }
 
-        Outcome::Unresolved(None)
+        Outcome::Unresolved
     }
 
     /// Returns a complexity score for a given name, which is used to sort names for resolution. The complexity is based
@@ -1980,7 +2027,7 @@ impl<'a> Resolver<'a> {
 
                 let (inner_parent, partial) = self.singleton_parent_id(owner_id);
                 (
-                    self.get_or_create_singleton_class(inner_parent, false)
+                    self.get_or_create_singleton_class(inner_parent, SingletonAncestors::Deferred)
                         .expect("singleton parent should always be a namespace"),
                     partial,
                 )
@@ -1991,7 +2038,7 @@ impl<'a> Resolver<'a> {
 
                 let (picked_parent, unresolved_parent) = self.get_parent_class(&definition_ids);
                 (
-                    self.get_or_create_singleton_class(picked_parent, false)
+                    self.get_or_create_singleton_class(picked_parent, SingletonAncestors::Deferred)
                         .expect("parent class should always be a namespace"),
                     unresolved_parent.is_some(),
                 )