You add a second embedded type to a Go struct and importers' calls stop compiling - why?

## Two embedded types share one namespace Consider a reconciler that compares desired state against observed state. It started life embedding one helper; a year later, with the original author gone, someone adds a second: ```go type SpecSource struct{} func (SpecSource) Refresh() {} type StatusSource struct{} func (StatusSource) Refresh() {} type Reconciler struct { SpecSource StatusSource } ``` This compiles. The struct declaration is perfectly legal - Go does not complain that two embedded types both offer `Refresh`. The trouble starts at the first use: ```go r.Refresh() // ambiguous selector r.Refresh ``` ### The rule underneath Promotion is resolved by **depth**. A selector on the outer type looks for the shallowest declaration of that name: a method or field declared directly on the outer type is depth zero, anything promoted from an embedded field is depth one, from a field embedded inside that, depth two, and so on. The shallowest wins outright. But **two candidates at equal depth are ambiguous**, and an ambiguous name is simply not promoted - it does not exist on the outer type at all. Three consequences follow, and each one bites differently. **1. The error appears where the name is used, not where it is declared.** Your own package may never call `r.Refresh()`, so `go build ./...` in your module is green. The breakage is in other people's packages, discovered after you have tagged and published the change. Everything reachable through the explicit path still works: `r.SpecSource.Refresh()` is unambiguous and always was. **2. The method leaves the method set, so interface satisfaction changes silently.** If `Reconciler` was being passed to something that accepts an interface with a `Refresh` method, that assignment now fails to compile - possibly in a completely different file from any call to `Refresh`. If the value was being stored in an interface variable at a distance, the error surfaces somewhere that looks unrelated to your change. **3. The same rule applies to fields.** Two embedded structs that both have a `Name` field make `r.Name` ambiguous in exactly the same way. Promotion is one mechanism for methods and fields alike. ### The fix Declare the method on the outer type. Depth zero beats both candidates, and you say explicitly which one you meant: ```go func (r Reconciler) Refresh() { r.SpecSource.Refresh() } ``` That is the whole repair, and it is worth noticing what it is: the forwarding method you would have written on day one if the field had simply been named. The ambiguity did not create the work, it deferred it - and deferred it past the point where the change is free. ### Diagnosing it in the wild The compiler message is direct - it names the ambiguous selector at the offending expression - so the diagnosis is fast once you see it. The hard part is that you may not be the one who sees it. Two habits catch it earlier: - Build the *consumers* you know about, not only your own module, before publishing a change that adds an embedded field. - Treat "added an embedded field" as an API change in review, the same way you would treat adding a method to an exported interface. Both alter what compiles for someone else. ### Why it happens at all The pull towards a second embed is real: you need one more collaborator's behaviour, the first one is already embedded, and matching the existing style feels like the polite thing to do. But embedding is not a style; it is a claim on a namespace shared between you and every type you embed. Two embedded types make it a namespace shared between three authors, none of whom coordinate - and either dependency can create the collision later just by adding a method in a minor release. The defensive posture is the same one that avoids most of these problems: embed at most one thing in an exported type, and only when its entire API is deliberately yours. Hold the rest in named fields and forward the two or three calls you actually need. The forwarding methods are boring, and boring is the property you want in a public surface.