Migrate Local Models Across Android Runtime Versions

Direct answer

Treat a runtime upgrade as a compatibility change that must be tested against the exact model artifact and user task. A package version by itself does not prove that an existing model file, tokenizer, compiled cache, conversation state, or native backend behaves the same under the new runtime. Google’s LiteRT-LM Kotlin getting-started documentation describes the current Android/JVM API surface, initialization and explicit resource close behavior; it is an integration reference, not a compatibility matrix for every artifact across runtime revisions. That boundary means an app should record old and new runtime identities, model revision and format, Android build, ABI, backend request, prompt template, decoding settings and any derived cache version before planning migration. Keep the original working artifact and its matching runtime path until the candidate has passed validation. If replacing the runtime also replaces the only copy of a model or compiled cache, a failed update can turn a recoverable migration into an unavailable feature. A safer release plan downloads or retains a candidate separately, validates its identity, opens it with the new runtime, runs a representative task, checks output properties, cancellation and a second request, and only then changes the active pointer. The exact transaction depends on app architecture and storage; do not claim that the runtime performs migration automatically unless the selected API explicitly documents that behavior. Model artifact, tokenizer, prompt template, runtime, native libraries and cached representations are separate inputs. Changing one may require invalidating a derived cache even if the model filename did not change. Preserve user-authored conversation history separately from derived inference state. If a conversation is resumed under a different tokenizer or prompt template, mark the provenance and test whether the old representation is supported; never silently rewrite or discard the user record. For structured outputs, run schema and safety fixtures again. For a translation feature, use an authored bilingual fixture set and reviewer rubric; a few fluent outputs do not establish accuracy. If no raw benchmark data exists, do not attach speed, memory, thermal or device-support numbers to the migration. Cove’s fact ledger records that the current Gemma E2B SHA-256 field is empty, so do not describe the current artifact as hash-verified. A migration manifest should distinguish known file identity from a digest that is absent, and the application should not claim integrity verification when it skipped the configured digest step. Test failures at each stage: dependency resolution, APK packaging, engine creation, old artifact open, candidate artifact open, output acceptance, cache invalidation, cancellation, crash/process restoration and rollback. Keep the previous runtime available when the app architecture permits and document storage implications rather than deleting the old copy before the candidate is known good. Include both upgrade and downgrade paths only if the application actually supports rollback. A downgrade may require restoring the old artifact and cache; it is not merely changing a Gradle dependency. If rollback is not supported, say so and provide a repair or re-download workflow. For durable background migration, persist only reconstructable task state, never a native engine handle. Explain to the user whether the app is preparing a model, verifying an artifact, or ready for the new runtime. A successful build proves compilation and packaging, not runtime compatibility. A successful engine initialization proves that one combination opened, not that every workflow survived migration. A task passing proves only the tested artifact, runtime, configuration and fixture. The engineering record should contain artifact source and revision, actual byte length, configured digest state, old/new runtime dependency, app build and ABI, migration procedure, cache policy, test fixtures, failures and rollback results. This allows the next maintainer to separate a real compatibility decision from a version-label assumption. Workflow: freeze the baseline; inventory durable and derived state; prepare a candidate without overwriting the last usable copy; run exact-artifact load and task checks; exercise interruption and rollback; then publish the narrow result. This guide is a migration method, not evidence that Cove currently supports a runtime upgrade or a public model migration path.

A runtime dependency changes before the next Android release

A team updates a local inference library to address a build requirement. Its currently installed model file and cached session were created with the earlier runtime. The team has not yet established whether the new runtime opens the same file or preserves the same product task behavior.

Decision

Keep a reproducible old-runtime baseline, test the candidate runtime with the exact model and fixtures, invalidate only identified derived state, and preserve a rollback or honest repair path.

Expected outcome

A reviewer can state which runtime/artifact/task combination passed and which migration cases remain unknown without converting an SDK upgrade into a compatibility promise.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Old and new runtime manifests
• Artifact and derived-cache identities
• Upgrade, rollback, and task outcomes

A completed byte stream is not enough. Final placement, integrity, runtime load, and recovery must also pass.

Implementation workflow

1. Freeze the baseline tuple. Record app commit and variant, resolved runtime dependency, artifact revision and format, ABI, backend request, prompt template, decoding settings, cache version, and a fixed user-task fixture.
2. Inventory persistent and derived state. Separate the model file, tokenizer, user history, prompt/schema versions, temporary download, compiled or runtime cache, and UI state; identify the owner and safe deletion rule for each.
3. Prepare a candidate without destructive replacement. Keep the old usable artifact and runtime path while the new package and exact candidate artifact are tested. If storage cannot hold both, disclose that constraint and require an explicit recovery choice.
4. Run migration acceptance fixtures. Test engine initialization, artifact open, representative output properties, schema and safety checks, cancellation, process recreation, and a second request. Preserve every failure and configuration label.
5. Exercise commit and rollback. Switch the active model/runtime only after acceptance, then test interruption and rollback or repair. Update persistent provenance atomically enough for the app architecture and never silently rewrite user-authored records.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• Old and candidate runtime, artifact, ABI, app build, backend request and cache identities are recorded for every result.
• The prior usable artifact remains available until candidate open and representative-task checks pass, unless a user-approved storage constraint is documented.
• User-created history is preserved separately from derived cache, and cache invalidation has an explicit rule and test.
• Published claims are limited to tested runtime/artifact/task combinations; no general compatibility or performance result is inferred.

Decision table

Failure patterns to prevent

• Reusing compiled caches blindly
• Replacing the only working artifact first

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Google AI Edge LiteRT-LM Kotlin getting started
• Android Developers — Processes and app lifecycle
• Android Developers — Test app backup and restore
• Cove model artifact identity configuration

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions