feat(symbols): key Android uploads by R8's map id, and upload dSYMs from an Xcode build (#769)

* feat(symbols): find the Android mapping and app version in the build

`ldcli symbols upload --type android` needed a --path pointing at a directory
holding mapping.txt and an --app-version matching what the app reports, so
every project had to add build script code to stage the mapping somewhere and
plumb its version into CI.

The Android Gradle Plugin already writes both: R8's mapping at
<module>/build/outputs/mapping/<variant>/mapping.txt, and the version it
packaged in output-metadata.json beside the APK. Read them, and the command
works from an Android project root with no flags and no build script at all.
Several obfuscated variants is an error naming them rather than a guess, since
only one of them is the build being shipped.

An Android mapping is now also stored as mapping.txt however deep it was found.
Symbolication reads it at <lane>/mapping.txt, so a mapping uploaded from a
nested path was previously keyed somewhere nothing looks.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(symbols): read the Android symbols id out of the packaged app

A build that stamps a content-derived symbols id into assets/ld_symbols_id.txt
had to also stage a mapping.txt.symbolsid sidecar next to a copy of the mapping,
purely so the upload could be keyed by the same id the app reports.

The packaged APK/AAB already carries that asset, and it is the app that will
run: what it carries is exactly what will be reported. Reading it there needs
nothing handed over by the build and leaves no way for the two to disagree, so
the staging step goes away and a stamped build uploads on the Symbols Id Lane
with no flags.

An id that does not match the 32-hex-char shape the SDK reports is ignored
rather than keyed on, since it names a lane nothing would ever ask for.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(symbols): gzip what an upload sends

A release R8 mapping is tens of megabytes of text and every build pushes it
again: the e2e app's is 61.3 MB, which gzips to 5.0 MB in under half a second.
React Native source maps and Apple symbol maps compress on the same order.

Each object is marked Content-Encoding: gzip, so it stays self-describing —
storage returns the header on read, an HTTP client inflates it in transit, and
the backend inflates whatever still arrives compressed.

Artifacts held in memory are compressed before an upload URL is asked for rather
than at the point of sending, because the digest that proves an object is
already stored is compared against the ETag of the stored bytes; hashing the
artifact instead would never match and every source bundle would be re-sent.
Files are compressed as they are read, streamed through the compressor so a
large mapping is never held in memory whole.

Anything that comes out of gzip no smaller is sent as it is, so a .srcbundle,
which already gzips its own entries, is not wrapped a second time.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(symbols): build the R8 index in the CLI instead of uploading the mapping

An Android upload sent R8's mapping.txt as it was, tens of megabytes of text, and
the backend parsed it into a random-access index on the first crash of every build
that ever crashed. The mapping is here, on the machine that just produced it, so
the index is built here too and the text is never stored: `upload` and `generate`
now write mapping.v1.index to the Symbols Id and Version lanes.

The mapping is streamed through r8index.EncodeFrom rather than parsed into memory,
so a build machine does not have to find hundreds of megabytes to produce a few.
A mapping that yields no index is an error: symbolication reads only the index, so
storing anything else would leave a build looking like it has symbols while every
crash arrives obfuscated.

internal/symbols/r8index is a verbatim copy of the backend's package, the way
dsymmap and srcbundle already are, and srcbundle.Builder now compresses on add so
that a per-class bundle costs its compressed size rather than its raw one.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(symbols): pin the R8 index format with a golden fixture

The r8index package exists twice, here and in the backend that reads what this
writes, and an index is only interchangeable if the two copies agree byte for byte.
Two copies cannot import each other's tests, so what they share is a fixture: a
readable mapping and the exact index bytes it encodes to, identical in both repos.
Either side drifting now fails here rather than in production, where the symptom
would be an unreadable index or a silently wrong frame.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(symbols): cross-check a CLI-built index against its mapping

The golden fixture proves the encoder here still produces the bytes both repos
agreed on; this proves the artifact a build machine wrote answers like the mapping
it came from, which is the guarantee symbolication actually rests on. Opt-in via
R8_MAPPING and R8_INDEX, since it needs a real release build.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(symbols): name the real mapping to check against with a flag

