Fix missing-apostrophe contraction candidate selection

[AsafMah]

Problem

The missing-apostrophe shortcut in Suggest.shouldBeAutoCorrected finds an expected contraction anywhere in the dictionary results, but returns an auto-correction decision for the pre-existing first candidate. For example, youre with higher-ranked Youre or yours and a lower-ranked you're can auto-correct to the distractor rather than the contraction that justified the decision.

Change

• Evaluate the actual existing contraction candidate and promote that transformed entry only when auto-correction is permitted. Keep scores, source dictionaries, raw result order, and typed-word alternatives intact.
• Prefer the existing conventional spelling from COMMON_CONTRACTIONS when available: lower-ranked you're over You're for unshifted input, but retain the map's intentional I'm capitalization and normal sentence-start/manual Shift/CapsLock transformations.
• Bind the contraction shortcut to the selected candidate, not a match elsewhere. Preserve explicit whitelist and dictionary-shortcut priority, and prevent the contraction path from accepting a dictionary shortcut when shortcut auto-correction is disabled.
• Add focused feature documentation and deterministic suggestion-pipeline/space-commit regressions.

Validation

Test-first fixtures on the original production code reproduced the wrong selected candidates (Youre, yours, and others); the final cases pass after the fix. Additional shortcut controls failed before their guard was added.

.\gradlew.bat :app:testStandardDebugUnitTest --tests 'helium314.keyboard.latin.SuggestTest' --tests 'helium314.keyboard.latin.InputLogicTest'

Fresh XML results with Temurin JDK 21 and the existing Android SDK:

• SuggestTest: 33 passed, no failures/errors/skips.
• InputLogicTest: 90 passed, no failures/errors; one unchanged pre-existing ignored Hangul test (insertLetterIntoWordHangulFails).

Coverage includes a contraction beyond the visible strip, higher capitalized rivals, typed alternatives and raw results, capitalization/deduplication, trailing quotes, correction disabled, resumed words, unavailable main dictionaries, known English/French words, already-correct you're, English secondary-language candidates, whitelist/shortcut controls, and synthetic space commits producing I think you're .

The initially attempted testOfflineDebugUnitTest is blocked by the existing test-manifest minSdk 21 / androidx.graphics:graphics-path:1.1.0 minSdk 23 mismatch. No build configuration, dependency, baseline, or ignore was changed.

Scope

This fixes controlled-candidate selection, not dictionary availability or broad capitalization/ranking policy. It does not synthesize absent words, force lowercase when no lowercase candidate exists, change scoring algorithms, modify editor caps/context handling, or address TextExpander behavior. WhatsApp/Discord and the user's device were not reproduced; the integration evidence is deterministic Robolectric execution with injected dictionary results.

Related symptom discussion: #482. This does not claim to resolve or close that broader report.