Improve mock generation for fulfilledByType and mockOnly coexistence

CLAUDE.md

@@ -60,6 +60,7 @@ The production code path (`generatePropertyCode` with `.dependencyTree`) and moc
 - `TypeDescription.simplified` strips wrappers for cleaner suffixes, with fallback on collision
 - Closure-typed defaults use `@escaping T = default` (not `@autoclosure`)
 - `#SafeDIConfiguration` is always read from the current module only, never dependent modules
+- When a mockOnly and a non-mockOnly coexist for the same type, `resolveSafeDIFulfilledTypes` merges them. The `(false, true)` and `(true, false)` branches handle opposite processing orders. Any cross-cutting concern (tracking sets, stale clearing) must be applied to both branches or order-dependent bugs will surface only on CI.
 
 ### Validation boundaries
 
@@ -89,6 +90,8 @@ The `Instantiable` struct conforms to `Codable` and is serialized as JSON in `.s
 - **Test through the pipeline**, not direct model construction. Mock tests use `executeSafeDIToolTest` which parses real Swift source through the full visitor → generator pipeline.
 - **Full `==` output comparison.** Never use `.contains()` for mock output. Compare the complete expected string.
 - **Verify updated test expectations compile.** When updating expected output in generator tests, review the new expected code to confirm it would compile as valid Swift. Check that variable references resolve to the correct scope, types match (no optional where non-optional expected), and all referenced variables have bindings. Do not blindly update expected output to match actual — the actual output may itself be buggy.
+- **Code generation tests should only test paths where the macro would not emit an error.** Test inputs must be valid under `@Instantiable` macro validation — every `mockOnly: true` type needs a `mock()` method (or `customMockName` method), mock method names on the same type must not collide, and production types need `init` or `instantiate()`.
+- **Test titles must be observably verified.** When a test title says "prefers X over Y", the assertion must verify X is used — not just that the test doesn't crash. Add a parent type with `generateMock: true` that instantiates the type under test, and assert the full mock output shows X's method name.
 - **If code can't be covered by a test with real parsed input, remove the code.** Dead branches and defensive fallbacks for structurally unreachable paths should not exist.
 - **Test fixture file naming affects processing order.** `executeSafeDIToolTest` names fixture files by extracting the type name from `@Instantiable` in the source content. Files are processed alphabetically, so the order types appear in `resolveSafeDIFulfilledTypes` depends on these names. When testing ordering-sensitive behavior (e.g., duplicate detection), be aware that a `struct MyService` file sorts differently than an `extension MyService` file (which falls back to `"File"`).
 
@@ -99,3 +102,6 @@ The `Instantiable` struct conforms to `Codable` and is serialized as JSON in `.s
 - Extension-based `@Instantiable` types use `static func instantiate(...)` instead of `init(...)`. Their `@Instantiated` dependencies are constructed by the parent scope.
 - When a received dependency is promoted to root scope, the producer branch must capture the root-bound value — not reconstruct the type.
 - `resolvedParameters` flows through sibling accumulation AND parent-to-child descent. Both paths must be consistent.
+- `typeDescriptionToFulfillingInstantiableMap` is a dictionary — iterating `.values` has non-deterministic order. Any code that reduces, sorts, or builds state from `.values` must produce the same result regardless of iteration order. CI runs tests 5 times specifically to catch non-determinism.
+- `resolveSafeDIFulfilledTypes` can produce multiple map entries with the same `concreteInstantiable` under different keys (e.g., a merged entry under `MyService` and an unmerged entry under `ServiceProtocol`). These entries may have different mock info. The mock scope map uses scope-reuse by `concreteInstantiable` and a deterministic sort to handle this.
+- `mockInitializer` on an `Instantiable` can be inherited from a mockOnly merge — it doesn't always mean the type declared its own mock. `generateMock` is never inherited. Use `mockReturnTypeIsCompatible(withPropertyType: concreteInstantiable)` to distinguish genuine hand-written mocks from inherited ones.