Keeps the r8index copy in step with the backend's, where reading these paths from
R8_MAPPING and R8_INDEX fails a CI check that bans os.Getenv anywhere in the
backend. A test flag is what the package already reaches for anyway (-update, for
the golden fixture).

end-of-file-fixer runs here too, through pre-commit, and it appended a newline to
the backend's copy of the golden index — a byte that moves the footer the reader
locates the index by, and breaks the byte-for-byte agreement the fixture exists to
prove. It cannot tell a binary file from a text one, so *.index is excluded.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(symbols): accept --source-path on `symbols generate`

Generating an Android source bundle reads sourcePathFlag, which generate never
registered: --source-path was rejected outright, so sources could only be scanned
from the working directory. The read answered anyway, because both commands bind
the same viper keys and upload's flag was left to supply the default — a value the
caller of generate could neither see nor change.

Also stop describing --include-sources as Apple-only, since an Android mapping
carries sources now too.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(symbols): key an Android upload by the id R8 recorded for the mapping

An Android build only reached the Symbols Id Lane if something had stamped an
id into the app for it, which meant a Gradle task in every project that wanted
one. R8 has been recording an id for its own mapping all along — "# pg_map_id:"
in the header — and from AGP 8.12 it stamps that same id into each class, so
the shipped app already reports it on every frame of every crash.

Read it from the header when no id was given or found in the packaged app, and
key the upload by it. A project that adds nothing to its build now uploads to
the lane its crashes arrive on; an id the app stamped still wins, since that is
a build saying what it will report, and the only answer for one too old for R8
to stamp anything itself.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(symbols): upload the dSYMs an Xcode build just produced

A dSYM is best uploaded by the build that made it, which means a Run Script
phase — and every project writing one wrote the same two pieces of shell first:
a --path pointing at DWARF_DSYM_FOLDER_PATH, and a guard skipping the
configurations that make no dSYM, without which a Debug build fails on "no
.dSYM bundles found". Both are debugged inside a build phase, where the way you
find out is a failed build.

Read the folder from the build environment when no --path was given, and treat
finding no dSYM there as nothing to do rather than as an error. What a phase has
to say is now the project it uploads to. An explicit --path still wins, so
uploading a dSYM from an archive or from CI is unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(symbols): one index per mapping when a class name repeats

Mirrors the observability copy of r8index, which has to stay byte-identical apart
from the srcbundle import path.

srcbundle.Builder.Add ignores a key it already holds, so streaming keeps the first
block for a repeated obfuscated name, while Parse's map assignment kept the last.
One mapping then encoded to two different indexes depending on which encoder read
it, which is not something an artifact addressed by its mapping's id can afford.
Parse keeps the first too: streaming has no other option, since a class is gzipped
and handed off before a duplicate arrives.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: abelonogov-ld

cmd/symbols/android_mapid.go

@@ -0,0 +1,58 @@
+package symbols
+
+import (
+	"bufio"
+	"os"
+	"regexp"
+	"strings"
+)
+
+// The id R8 gives the mapping it produced.
+//
+// R8 writes "# pg_map_id: <hash of the mapping>" into every mapping's header, and
+// from AGP 8.12 it stamps that same id into each class's source file attribute — so
+// a shipped app reports "r8-map-id-<hash>" where a file name goes, on every frame of
+// every crash. Keying the upload by it puts the index exactly where symbolication
+// will look for a build that was asked to do nothing at all.
+//
+// It is read out of the header rather than recomputed here because the header is
+// R8's own statement of what it stamped. A hash computed on this side would have to
+// agree with R8's forever, and would be silently wrong the first time it didn't.
+
+// androidMapIDComment is the mapping header line carrying the id.
+const androidMapIDComment = "# pg_map_id:"
+
+// androidMapIDPattern is the shape of an id that may be keyed by: a hash, which is
+// the mapping's full SHA-256 from AGP 8.12 and a 7-character prefix of it before.
+var androidMapIDPattern = regexp.MustCompile(`^[0-9a-f]{7,64}$`)
+
+// androidMapID returns the id R8 recorded for a mapping, or "" when it recorded none
+// — a mapping written by ProGuard rather than R8, or one old enough to predate the
+// header. Best effort, like every other way of learning what a build shipped: an
+// upload with no id falls back to the Version Lane rather than failing over it.
+func androidMapID(mappingPath string) string {
+	file, err := os.Open(mappingPath)
+	if err != nil {
+		return ""
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		// The header is the comments before the first class, and a release mapping
+		// is tens of megabytes of what follows it.
+		if !strings.HasPrefix(line, "#") {
+			return ""
+		}
+		rest, ok := strings.CutPrefix(line, androidMapIDComment)
+		if !ok {
+			continue
+		}
+		if id := strings.TrimSpace(rest); androidMapIDPattern.MatchString(id) {
+			return id
+		}
+		return ""
+	}
+	return ""
+}

