On-Device Model Update and Rollback

Direct answer

A safe model update is a candidate-and-commit transaction, not an overwrite of the only working file. Keep the active artifact addressable while downloading a candidate into separate storage. Bind both files to explicit identities, verify the candidate using the evidence actually available, ask the intended runtime to load it without destroying the current session, and switch the active reference only after release acceptance passes. If any stage fails, leave the prior artifact selected and make retry or rollback visible. A successful transfer is not enough to commit an update: file presence, digest verification, runtime initialization, and task acceptance answer different questions. The project’s ModelDownloader writes to a temporary file and attempts to rename it to the configured target after optional SHA-256 verification. The E2B digest is currently empty, while E4B size and digest are documented as placeholders. ModelManager also documents a selected variant and an engine-release path around variant changes. This code is valuable evidence of current behavior, but it does not prove crash-safe atomic replacement on every filesystem, a verified digest for current artifacts, or a published update channel. This guide therefore describes a release procedure, not a claim that Cove has shipped an updater. Model replacement has multiple identities: source repository and immutable revision, converted artifact, runtime package, application build, prompt or tokenizer assets, and derived user data. Record which inputs changed. If a runtime or prompt changes but the model bytes do not, do not mislabel it as a model-file update. If the candidate is incompatible with cached derived data, invalidate or rebuild only the derived representation according to its own schema. Preserve conversations, notes, and user media unless the user separately chooses deletion. A rollback should restore a known-good combination, not merely move a filename pointer while leaving incompatible metadata active. Design the commit boundary explicitly. Before candidate validation, active inference may continue on the old artifact only if the runtime can safely keep it open. Otherwise explain the maintenance window and block new work. The switch step should have one owner, exclude competing variant changes, and persist enough state to recover after process death: active artifact identity, candidate identity, phase, and last durable verification result. On restart, reconcile that record with actual files; never trust a stale “ready” flag by itself. A half-written candidate must not become active merely because its target filename exists. The rollback trigger should be based on explicit evidence: candidate file absent, expected metadata mismatch, runtime load failure, representative task rejection, or a failure during commit. Define whether the previous artifact remains on disk, how much storage a dual-copy update requires, and what action occurs if there is not enough safe space. Do not automatically delete user data or the last working model to create headroom. If rollback cannot restore the old artifact, expose a repair state and offer a documented re-download or support action instead of looping through load attempts. Test fault points before trusting the transaction: interrupt during download, after the candidate is complete but before verification, during runtime load, immediately before active-pointer update, after pointer update but before state persistence, and during cleanup of the old artifact. Each restart should either select the prior known-good artifact or finish a verified commit; it should never guess. Use deterministic fake files and injected failures before testing the actual runtime. Record exact app, artifact, and runtime revisions so a successful rollback is reproducible. ### Procedure 1. Define a versioned update manifest with active and candidate identities, format, source revision, expected metadata, runtime requirement, and any derived-data migration rule. Mark unknown size or digest fields as unknown rather than filling plausible values. 2. Download the candidate into a separate revision-bound temporary path. Verify response identity and all available trusted integrity data; do not modify the active artifact during this phase. 3. Load the candidate in an isolated validation step. Run package/runtime checks and one fixed, non-sensitive task whose acceptance properties are written in advance. Keep the old artifact selected until all checks pass. 4. Commit through one serialized owner. Persist a recoverable phase record, switch an atomic manifest or pointer only after validation, then reopen the selected artifact and confirm the resulting state. 5. Inject interruption at every boundary. Verify restart reconciliation, user-data preservation, cleanup consent, and rollback to the exact prior identity before removing the old file. ### Acceptance criteria - The active artifact remains recoverable until the candidate passes identity, integrity, runtime-load, and task checks. - Process interruption at each commit boundary results in either the prior known-good selection or a fully verified candidate, never an ambiguous half-state. - Rollback selects a recorded artifact/runtime combination and preserves conversations and unrelated user files. - Storage shortage and failed rollback have an explicit user-facing recovery path; no automatic cleanup deletes user content or the last working model. ### Comparison | Update design | Benefit | Risk or boundary | |---|---|---| | In-place overwrite | Uses less temporary space | A failed transfer or load can destroy the only working copy | | Candidate plus active copy | Preserves rollback while validating | Requires storage planning and explicit cleanup policy | | Pointer/manifest commit | Separates selection from bytes | Still needs durable state and restart reconciliation | ### FAQ **Can the app replace the model as soon as download reaches 100%?** No. Transfer completion does not establish trusted identity, successful integrity verification, runtime compatibility, or user-task acceptance. Keep the candidate inactive until those steps have explicit results. **Does renaming a file make the update transaction crash-safe?** Not by itself. Rename semantics depend on path and filesystem conditions, and the application still needs to persist which artifact is active and reconcile state after interruption. Test the actual storage path. **How long should the old model remain?** Until the new candidate has passed the release checks and rollback policy no longer requires it. If storage cannot hold both, disclose the risk and design a recovery route; do not silently delete user data to make room. **Should conversations be migrated during a model rollback?** Keep conversation data separate from model files. Restore or invalidate only versioned derived state with a documented schema rule, and preserve user-authored records unless deletion is a separate, explicit choice.

A candidate model fails after download but before activation

A user already has a usable local model and requests an update. The candidate file arrives, but runtime initialization or a fixed acceptance task may fail. The app must not leave the user with a filename that looks installed while the previous working model has already been deleted.

Decision

Keep active and candidate artifacts separate, validate the exact candidate with the intended runtime, and move the active reference only at a recoverable commit point.

Expected outcome

A failure leaves the prior known-good identity selected, preserves user records, and exposes a bounded repair action rather than an automatic retry loop.

Evidence to collect

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

• Old and new manifests
• Switch transaction
• Rollback test

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

Implementation workflow

1. Record both artifact identities. Persist the active and candidate source revisions, formats, runtime requirements, integrity metadata, and update phase. Do not treat a family name or filename as a complete identity.
2. Download without mutating the active file. Write the candidate to a separate revision-bound path, validate response metadata, and preserve the current artifact. If space is insufficient, stop and explain the choices before deleting anything.
3. Validate candidate and task behavior. Check file identity and available integrity data, load it using the intended runtime, and run a fixed task with declared acceptance properties. Keep user content out of test records.
4. Commit through a serialized state owner. Prevent concurrent update or variant-switch operations. Persist the commit phase and update the active manifest only after candidate acceptance; reopen the selected identity to confirm recovery.
5. Exercise interruption and rollback. Inject process death before and after verification, pointer change, and cleanup. Confirm each restart resolves to the previous working identity or a fully accepted new one.

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

Acceptance criteria

• No candidate becomes active before its identity, available integrity checks, runtime load, and task acceptance pass.
• Every interruption point resolves to a known active identity after restart.
• Rollback preserves user records and identifies the exact previous artifact and runtime combination.
• Insufficient space and failed rollback have explicit recovery copy and do not trigger destructive cleanup.

Decision table

Failure patterns to prevent

• Replacing before verification
• No artifact version in user state

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

• AndroidX AtomicFile API reference
• LiteRT-LM Kotlin API lifecycle guide
• Android Activity lifecycle

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

Frequently asked questions