ci: report binary compatibility against the last published release

[nickolas-dimitrakas]

Summary

Adds a CI job, Binary Compatibility, that compares the release artifacts of android-core and android-kit-base against the most recent version published to Maven Central and fails on any binary- or source-incompatible change.

• scripts/api_compat_report.py builds both release AARs, extracts classes.jar from each, downloads the same artifact at the latest published version (verified against its published checksum), and runs japicmp 0.26.2 (pinned by version and SHA-256). Additions are reported but do not fail the run.
• android-core ships R8-minified, so R8-renamed symbols are excluded before the verdict is computed. Classes whose simple name, or any nested-class segment of it, is R8-shaped (a, b1, MParticle$a, Outer$1) are dropped from both jars. Members are filtered only on evidence: the release build's R8 mapping file identifies the classes that a keep rule names only partially (today ConfigManager, MParticleIdentityClientImpl and the Kotlin access$ synthetics of InternalListenerManager), and only inside those classes are R8-shaped member names ignored. Every member of a fully kept class is compared by its real name, so removing a short-named public field such as MPUtility.AdIdInfo.id is reported.
• scripts/test_api_compat_report.py (standard-library unittest) covers the class filter, the mapping parser and the report evaluation; CI runs it before the comparison.
• HTML and XML reports are uploaded as the api-compat-reports workflow artifact; a one-line result goes to the job summary.
• Documents the script and job in AGENTS.md.

The job is deliberately not in the required-check set. It runs on every pull request and on pushes to main.

Why

./gradlew apiCheck (#843) guards the compiled surface before R8. What consumers link against is the post-R8 artifact, in which only the classes android-core/proguard.pro keeps survive under their own names. This job is the check on the artifact that ships, and it also sees throws clauses and nullability annotations. japicmp runs with --ignore-missing-classes and no external classpath, so changes that only manifest through unresolved external supertypes are left to the compile-time dump.

Verification

• Unit tests: 8 passing.
• Local release AARs against 6.1.2 from Maven Central: android-core 115 named classes compared (180 R8-renamed dropped on each side), android-kit-base 44 compared; no changes.
• android-core against 6.0.0: compatible; five classes with additions only. The R8-renamed members that a name-shape filter would have mis-reported are correctly ignored.
• Synthetic check: removing AttributionError from the local AAR reports CLASS_REMOVED and each of its members, exit code 2.

🤖 Generated with Claude Code

[github-actions]

📦 SDK Size Impact Report

What the SDK adds to a minified release APK.

Measured against an empty baseline app. Unlike the Rokt kit, android-core ships no Compose and no resources, so there is nothing here that a host app would already provide.

mParticle Core SDK

Metric	Target branch	This PR	Change
APK size	119.78 KB	119.78 KB	-1 bytes
Download size	117.60 KB	117.60 KB	-1 bytes
Dex bytes	213.75 KB	213.75 KB	0 bytes

➡️ SDK size impact change is minimal.

Raw measurements

Target branch:

{"baseline_dex_bytes": 0, "baseline_download_bytes": 2513, "baseline_install_bytes": 7528, "core_dex_bytes": 218884, "core_download_bytes": 122935, "core_install_bytes": 130187}

This PR:

{"baseline_dex_bytes": 0, "baseline_download_bytes": 2513, "baseline_install_bytes": 7529, "core_dex_bytes": 218884, "core_download_bytes": 122934, "core_install_bytes": 130187}

_{Measured 885020c merged into 49124e4}

[cursor]

PR Summary

Low Risk
CI and developer tooling changes only. No production runtime SDK code is modified.

Overview
Adds a Binary Compatibility CI job and Python utility (scripts/api_compat_report.py) to verify post-R8 release AARs for android-core and android-kit-base against the latest published version on Maven Central using japicmp.

The script downloads the baseline release artifacts, extracts classes, filters out unstable R8-obfuscated classes and members using release mapping files, and flags binary- or source-incompatible changes.

Results are uploaded as workflow artifacts and posted as sticky PR comments or job summaries. Includes comprehensive unit tests in scripts/test_api_compat_report.py and documentation in AGENTS.md.

^{Reviewed by Cursor Bugbot for commit 885020c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 32bbfbf. Configure here.}

[github-actions]

Binary compatibility

• ✅ android-core is compatible with 6.1.5 (115 classes compared, 1 with additions only).
• ✅ android-kit-base is compatible with 6.1.5 (44 classes compared, 0 with additions only).

Compares the release AAR against the same artifact at the last version published to Maven Central; R8-renamed classes and members are excluded (see the script docstring). Full japicmp HTML/XML reports are attached as the api-compat-reports workflow artifact. This check is not in the required-check set yet, so a red result here does not block merging.