Documentation/Manual.md

@@ -595,9 +595,9 @@ extension MyService {
 }
 ```
 
-When both declarations exist, SafeDI uses the production `@Instantiable` for the dependency tree and the `mockOnly` declaration for mock generation. At most one declaration may provide a mock — if both provide mock methods, SafeDI emits an error.
+When both declarations exist, SafeDI uses the production `@Instantiable` for the dependency tree and the `mockOnly` declaration’s hand-written mock for mock generation. If the production type also has a hand-written `mock()` method, SafeDI emits an error — a type can have at most one hand-written mock. A `generateMock: true` production type that lacks a hand-written mock will use the `mockOnly` declaration’s mock, since hand-written mocks take priority over generated ones.
 
-Your user-defined `mock()` method must be `public` (or `open`) and must accept parameters for each of the type’s `@Instantiated`, `@Received`, and `@Forwarded` dependencies. Non-dependency parameters must have default values. On concrete type declarations the return type must be `Self`, the type name, or a type listed in `fulfillingAdditionalTypes`; on extension-based `@Instantiable` types the return type must match the extended type (e.g. `-> Container<Bool>`) or a `fulfillingAdditionalTypes` entry, mirroring the corresponding `instantiate()` method. The `@Instantiable` macro validates these requirements and provides fix-its for any issues.
+Your user-defined `mock()` method must be `public` (or `open`) and must accept parameters for each of the type’s `@Instantiated`, `@Received`, and `@Forwarded` dependencies. Non-dependency parameters must have default values. On concrete type declarations the return type must be `Self` or the type name; on extension-based `@Instantiable` types the return type must match the extended type (e.g. `-> Container<Bool>`) or a `fulfillingAdditionalTypes` entry, mirroring the corresponding `instantiate()` method. The `@Instantiable` macro validates these requirements and provides fix-its for any issues.
 
 ```swift
 #if DEBUG

Sources/SafeDI/Decorators/Instantiable.swift

@@ -53,7 +53,7 @@
 ///   - isRoot: Whether the decorated type represents a root of a dependency tree.
 ///   - additionalTypes: The types (in addition to the type decorated with this macro) of properties that can be decorated with `@Instantiated` and yield a result of this type. The types provided *must* be either superclasses of this type or protocols to which this type conforms.
 ///   - conformsElsewhere: Whether the decorated type already conforms to the `Instantiable` protocol elsewhere. If set to `true`, the macro does not enforce that this declaration conforms to `Instantiable`.
-///   - mockOnly: Whether this declaration exists solely for mock generation. When `true`, you must provide a hand-written `mock()` method (or a method named by `customMockName`). No `init`/`instantiate()` or `Instantiable` conformance is required. Mutually exclusive with `generateMock` and `isRoot`. Defaults to `false`.
+///   - mockOnly: Whether this declaration exists solely for mock generation. When `true`, you must provide a hand-written `mock()` method (or a method named by `customMockName`). No `init`/`instantiate()` or `Instantiable` conformance is required. Hand-written mocks take priority over generated ones — a `mockOnly` mock is used even when the production type has `generateMock: true`. A type can have at most one hand-written mock; if the production type also has a hand-written mock, SafeDI emits an error. Mutually exclusive with `generateMock` and `isRoot`. Defaults to `false`.
 ///   - mockAttributes: Attributes to add to the generated `mock()` method. Use this when the type’s initializer is bound to a global actor that the plugin cannot detect from source (e.g. inherited `@MainActor`). Example: `@Instantiable(mockAttributes: "@MainActor")`.
 ///   - generateMock: Whether to generate a `mock()` method for this type. Defaults to `false`.
 ///   - customMockName: The name of a hand-written mock method. With `generateMock: true`, the generated `mock()` calls through to this method (it must have a different name to avoid ambiguity). With `mockOnly: true`, SafeDI uses this method as the mock provider for the type. Requires `generateMock: true` or `mockOnly: true`.

