Migrate Music Libraries

Migrate Music Libraries

Migrate through a platform-neutral manifest. Adapt authentication and APIs to the available source and destination while keeping extraction, matching, ordered writing, verification, and reporting consistent.

Required invariants

1. Treat the source as read-only unless the user explicitly requests source changes.
2. Never place source liked songs directly into the destination's built-in liked/favorite collection. Create a normal destination playlist named <source> 我喜欢（原顺序） or a user-approved equivalent.
3. Preserve the source's canonical item order. Define position 1 explicitly and never infer order from an unstable UI sort.
4. Read every created collection back from the destination. Verify counts and order using stable destination IDs when available.
5. Distinguish complete, partial, and blocked outcomes. Never label unmatched or unverified items as successful.
6. Produce a final migration report and retain no credentials, OTPs, cookies, or tokens in artifacts.

Workflow

1. Discover platforms and capabilities

• Identify source, destination, account scope, requested categories, and whether this is a fresh run, resume, repair, or dry run.
• Prefer official APIs, connectors, exports, or CLIs. Use browser control only when authentication or platform UI is required.
• Ask the user to authenticate in the platform's own visible flow. Do not request passwords or OTP values in chat.
• Preserve a working authenticated session; avoid restarting it during retries unless it is actually invalid.
• Read references/adapter-contract.md before implementing or modifying a platform adapter.
• Build a capability matrix for extraction, creation, batch limits, duplicate behavior, insertion semantics, deletion, and read-back.

2. Extract a canonical source manifest

• Extract all requested categories before destination writes when practical.
• Record collection kind, ownership, source ID, title, description, item count, and source order basis.
• Record each track's source position, source ID, ISRC when available, title, artists, album, duration, version markers, and added timestamp.
• Prefer a reliable per-track added timestamp. Otherwise preserve the authoritative source API order and document that basis.
• Preserve duplicate occurrences in the manifest. Do not silently merge live, remix, acoustic, explicit, instrumental, or region-specific versions.
• Save a resumable checkpoint with no credentials.

3. Match destination catalog items

Match in this order:

1. Stable cross-platform identifiers such as ISRC.
2. Exact normalized title, primary artists, version markers, album, and duration tolerance.
3. Conservative fuzzy matching with a confidence score and explicit ambiguity handling.

• Prefer already matched destination items when repairing order to avoid search drift.
• Never choose an ambiguous candidate solely because it is the first search result.
• Record unmatched, unavailable, ambiguous, duplicate-suppressed, and substituted items separately.
• Keep the matched sequence in source-position order.

4. Create destination structures

• Recreate owned playlists as owned playlists.
• Copy followed/saved playlists into normal destination playlists when direct following is unavailable; label copied collections clearly.
• Save albums through the destination's album-favorite feature when supported. Otherwise create a clearly labeled fallback playlist.
• Follow artists only after confirming a singer/artist entity match; do not treat ordinary user accounts as artists.
• Resolve name conflicts idempotently: reuse a checkpointed destination collection or create a uniquely labeled replacement. Do not create duplicates on resume.

5. Rebuild source liked songs as an independent playlist

• Create <source> 我喜欢（原顺序）; never mutate the destination's built-in liked collection unless the user explicitly overrides this invariant.
• Use the matched source sequence directly as the desired final order.
• Read references/order-preservation.md before any ordered write.
• Determine whether each destination batch is appended or prepended and whether the API reverses items inside a batch. Probe with disposable items when documentation is insufficient.
• Run scripts/plan_order_batches.py to derive exact write batches. Submit the returned batches without flattening or re-chunking them.
• Create a new replacement playlist when an existing playlist has hidden/custom weights that cannot be reset reliably.
• Read the complete playlist back and compare every position. A correct first page is not sufficient proof.

6. Verify and repair

• Verify destination collection count, stable item IDs, duplicate behavior, and item order.
• If IDs differ because the destination substituted an equivalent release, compare title, artists, version markers, duration, and neighboring source positions; record the substitution.
• If a batch is reversed or misplaced, infer actual insertion behavior from the read-back, regenerate batches, and write a fresh replacement rather than repeatedly shuffling an unreliable collection.
• Re-run only failed or unverified actions from the checkpoint.
• Keep temporary probe collections clearly named and remove them after safe verification when permitted.

7. Report and hand off

• Read references/report-schema.md.
• Build the normalized result JSON and run scripts/build_migration_report.py.
• Include source and destination, requested scope, per-category totals, liked-playlist name and ID, source order basis, full order-verification result, unmatched items, substitutions, duplicate handling, follow failures, and manual cleanup.
• State the exact playlist the user should keep when test or superseded playlists exist.
• Keep claims evidence-based: added, read_back, and order_verified are separate facts.

Safety and recovery

• Obtain confirmation at action time for destructive cleanup of nontrivial user collections.
• Do not overwrite or delete an existing destination collection without a checkpoint and clear authorization.
• Avoid exposing private library data in logs beyond what is needed for the migration report.
• Rate-limit requests, retry transient failures with bounded backoff, and stop before platform enforcement risk.
• When authentication expires, preserve extracted manifests and action checkpoints so the user only reauthenticates the affected platform.

Resources

• references/adapter-contract.md: canonical manifest and adapter capability contract.
• references/order-preservation.md: ordered batch-write and verification rules.
• references/report-schema.md: normalized migration-result schema.
• scripts/plan_order_batches.py: deterministic ordered-batch planner and simulator.
• scripts/build_migration_report.py: Markdown completion-report generator.