cmd/symbols/android_mapid_test.go

@@ -0,0 +1,82 @@
+package symbols
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The header R8 8.13 writes, trimmed to what is read from it.
+const testMapIDHeader = `# compiler: R8
+# compiler_version: 8.13.19
+# min_api: 23
+# common_typos_disable
+# {"id":"com.android.tools.r8.mapping","version":"2.2"}
+# pg_map_id: 92d0222f1a7a3b92fca00ddc75fbcf893c89be03e02286414d51abcfd9b02063
+# pg_map_hash: SHA-256 92d0222f1a7a3b92fca00ddc75fbcf893c89be03e02286414d51abcfd9b02063
+`
+
+const testMapID = "92d0222f1a7a3b92fca00ddc75fbcf893c89be03e02286414d51abcfd9b02063"
+
+func TestAndroidMapIDReadsTheHeader(t *testing.T) {
+	path := writeMappingFile(t, testMapIDHeader+testAndroidMapping)
+	assert.Equal(t, testMapID, androidMapID(path))
+}
+
+// R8 shortened the id before AGP 8.12, and a build being retraced today may well
+// have been produced by one of those.
+func TestAndroidMapIDReadsAShortID(t *testing.T) {
+	path := writeMappingFile(t, "# compiler: R8\n# pg_map_id: 92d0222\n"+testAndroidMapping)
+	assert.Equal(t, "92d0222", androidMapID(path))
+}
+
+// Nothing here may fail an upload: an id that cannot be read leaves the mapping on
+// the Version Lane, which is where it was before R8 recorded one.
+func TestAndroidMapIDWithoutOne(t *testing.T) {
+	cases := map[string]string{
+		"no header at all":         testAndroidMapping,
+		"a ProGuard mapping":       "com.example.app.CheckoutDemo -> a.b.c:\n",
+		"an id that is not a hash": "# compiler: R8\n# pg_map_id: release-7\n" + testAndroidMapping,
+		"an empty id":              "# compiler: R8\n# pg_map_id:\n" + testAndroidMapping,
+	}
+	for name, mapping := range cases {
+		assert.Emptyf(t, androidMapID(writeMappingFile(t, mapping)), "androidMapID of %s", name)
+	}
+
+	assert.Empty(t, androidMapID(filepath.Join(t.TempDir(), "nothing-here.txt")))
+}
+
+// The header ends at the first class, and what follows is tens of megabytes of a
+// build's own strings — including, in an app that has one, a class whose name would
+// read as a header line to anything still looking.
+func TestAndroidMapIDStopsAtTheFirstClass(t *testing.T) {
+	path := writeMappingFile(t, testAndroidMapping+"# pg_map_id: "+testMapID+"\n")
+	assert.Empty(t, androidMapID(path))
+}
+
+// The point of the id: a build that stamps nothing and is told nothing still uploads
+// to the lane its crashes will arrive on, because R8 recorded which mapping this is
+// and the shipped app reports the same thing on every frame.
+func TestBuildAndroidObjectsKeysByTheMapID(t *testing.T) {
+	path := writeMappingFile(t, testMapIDHeader+testAndroidMapping)
+
+	objects, err := buildAndroidObjects(path, "", "", false, "")
+	require.NoError(t, err)
+	require.Len(t, objects, 1)
+	assert.Equal(t, "_sym/android/id/"+testMapID+"/mapping.v1.index", objects[0].Key())
+	assert.True(t, objects[0].keyProvesContent, "the key is derived from the mapping it stores")
+}
+
+// An id the caller gave, or one read out of the packaged app, is a build saying what
+// it will report — which is the more specific answer, and the only one for a build
+// old enough that R8 stamps nothing into the app itself.
+func TestBuildAndroidObjectsPrefersAReportedID(t *testing.T) {
+	path := writeMappingFile(t, testMapIDHeader+testAndroidMapping)
+
+	objects, err := buildAndroidObjects(path, "", "deadbeef", false, "")
+	require.NoError(t, err)
+	require.Len(t, objects, 1)
+	assert.Equal(t, "_sym/android/id/deadbeef/mapping.v1.index", objects[0].Key())
+}

