RKNnoVPN/docs/architecture-reset/CODE_MIGRATION_PLAN.md

RKNnoVPN Local-First Code Migration Plan

This plan is the guardrail for the daemon-to-local-first migration. The goal is to keep the existing UI and user-visible features while changing ownership and execution boundaries:

• APK owns profile, settings, subscriptions, and update cache.
• APK performs subscription and release network requests directly.
• Root/module runtime is only an executor for apply/start/stop/restart/reset, logs, and module staging.
• Old daemon IPC compatibility is not part of the active APK or runtime path.

Non-Breaking Feature Contract

The migration must preserve:

• direct link import;
• QR/import sheet;
• subscriptions;
• app list and package picker;
• routing modes;
• bypassRussia;
• DNS settings;
• always-direct apps;
• sharing/tethering settings;
• update check and download;
• start, stop, restart, reset;
• logs;
• node tests.

Backend ownership changes are expected:

• daemon profile get/apply/import calls become APK-local profile operations: AppProfileStore is dumb persistence, while ProfileRepository is the only owner/publisher of observable profile state;
• daemon subscription preview/refresh becomes APK-side subscription fetching and parsing through ApkSubscriptionClient;
• daemon update check/download becomes APK-side Forgejo release fetching through ApkReleaseUpdater;
• daemon backend controls become explicit root CLI commands through RuntimeController;
• daemon logs become RuntimeController.logs.

Phase 1: APK Boot Without Runtime

Required code:

• app/app/src/main/AndroidManifest.xml
• app/app/src/main/kotlin/com/rknnovpn/panel/profile/AppProfile.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/storage/AppProfileStore.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/storage/FileAppProfileStore.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/repository/ProfileRepository.kt

Acceptance:

• APK opens with no module installed.
• APK profile is created and stored under app-private storage.
• Profile editing and imports do not require root or runtime compatibility.
• AppProfileStore remains a persistence-only contract: no StateFlow, no long-lived profile, warning, or error properties, and no UI/runtime state ownership.
• ProfileRepository is the single owner of profile-related observable state: profile, freshness/loading, error, and notice flows are published from the repository, not from storage.

Phase 2: Remove Active IPC Compatibility

Forbidden in active code paths:

• compat.check
• ipc.contract
• GeneratedDaemonContract
• requireCompatible
• compatibilityCache
• repair cooldowns
• stable invalid response recovery
• automatic module repair after parse errors
• daemon-owned profile as APK startup dependency

Acceptance:

• Forbidden strings are absent from app, runtime, module, tools, and CI scripts except for the local-first checker that defines the forbidden patterns.

Phase 3: APK-Side Subscriptions

Required code:

• app/app/src/main/kotlin/com/rknnovpn/panel/subscription/ApkSubscriptionClient.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/subscription/SubscriptionRepository.kt

Acceptance:

• APK downloads subscription URLs itself.
• APK parses payloads with LinkParser.
• APK saves imported nodes into AppProfileStore.
• Runtime/module absence does not block preview, commit, refresh, or refresh all.

Phase 4: APK-Side Updates

Required code:

• app/app/src/main/kotlin/com/rknnovpn/panel/update/ApkReleaseUpdater.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/update/UpdateRepository.kt
• settings update flow.

Acceptance:

• APK checks the latest release in the project Forgejo itself.
• APK downloads module.zip, panel.apk, and SHA256SUMS.
• APK verifies SHA256 before exposing downloaded update paths.
• Runtime is only needed to stage/install the root/module part.

Phase 5: Root CLI Runtime

Required code:

• app/app/src/main/kotlin/com/rknnovpn/panel/runtime/RuntimeController.kt
• app/app/src/main/kotlin/com/rknnovpn/panel/root/RootCommandExecutor.kt
• runtime/cmd/rknnovpn-runtime/main.go

Required commands:

• rknnovpn-runtime version
• rknnovpn-runtime status
• rknnovpn-runtime apply <profile.json>
• rknnovpn-runtime start
• rknnovpn-runtime stop
• rknnovpn-runtime restart
• rknnovpn-runtime reset
• rknnovpn-runtime logs
• rknnovpn-runtime stage-module <module.zip>

Runtime actions are enabled only when:

• runtime release version equals APK BuildConfig.VERSION_NAME;
• runtime version code equals APK BuildConfig.VERSION_CODE;
• runtime wireEpoch equals 1.

If runtime is missing, old, root-denied, or returns malformed JSON, APK local features remain usable and runtime controls fail as disabled/unavailable actions.

Phase 6: Runtime Profile Renderer

Required code:

• app/app/src/main/kotlin/com/rknnovpn/panel/runtime/RuntimeProfileRenderer.kt

Acceptance:

• APK profile is converted into runtime config only during apply/start.
• APK boot does not depend on runtime config schema.
• Routing, DNS, sharing, always-direct apps, app groups, bypassRussia, and active node selection are carried into the runtime projection.
• Runtime projection does not carry APK-only subscription registry, share-link fallback data, or stale node metadata.

Phase 7: Tests And Validation

Expected coverage areas:

• APK profile file store behavior.
• Profile repository local-first behavior.
• Profile store/repository boundary: store returns operation results only, repository publishes profile/error/notice state.
• Subscription payload parsing and repository behavior.
• Release metadata/checksum parsing and update repository behavior.
• Runtime availability/protocol handling for missing, mismatched, and malformed runtime responses.
• Runtime profile rendering for routing, DNS, sharing, always-direct, app groups, and stale-node filtering.

Required validation commands:

./gradlew :app:assembleDebug
./gradlew :app:testDebugUnitTest
scripts/ci/check_local_first_runtime.sh
scripts/ci/check_apk_privacy.sh
rg "compat\\.check|ipc\\.contract|GeneratedDaemonContract|requireCompatible|compatibilityCache|Repair cooldown|stableInvalidResponse" app runtime module .forgejo

Release APK privacy validation requires a built APK:

scripts/ci/check_release_apk_privacy.sh path/to/app.apk