Sources/SafeDICore/Generators/DependencyTreeGenerator.swift

@@ -113,14 +113,15 @@ public actor DependencyTreeGenerator {
 		// Compute types with hand-written mocks that can be called with zero arguments,
 		// suitable for use as default values in forwarded mock parameters. This includes
 		// standalone mockOnly types AND merged entries where a mockOnly declaration's mock
-		// was copied onto a non-mockOnly production entry. Types whose mock method has
-		// required parameters are excluded, since the generated default `Type.mock()` would
-		// not compile.
+		// was copied onto a production entry (which may also have generateMock). Types
+		// whose mock method has required parameters are excluded. The mock return type
+		// must be compatible with the concrete type — extension mocks returning a
+		// protocol type are not valid defaults for concrete-type forwarded parameters.
 		let forwardedParameterMockDefaults: [TypeDescription: String] = typeDescriptionToFulfillingInstantiableMap.values
 			.reduce(into: [TypeDescription: String]()) { result, instantiable in
-				guard !instantiable.generateMock,
-				      let mockInitializer = instantiable.mockInitializer,
-				      mockInitializer.arguments.allSatisfy(\.hasDefaultValue)
+				guard let mockInitializer = instantiable.mockInitializer,
+				      mockInitializer.arguments.allSatisfy(\.hasDefaultValue),
+				      instantiable.mockReturnTypeIsCompatible(withPropertyType: instantiable.concreteInstantiable)
 				else { return }
 				result[instantiable.concreteInstantiable] = instantiable.customMockName ?? InstantiableVisitor.mockMethodName
 			}
@@ -142,20 +143,35 @@ public actor DependencyTreeGenerator {
 			      seen.insert(instantiable.concreteInstantiable).inserted,
 			      let scope = typeDescriptionToScopeMap[instantiable.concreteInstantiable]
 			else { continue }
+			// Canonicalize: slot-specific merges can produce different entries
+			// for the same concreteInstantiable (e.g., the ServiceProtocol key
+			// has a protocol-returning mock but the MyService key does not).
+			// Always use the concrete-type key entry so mock root generation
+			// uses the correct mock info for the concrete type.
+			let instantiable = typeDescriptionToFulfillingInstantiableMap[instantiable.concreteInstantiable] ?? instantiable
 			if let currentModuleSourceFilePaths, !isAdditionalMock {
 				guard let sourceFilePath = instantiable.sourceFilePath,
 				      currentModuleSourceFilePaths.contains(sourceFilePath)
 				else { continue }
 			}
 
 			// Validate that this type's constant @Instantiated children have no @Forwarded properties.
+			// Use the mock scope map (not typeDescriptionToFulfillingInstantiableMap) because
+			// mockOnly types can win additional-type slots and may have different @Forwarded properties.
+			// For fulfilledByType deps, validate against the declared type (same as mock resolution).
 			for dependency in scope.instantiable.dependencies {
-				guard case .instantiated = dependency.source else { continue }
+				guard case let .instantiated(fulfillingTypeDescription, _) = dependency.source else { continue }
 				let instantiatedType = dependency.asInstantiatedType
-				if let childInstantiable = typeDescriptionToFulfillingInstantiableMap[instantiatedType] {
+				let childScope: Scope? = if fulfillingTypeDescription != nil {
+					typeDescriptionToScopeMap[dependency.property.typeDescription.asInstantiatedType]
+						?? typeDescriptionToScopeMap[instantiatedType]
+				} else {
+					typeDescriptionToScopeMap[instantiatedType]
+				}
+				if let childScope {
 					try validateNoForwardedProperties(
 						for: dependency,
-						instantiable: childInstantiable,
+						instantiable: childScope.instantiable,
 						parent: scope.instantiable,
 					)
 				}
@@ -714,23 +730,97 @@ public actor DependencyTreeGenerator {
 	/// but includes ALL types (not just reachable from roots). Received dependencies are NOT
 	/// promoted here — they're promoted at the root level in `createMockRootScopeGenerator`.
 	private func createMockTypeDescriptionToScopeMapping() -> [TypeDescription: Scope] {
-		// Create scopes for all types.
+		// Create scopes for all types. Process non-mockOnly types first so they
+		// claim additional-type slots. mockOnly types then overwrite slots whose
+		// existing scope lacks a compatible hand-written mock.
+		// Multiple map entries can share a concreteInstantiable but have different
+		// instantiableTypes (e.g., a mockOnly with extra fulfillingAdditionalTypes).
+		// Reuse the same scope for all entries sharing a concreteInstantiable so
+		// every instantiableType is mapped.
+		var visitedConcreteTypeToScope = [TypeDescription: Scope]()
 		let typeDescriptionToScopeMap: [TypeDescription: Scope] = typeDescriptionToFulfillingInstantiableMap.values
+			.sorted { lhs, rhs in
+				// Non-mockOnly before mockOnly (production claims slots first).
+				if lhs.mockOnly != rhs.mockOnly {
+					return !lhs.mockOnly
+				} else {
+					// Within the same mockOnly tier, prefer entries with mock info
+					// so scope-reuse creates scopes from mock-capable entries.
+					// Hand-written mocks (mockInitializer) before generateMock,
+					// since hand-written mocks take priority.
+					let lhsHasHandWrittenMock = lhs.mockInitializer != nil
+					let rhsHasHandWrittenMock = rhs.mockInitializer != nil
+					if lhsHasHandWrittenMock != rhsHasHandWrittenMock {
+						return lhsHasHandWrittenMock
+					} else {
+						let lhsHasMock = lhs.generateMock || lhsHasHandWrittenMock
+						let rhsHasMock = rhs.generateMock || rhsHasHandWrittenMock
+						if lhsHasMock != rhsHasMock {
+							return lhsHasMock
+						} else {
+							// Stable tiebreaker: sort by concrete type name so scope-reuse
+							// selects the same entry across runs.
+							return lhs.concreteInstantiable < rhs.concreteInstantiable
+						}
+					}
+				}
+			}
 			.reduce(into: [TypeDescription: Scope]()) { partialResult, instantiable in
-				guard partialResult[instantiable.concreteInstantiable] == nil else { return }
-				let scope = Scope(instantiable: instantiable)
+				let scope = visitedConcreteTypeToScope[instantiable.concreteInstantiable] ?? Scope(instantiable: instantiable)
+				visitedConcreteTypeToScope[instantiable.concreteInstantiable] = scope
 				for instantiableType in instantiable.instantiableTypes {
-					partialResult[instantiableType] = scope
+					guard let existingScope = partialResult[instantiableType] else {
+						// When a mockOnly entry adds a new slot and the reused scope
+						// lacks mock metadata, use a scope built from the mockOnly's
+						// instantiable so the slot retains the hand-written mock info.
+						// Only when the mock return type is compatible with this slot.
+						if instantiable.mockOnly,
+						   instantiable.mockInitializer != nil,
+						   instantiable.mockReturnTypeIsCompatible(withPropertyType: instantiableType),
+						   scope.instantiable.mockInitializer == nil
+						{
+							partialResult[instantiableType] = Scope(instantiable: instantiable)
+						} else {
+							partialResult[instantiableType] = scope
+						}
+						continue
+					}
+					// A mockOnly hand-written mock overwrites a scope that lacks
+					// its own hand-written mock. generateMock (which wraps init)
+					// does not count — hand-written mocks take priority.
+					// Check compatibility against both the concrete type and the
+					// slot type — extension mocks can validly return a protocol
+					// from fulfillingAdditionalTypes. Also verify the incoming
+					// mockOnly's mock is usable for this slot (its return type
+					// must match the slot type or its own concrete type).
+					if instantiable.mockOnly,
+					   instantiable.mockReturnTypeIsCompatible(withPropertyType: instantiableType),
+					   !existingScope.instantiable.mockReturnTypeIsCompatible(withPropertyType: existingScope.instantiable.concreteInstantiable),
+					   !existingScope.instantiable.mockReturnTypeIsCompatible(withPropertyType: instantiableType)
+					{
+						partialResult[instantiableType] = scope
+					}
 				}
 			}
 
 		// Populate propertiesToGenerate on each scope.
 		for scope in Set(typeDescriptionToScopeMap.values) {
 			for dependency in scope.instantiable.dependencies {
 				switch dependency.source {
-				case let .instantiated(_, erasedToConcreteExistential):
+				case let .instantiated(fulfillingTypeDescription, erasedToConcreteExistential):
+					// For fulfilledByType deps, prefer the declared type for mock
+					// resolution — fulfilledByType is a production-only directive.
+					// The scope map's priority rules determine the best mock for
+					// the declared type. Fall back to the fulfilling type if the
+					// declared type isn't in the scope map.
 					let instantiatedType = dependency.asInstantiatedType
-					if let instantiatedScope = typeDescriptionToScopeMap[instantiatedType] {
+					let declaredType = dependency.property.typeDescription.asInstantiatedType
+					let instantiatedScope: Scope? = if fulfillingTypeDescription != nil {
+						typeDescriptionToScopeMap[declaredType] ?? typeDescriptionToScopeMap[instantiatedType]
+					} else {
+						typeDescriptionToScopeMap[instantiatedType]
+					}
+					if let instantiatedScope {
 						scope.propertiesToGenerate.append(.instantiated(
 							dependency.property,
 							instantiatedScope,

Sources/SafeDICore/Visitors/InstantiableVisitor.swift

@@ -392,10 +392,12 @@ public final class InstantiableVisitor: SyntaxVisitor {
 		case .extensionDecl:
 			if extensionInstantiables.isEmpty, mockOnly, let mockReturnType {
 				// mockOnly extensions without instantiate() still produce an Instantiable
-				// so the type is registered in the mock scope map.
+				// so the type is registered in the mock scope map. Use the extended
+				// type (instantiableType) as the concrete type — not mockReturnType,
+				// which may be a protocol from fulfillingAdditionalTypes.
 				[
 					Instantiable(
-						instantiableType: mockReturnType,
+						instantiableType: instantiableType ?? mockReturnType,
 						isRoot: isRoot,
 						initializer: nil,
 						additionalInstantiables: additionalInstantiables,

Sources/SafeDIMacros/Macros/InstantiableMacro.swift

@@ -578,11 +578,11 @@ public struct InstantiableMacro: MemberMacro {
 				let typeName = concreteDeclaration.name.text
 				let instantiableTypeStrippingGenerics = visitor.instantiableType?.strippingGenerics
 				let mockReturnType = mockSyntax.signature.returnClause?.type.typeDescription
-				let additionalTypesStrippingGenerics = (visitor.additionalInstantiables ?? []).map(\.strippingGenerics)
 				let isSelfReturnType = mockReturnType == .simple(name: "Self", generics: [])
+				// Concrete type mocks must return Self or the type name.
+				// Additional types are only allowed for extension-based mocks.
 				let returnTypeMatchesTypeName = isSelfReturnType
 					|| mockReturnType?.strippingGenerics == instantiableTypeStrippingGenerics
-					|| additionalTypesStrippingGenerics.contains(where: { $0 == mockReturnType?.strippingGenerics })
 				if !returnTypeMatchesTypeName {
 					var fixedMockSyntax = mockSyntax
 					if let existingReturnClause = mockSyntax.signature.returnClause {