cmd/symbols/android_upload.go

@@ -126,15 +126,25 @@ func buildAndroidObjects(path, appVersion, symbolsID string, includeSources bool
 		return nil, err
 	}
 
-	lanes := androidLanes(build)
-	if len(lanes) == 0 {
-		return nil, fmt.Errorf("this build reports no symbols id and no app version, so there is no key a crash could be symbolicated under. Apply the LaunchDarkly Gradle plugin so the shipped app records its symbols id, or re-run with --%s <version>", appVersionFlag)
-	}
-
 	mapping, err := findAndroidMapping(build.Path)
 	if err != nil {
 		return nil, err
 	}
+	if build.SymbolsID == "" {
+		// R8's own id for this mapping, which the shipped app reports on every frame
+		// (see android_mapid.go). Below an id the app stamped, which is a build
+		// saying what it will report and so the more specific answer of the two.
+		if id := androidMapID(mapping); id != "" {
+			build.SymbolsID = id
+			fmt.Printf("Using symbols id %s, as recorded by R8 in the mapping\n", id)
+		}
+	}
+
+	lanes := androidLanes(build)
+	if len(lanes) == 0 {
+		return nil, fmt.Errorf("this mapping records no id of its own and the build reports no app version, so there is no key a crash could be symbolicated under. Re-run with --%s <version>", appVersionFlag)
+	}
+
 	index, err := buildAndroidIndex(mapping)
 	if err != nil {
 		return nil, err

cmd/symbols/apple_upload.go

@@ -54,13 +54,21 @@ func (m appleSymbolMap) label() string {
 // nothing. Source bundles borrow that UUID rather than being keyed by their own
 // contents — sources unreadable on the machine that uploaded first must still be able
 // to overwrite — so those are skipped only when their digest matches what is stored.
-func uploadAppleDSYMs(apiKey, projectID, path, backendURL string, includeSources, skipExisting bool) error {
-	images, err := findDSYMImages(path)
+func uploadAppleDSYMs(apiKey, projectID string, upload appleUpload, backendURL string, includeSources, skipExisting bool) error {
+	images, err := findDSYMImages(upload.Path)
 	if err != nil {
 		return fmt.Errorf("failed to find dSYM files: %w", err)
 	}
 	if len(images) == 0 {
-		return fmt.Errorf("no .dSYM bundles found in %s, is this the correct path?", path)
+		if upload.FromXcode {
+			// Running from a build that produced no dSYM is ordinary — a Debug
+			// build's debug information stays in the binary — and a build phase
+			// that fails the build over it would be a phase every project has to
+			// guard. There is nothing to upload, which is not the same as an error.
+			fmt.Printf("This build produced no dSYM, so there is nothing to upload. Set Debug Information Format to \"DWARF with dSYM File\" for the configurations you ship.\n")
+			return nil
+		}
+		return fmt.Errorf("no .dSYM bundles found in %s, is this the correct path?", upload.Path)
 	}
 
 	maps, err := buildAppleMaps(images, includeSources)

cmd/symbols/apple_xcode.go

@@ -0,0 +1,50 @@
+package symbols
+
+import (
+	"fmt"
+	"os"
+)
+
+// Uploading from inside an Xcode build.
+//
+// The reliable moment to upload a dSYM is the build that produced it, which means
+// a Run Script phase. Xcode runs one with the whole build's settings in its
+// environment, so the phase can be told nothing and still know everything:
+// DWARF_DSYM_FOLDER_PATH is where this build put its dSYMs.
+//
+// Reading it here is what keeps the phase to a single line. Otherwise every
+// project writes the same two pieces of shell — a path that has to stay in step
+// with the project's configuration, and a guard against the configurations that
+// produce no dSYM — and gets to debug them inside a build phase, where the way you
+// find out is a failed build.
+
+// xcodeDSYMFolderEnv is the build setting naming the folder Xcode wrote this
+// build's dSYMs to. It is set for every configuration, including the ones whose
+// debug information format produces no dSYM at all.
+const xcodeDSYMFolderEnv = "DWARF_DSYM_FOLDER_PATH"
+
+// appleUpload is where an Apple upload reads its dSYMs from.
+type appleUpload struct {
+	Path string
+	// FromXcode records that the path came from the surrounding build rather than
+	// from the caller, which is what makes finding no dSYM there ordinary: it is
+	// the answer for a Debug build, and not something to fail over.
+	FromXcode bool
+}
+
+// resolveAppleUpload decides where to read dSYMs from. An explicit --path always
+// wins — a phase that wants to upload something other than what it just built can
+// still say so — and the build environment answers when there was no path to go on.
+func resolveAppleUpload(path string) appleUpload {
+	if path != defaultPath {
+		return appleUpload{Path: path}
+	}
+
+	folder := os.Getenv(xcodeDSYMFolderEnv)
+	if folder == "" {
+		return appleUpload{Path: path}
+	}
+
+	fmt.Printf("Using the dSYMs this Xcode build produced, from %s\n", folder)
+	return appleUpload{Path: folder, FromXcode: true}
+}

cmd/symbols/apple_xcode_test.go

@@ -0,0 +1,55 @@
+package symbols
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The point of reading the build environment: a phase that says nothing at all
+// still uploads what the build it is part of just produced.
+func TestResolveAppleUploadFromXcode(t *testing.T) {
+	t.Setenv(xcodeDSYMFolderEnv, "/dd/Build/Products/Release-iphoneos")
+
+	upload := resolveAppleUpload(defaultPath)
+	assert.Equal(t, "/dd/Build/Products/Release-iphoneos", upload.Path)
+	assert.True(t, upload.FromXcode)
+}
+
+// A phase that names a path means it: uploading a dSYM from somewhere other than
+// the build in progress has to stay possible.
+func TestResolveAppleUploadPrefersAnExplicitPath(t *testing.T) {
+	t.Setenv(xcodeDSYMFolderEnv, "/dd/Build/Products/Release-iphoneos")
+
+	upload := resolveAppleUpload("./archives/MyApp.xcarchive/dSYMs")
+	assert.Equal(t, "./archives/MyApp.xcarchive/dSYMs", upload.Path)
+	assert.False(t, upload.FromXcode)
+}
+
+func TestResolveAppleUploadOutsideXcode(t *testing.T) {
+	t.Setenv(xcodeDSYMFolderEnv, "")
+
+	upload := resolveAppleUpload(defaultPath)
+	assert.Equal(t, defaultPath, upload.Path)
+	assert.False(t, upload.FromXcode)
+}
+
+// Xcode sets the folder for every configuration, including the ones whose debug
+// information stays in the binary. Finding no dSYM there is the answer for a Debug
+// build, and a build phase that failed the build over it would be one every project
+// has to write a guard around.
+func TestUploadAppleDSYMsFromXcodeWithoutADSYM(t *testing.T) {
+	err := uploadAppleDSYMs("", "", appleUpload{Path: t.TempDir(), FromXcode: true}, "", false, false)
+	assert.NoError(t, err)
+}
+
+// Asked for a path with no dSYM under it, though, there is nothing else this could
+// have meant, so it is still reported.
+func TestUploadAppleDSYMsWithoutADSYM(t *testing.T) {
+	dir := t.TempDir()
+
+	err := uploadAppleDSYMs("", "", appleUpload{Path: dir}, "", false, false)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), dir)
+}

cmd/symbols/upload.go

@@ -224,8 +224,11 @@ func runE(client resources.Client) func(cmd *cobra.Command, args []string) error
 		// Apple dSYMs take a dedicated path: they are compiled to per-arch .dsymmap
 		// symbol maps keyed by build UUID, ignoring the version/symbols-id lanes.
 		if symbolType == typeAppleDSYM {
-			fmt.Printf("Starting to upload %s symbols from %s\n", symbolType, path)
-			return uploadAppleDSYMs(viper.GetString(cliflags.AccessTokenFlag), projectResult.ID, path, backendUrl, viper.GetBool(includeSourcesFlag), skipExisting)
+			// A dSYM is best uploaded by the build that produced it, so where to
+			// read one from can come from the build itself. See apple_xcode.go.
+			upload := resolveAppleUpload(path)
+			fmt.Printf("Starting to upload %s symbols from %s\n", symbolType, upload.Path)
+			return uploadAppleDSYMs(viper.GetString(cliflags.AccessTokenFlag), projectResult.ID, upload, backendUrl, viper.GetBool(includeSourcesFlag), skipExisting)
 		}
 
 		// Flutter/Dart symbols take a dedicated path too: each app.<platform>.symbols
@@ -700,10 +703,10 @@ func initFlags(cmd *cobra.Command) {
 	cmd.Flags().String(appVersionFlag, "", fmt.Sprintf("The current version of your deploy. With --type %s this is read from the packaged build when omitted", typeAndroid))
 	_ = viper.BindPFlag(appVersionFlag, cmd.Flags().Lookup(appVersionFlag))
 
-	cmd.Flags().String(symbolsIdFlag, "", fmt.Sprintf("The symbols id (launchdarkly.symbols_id.htlhash) to key uploads by (Symbols Id Lane). If omitted, a *.symbolsid sidecar next to the bundle is used when present, and with --type %s the id the packaged app reports", typeAndroid))
+	cmd.Flags().String(symbolsIdFlag, "", fmt.Sprintf("The symbols id (launchdarkly.symbols_id.htlhash) to key uploads by (Symbols Id Lane). If omitted, a *.symbolsid sidecar next to the bundle is used when present, and with --type %s the id the packaged app reports, or failing that the one R8 recorded in the mapping", typeAndroid))
 	_ = viper.BindPFlag(symbolsIdFlag, cmd.Flags().Lookup(symbolsIdFlag))
 
-	cmd.Flags().String(pathFlag, defaultPath, fmt.Sprintf("Sets the directory of where the symbol files are. With --type %s, run from your project root and the R8 mapping is found for you", typeAndroid))
+	cmd.Flags().String(pathFlag, defaultPath, fmt.Sprintf("Sets the directory of where the symbol files are. With --type %s, run from your project root and the R8 mapping is found for you; with --type %s, an Xcode build phase uploads what it just built", typeAndroid, typeAppleDSYM))
 	_ = viper.BindPFlag(pathFlag, cmd.Flags().Lookup(pathFlag))
 
 	cmd.Flags().String(basePathFlag, "", "An optional base path for the uploaded symbol files")

internal/symbols/r8index/encode.go

@@ -55,6 +55,9 @@ func EncodeFrom(r io.Reader) ([]byte, error) {
 	var b srcbundle.Builder
 	classes := 0
 	sc := newScanner(func(obf string, c *class) {
+		// Add ignores a key it already holds, so a repeated obfuscated name keeps its
+		// first block. Parse keeps the first too (see there), because both encoders
+		// have to produce one index for one mapping.
 		b.Add(classPrefix+obf, encodeClass(c))
 		classes++
 	})

internal/symbols/r8index/parse.go

@@ -72,7 +72,20 @@ func (m *Mapping) Classes() int {
 // check.
 func Parse(data []byte) *Mapping {
 	m := &Mapping{classes: map[string]*class{}}
-	sc := newScanner(func(obf string, c *class) { m.classes[obf] = c })
+	// The first block wins a repeated obfuscated name, which is the one thing
+	// EncodeFrom can do: srcbundle.Builder.Add ignores a key it already holds, and a
+	// class it has already compressed into the bundle cannot be revisited. Plain
+	// assignment here would keep the last instead, so one mapping would encode to two
+	// different indexes depending on which encoder read it — and an index is
+	// addressed by the id of the mapping it was built from.
+	//
+	// A name repeats when mapping files are concatenated: a build with feature splits,
+	// or one that appends a module's mapping to another's.
+	sc := newScanner(func(obf string, c *class) {
+		if _, seen := m.classes[obf]; !seen {
+			m.classes[obf] = c
+		}
+	})
 	sc.scan(data)
 	m.sourceFiles = sc.sourceFiles
 	return m