docs product MAP_29_PERFORMANCE_CONTRACT

MAP-29 performance and compatibility contract

Version: 2026-10-26. Written before any MAP-29 measurement. This contract does not authorize a national rollout, a commercial SLA, physical battery claims or a release. A result on an emulator is a proxy and is labelled as such.

Scenarios

• S1 static release candidate: :app:assembleRelease from the current head with the pinned engine candidate, universal APK; no test maps embedded.
• S2 reference emulator: owned emulator-5554, API 35, 16 KB kernel pages, x86_64 host with Android ARM64 translation and software/native GLES path; debug app; admitted regional Brazil_Parana_East.mwm, World and WorldCoasts in app-private files; airplane/offline after installation; no external provider.
• S3 low-resource/other-ABI profile: reported separately only if it actually executes. An API 30/API 35 profile is never recorded as API 26 evidence. A physical 4 KB arm64 profile is recorded as an informational reference, not as 16 KB or battery proof.
• S4 routing/planning: one 1.6 km real native route plus the MAP-27 planner bounded calls; cancellation and stale-callback checks.
• S5 measured UI: the MAP-28 real flow (vehicle → map → plan → alternative → failure → replan → save → reopen), functional proof; its UI timings are not a frame-pacing budget.

Metrics and budgets

Mandatory for this local gate:

1. Release universal APK ≤ 80 MiB (existing ceiling, unchanged). Report bytes and MiB; download/installed/Play splits are not claimed.
2. Only the supported ARM ABIs are advertised and packaged. Every packaged liborganicmaps.so LOAD segment is 0x4000-aligned; zipalign -c -P 16 4 passes. Static ELF verification is separate from runtime execution.
3. Engine initialization to native readiness on S2: ≤ 15,000 ms per sample (3 samples).
4. One real 1.6 km route build through the pinned engine on S2: ≤ 5,000 ms per sample (3 samples).
5. Total process PSS after native map initialization on S2: ≤ 512 MiB per sample (3 samples). This is an emulator proxy, not a low-end physical memory budget.
6. Cancellation: a cancelled native route publishes no result to the cancelled owner and cancellation returns in ≤ 1,000 ms; stale callback generation is ignored.
7. App cold launch am start -W on S2: ≤ 4,000 ms per sample (3 samples), debug build.

Measured/informational or owed, never inferred as PASS:

• Frame time/pacing and jank of Compose and the native SurfaceView: OWED. The MAP-14 historical 21–27 FPS profile and SurfaceFlinger queue figure are context, not a current budget or acceptance for this AAR/ABI/driver.
• Native/Java heap growth over repeated navigation/rotation/process death: only the PSS sample above is measured; a leak-freedom claim is OWED.
• Offline network bytes and Range/304/retry behavior: MAP-24 recorded 9 → 9 requests for its regional journey; this MAP-29 run does not re-measure current-head network bytes.
• PostGIS density/concurrency, cursor pagination, EXPLAIN and job backpressure: OWED. No SQL/job/schema change is made by MAP-27/28/29 and no disposable PostGIS service is used in this run.
• API 26 runtime: OWED; current profiles are API 30/API 35 only.
• ARMv7 JNI runtime: OWED unless the ARMv7 profile actually completes; static packaging is not runtime proof.
• GPS/CPU/battery in navigation: OWED; emulator power is not physical autonomy.
• National/dense-region capacity, staging CDN behavior, commercial SLA, release certification: OWED.

Protocol

• Record exact commit, build variant, APK/AAR SHA-256, toolchain, emulator image, kernel page size, ABI actually executed, map file hashes, commands, repetitions and host load.
• Do not change a budget after seeing a failure. A failed budget remains failed; a known external obligation is PARTIAL/OWED, not a waiver.
• Use --max-workers=1 for Gradle, do not run connectedCheck against all devices, and select the owned emulator serial explicitly.
• Sanitize raw output; no route traces, precise GPS, account keys, tokens or private data in Git. Synthetic charging fixtures remain labelled as synthetic.
• Gate result: PERFORMANCE_GATE PASS only when every mandatory item above has compatible proof. Otherwise PERFORMANCE_GATE PARTIAL, listing each owed item and its owner/condition.