Application State Management & Archiving Guide

This technical guide covers the mechanisms behind offline application state snapshots, 001-999 slot indexing, and SELinux category preservation in KuyFox.

🏗️ Why Backup in Recovery Mode?

Archiving application test states offline in recovery offers critical technical advantages:

1. Zero Locking (100% Database Integrity): Because the Android OS is not active, SQLite databases and session files (shared_prefs, keva, etc.) are never locked by active background processes. No risk of database corruption.
2. Zero Online Dependencies: Functions purely via recovery Linux shell without requiring active OS root daemons or runtime injection.
3. Ultra-Compact Storage: Archives are compressed directly into /sdcard/KuyFox/databackup/.

⚙️ Core Technical Highlights

1. Bind-Mount Architecture (Preventing Shadowed Files)

In recovery environments, /data/user/0 is often an independent mountpoint or symlink distinct from /data/data. Naive extractions frequently deposit files into shadowed mounts that disappear upon booting into Android.

KuyFox resolves this by establishing an explicit bind-mount:

mount -o bind /data/data /data/user/0

Extractions to either destination land directly in physical storage, ensuring 100% visibility upon Android boot.

2. Deterministic SELinux MLS Context Calculation

Every Android application executes under an isolated SELinux category context, such as: u:object_r:app_data_file:s0:c123,c456

Extracting archives without matching MLS contexts causes permission denied crashes under Enforcing kernels. KuyFox reads the package UID from packages.xml, determines the exact MLS category, and applies chcon deterministically.

3. Native Library Symlink Restoration (lib)

KuyFox inspects the original APK installation directory and recreates the /data/data/<pkg>/lib symlink pointing to the appropriate hardware architecture directory (e.g., /data/app/.../lib/arm64).

📝 Configuration Rules & Aliases (backup_config.cfg)

The backup_config.cfg file allows you to customize menu display aliases and configure directory include/exclude rules.

Configuration Format:

# ALIAS / APP NAME | PACKAGE_NAME | MODE | PATHS
Test App Suite Alpha | com.example.testapp.alpha | INCLUDE | databases, shared_prefs, files/session*
Benchmark QA Client  | com.benchmark.qaclient   | INCLUDE | databases, shared_prefs
Enterprise Demo App  | com.enterprise.demomobile| DEFAULT
Core Auth Client     | com.example.authclient   | EXCLUDE | files/cache, files/temp

Modes Breakdown:

1. INCLUDE Mode (Recommended for Heavy Test Applications):
   • Only archives the specified folders or wildcard patterns (e.g., only databases, shared_prefs, and files/session*).
   • Result: Large applications that normally take 200 MB - 1 GB shrink down to just ~300 KB of pure state data!
   • Backup & restore executes in under a second and prevents BusyBox tar Out-Of-Memory (OOM) recovery crashes.
2. EXCLUDE Mode:
   • Archives all app data, while excluding specific temporary cache directories declared in the paths column.
3. DEFAULT Mode:
   • Standard backup that automatically ignores global garbage folders (cache, code_cache, lib, .msm_cache).

📂 Standard 3-Digit Slot Management (001 - 999)

Archived backups are structured at: /sdcard/KuyFox/databackup/<package_name>/

Directory layout per slot:

/sdcard/KuyFox/databackup/com.example.testapp.alpha/
├── 001/
│   ├── data.tar.gz          # Compressed application data archive
│   ├── profile.env          # Device profile snapshot taken during backup
│   ├── ssaid.txt            # App unique SSAID at the time of backup
│   └── note.txt             # Test session reminder note (e.g., "Baseline Session")
├── 002/
└── 003/

Slot Management Features:

• Auto-Increment: New backups automatically fill the next sequential slot (001, 002, 003, etc.).
• Paginated Browsing: If you manage dozens of test state slots, the list is split into pages with [N] Next and [P] Prev navigation keys.
• Sync & Re-Order Slots: If an intermediate slot is deleted (e.g., deleting 002), the sync option re-indexes remaining folders into contiguous sequence (001, 002).

🔄 Smart Dual-Source Restore

When restoring an application backup:

1. KuyFox Native Backups (profile.env Present):
   • KuyFox detects the device identity snapshot and SSAID bundled with the backup.
   • It prompts whether you wish to restore the device profile & SSAID alongside data.
   • This ensures the application sees the exact same device fingerprint and SSAID as when the test session was saved, providing consistent state reproducibility for regression testing.
2. External Tool Backups (Raw Application Data):
   • If profile.env is absent, KuyFox recognizes it as raw application data.
   • It restores the data archive and fixes permissions directly with zero unnecessary prompts.

🚀 Step-by-Step Usage

How to Backup App State Data:

1. Open the main menu (kuyfox), select [1] Backup & Restore App Data.
2. Choose [1] Backup App Data.
3. Pick the target app from the configured alias list (or type [A] to scan all user apps on the device).
4. Enter an optional reminder note (e.g., Session Alpha Initial Login).
5. Backup completes in less than a second!

How to Restore App State Data:

1. Open [1] Backup & Restore App Data.
2. Choose [2] Restore App Data.
3. Select the target app (displays available backup count).
4. Select the slot number (e.g., 1 for slot 001).
5. Confirm restore. Launch the app after booting into Android — your application session is instantly restored!

💻 CLI Quick Commands

For terminal automation and ADB test scripts:

# Backup app data with a custom session note
kuyfox -ba com.example.testapp.alpha "Session_Alpha_Baseline"

# Restore a specific slot (e.g., slot 001)
kuyfox -ra com.example.testapp.alpha 001

# Restore slot 001 together with its device profile snapshot
kuyfox -ra com.example.testapp.alpha 001 --props

# List all saved test state backups across all applications
kuyfox -la