Migrate On-Device AI Storage

Direct answer

A storage migration is a planned move between two available roots, not the same event as losing a mounted volume or renaming one completed download. Inventory every data class first, define which root owns it, and move only what the product intends to migrate. Copy into a staged destination, verify identity and completeness there, update the authoritative path only after the destination is usable, and retain a recoverable source until the transition is committed. If the process stops halfway, the next launch must determine which copy is authoritative without mixing bytes or deleting user data. Separate model artifacts from transient and user-owned data. A complete model has a fixed identity and can be checked against the evidence available for its revision. A partial download is tied to a transfer state and response range; moving it safely requires preserving the artifact identity and accepted offset or discarding it as model-owned temporary data. Caches can often be regenerated but must be classified before deletion. Indexes or derived outputs may reference a specific model revision and need an explicit rebuild or compatibility policy. Conversations, imported documents, and exports belong to the user and require their own migration guarantee. Do not treat every file under one sandbox path as a homogeneous folder. Choose the destination and mechanism according to ownership. Internal app-specific storage is private to the app and ordinarily follows its package lifecycle. App-specific external storage may have different availability and can disappear with the volume or app removal. A user-selected directory through the Storage Access Framework is a separate permission boundary and may require a URI grant. The user must understand which data moves, whether the old copy is removed, and how access will behave later. Do not silently move personal documents to a new provider or request broad storage permission merely to simplify migration. Plan for temporary double occupancy. A copy-based migration often needs the source and destination to coexist until verification and metadata update complete. Calculate by actual file lengths, destination volume, partial files, and active model retention; do not assume rename across filesystems is atomic or free of temporary storage. If space is insufficient, stop before destructive changes and offer a clear choice. The old root should remain usable until the new root passes checks, unless the product has an explicitly tested in-place strategy with its own recovery guarantees. Use a journaled state machine. Persist migration ID, source root, destination root, artifact revision, data class, expected and observed lengths, digest evidence where available, phase, and last completed item. On restart, inspect both source and destination rather than trusting one boolean. If the source remains complete and the destination is partial, resume copying or remove only the staged candidate. If the destination is verified and the pointer update is pending, complete the switch idempotently. If neither can be proved usable, show repair and preserve user data. Do not update every stored path before files exist at the destination. Verify separately by class. For a model artifact, compare the destination file to the expected revision and run configured integrity and load checks. For partial transfers, either migrate transfer metadata and revalidate the remote representation before resuming, or discard only that partial model data with user-visible disclosure. For indexes, validate that referenced source and model versions remain consistent or rebuild them. For user records, confirm count and readable samples, preserve timestamps and identifiers, and test rollback. A successful file copy does not prove all repository references were updated.

Move an installation while the old root is still mounted

An application changes its model storage policy while the old root remains available. It contains an active model, partial candidate, cache, local index, and conversations. QA also tests interruption recovery before changing persisted paths or removing the source copy.

Decision

Migrate by data ownership class into a staged destination, verify each class, then switch the authoritative pointer while preserving a rollback source.

Expected outcome

The app can recover after interruption without confusing old and new model copies or deleting user-owned records.

Evidence to collect

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

• Source and destination inventory
• Interrupted migration fixtures
• Integrity and rollback result

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

Implementation workflow

1. Inventory roots and ownership. Record source and destination roots, volumes, permissions, and classes: active artifact, partial transfer, cache, index, database, and user content. Identify which component owns every file.
2. Define class-specific rules. For each class state whether to copy, rebuild, retain, or discard, and what proves completion. Keep a database schema transformation separate from a filesystem-location move.
3. Budget destination capacity. Calculate observed file lengths and temporary copies on the target volume, including active-model retention and verification workspace. Do not remove the source if capacity is insufficient or unknown.
4. Write into a staged destination. Preserve identifiers and revisions, journal progress, and avoid changing canonical paths until each required destination item exists and has passed its checks.
5. Verify before pointer commit. Re-read files, validate artifact identity and available integrity evidence, test runtime loading, reconcile index references, then update the root using a tested recoverable switch.
6. Inject interruption and rollback. Stop after copy, verification, and pointer-update phases. Restart and verify idempotent recovery, old model availability, user-data preservation, and cleanup limited to staged app-owned files.

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

Acceptance criteria

• Source and destination roots are named, and artifacts, partial transfers, caches, indexes, databases, and user files are tracked separately.
• The authoritative root changes only after each required destination class passes its checks.
• Interruption cannot leave ambiguous active state or silently lose conversations, imports, or exports.
• Insufficient space stops before destructive deletion and gives the user an explicit recoverable option.

Decision table

Failure patterns to prevent

• Mixing model and user deletion
• Switching paths before verification

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

• Android app-specific storage
• Android Storage Access Framework
• Android migrate a Room database
• RFC 9110: HTTP range requests and validators

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

Frequently asked questions