rn-update 1.0.0

package/android/src/main/java/cn/reactnative/modules/update/NativeUpdateCore.java

@@ -0,0 +1,43 @@
+/**
+ * [INPUT]: 依赖 System.loadLibrary 加载的 librnupdate 与 getSupportedDiffVersion JNI 符号
+ * [OUTPUT]: 对内提供幂等 ensureLoaded 和原生 supportedDiffVersion 能力查询
+ * [POS]: Android 共享原生库加载门，被状态、下载和冷启动决策桥共同复用
+ */
+package cn.reactnative.modules.update;
+
+final class NativeUpdateCore {
+    private static boolean loaded = false;
+
+    private NativeUpdateCore() {
+    }
+
+    static synchronized void ensureLoaded() {
+        if (loaded) {
+            return;
+        }
+
+        try {
+            System.loadLibrary("rnupdate");
+        } catch (UnsatisfiedLinkError error) {
+            UnsatisfiedLinkError wrapped = new UnsatisfiedLinkError(
+                "Failed to load rnupdate native library. Original error: "
+                    + error.getMessage());
+            wrapped.initCause(error);
+            throw wrapped;
+        }
+
+        loaded = true;
+    }
+
+    /**
+     * 原生 patch 内核可消费的 diff 轨道版本(2 = hdiffv2 轨道)。
+     * 经 getConstants 暴露给 JS,再随 checkUpdate 以 diffV 上报,
+     * 服务端按能力门控下发。
+     */
+    static int supportedDiffVersion() {
+        ensureLoaded();
+        return getSupportedDiffVersion();
+    }
+
+    private static native int getSupportedDiffVersion();
+}

package/android/src/main/java/cn/reactnative/modules/update/NativeUpdateFlow.java

@@ -0,0 +1,30 @@
+/**
+ * [INPUT]: 依赖 NativeUpdateCore 与 cpp/update_flow_core 的字符串 JSON JNI 实现
+ * [OUTPUT]: 对内提供检查请求构造、端点排序和响应决策三个无 IO 原生入口
+ * [POS]: NativeCheckOrchestrator 与跨平台纯决策核心之间的窄桥，不解释或持久化 JSON
+ */
+package cn.reactnative.modules.update;
+
+/**
+ * JNI bindings to the shared update-flow decision layer
+ * (cpp/update_flow_core). String-in/string-out JSON on purpose — it matches
+ * the decision layer's own boundary and keeps this surface trivially stable.
+ * A null return means the input did not parse; callers skip the check round.
+ */
+final class NativeUpdateFlow {
+    static {
+        NativeUpdateCore.ensureLoaded();
+    }
+
+    private NativeUpdateFlow() {
+    }
+
+    static native String buildCheckRequestBody(String inputJson);
+
+    static native String orderEndpointCandidates(String endpointsJson, double randomSample);
+
+    static native boolean isValidCheckResponse(String responseText);
+
+    static native String handleCheckResponse(
+        String responseText, String identityJson, String afterDownload);
+}

package/android/src/main/java/cn/reactnative/modules/update/PackageInstallerStatusReceiver.java

@@ -0,0 +1,17 @@
+/**
+ * [INPUT]: 依赖 Android BroadcastReceiver 生命周期与 manifest 注册的安装回执 Intent
+ * [OUTPUT]: 把 PackageInstaller 会话状态广播转交给 ApkInstaller.handleStatus 归类
+ * [POS]: Android APK 安装回执的入口 Receiver，无自身状态
+ */
+package cn.reactnative.modules.update;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+
+public final class PackageInstallerStatusReceiver extends BroadcastReceiver {
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        ApkInstaller.handleStatus(context, intent);
+    }
+}

package/android/src/main/java/cn/reactnative/modules/update/PatchFailedException.java

@@ -0,0 +1,21 @@
+/**
+ * [INPUT]: 依赖 IOException 与 DownloadTask 对下载阶段/补丁阶段的失败分类
+ * [OUTPUT]: 对内提供 PatchFailedException，标记解包、hdiff 或资源复制失败
+ * [POS]: Android 失败语义边界，使 UpdateModuleImpl 和客户端遥测不会把补丁质量问题归入网络噪声
+ */
+package cn.reactnative.modules.update;
+
+import java.io.IOException;
+
+/**
+ * A download task failure that happened after the artifact was fully
+ * downloaded — unzip, hdiff apply, or bundled-resource copy (including the
+ * copiesCrc content verification). UpdateModuleImpl rejects these with
+ * PATCH_FAILED instead of DOWNLOAD_FAILED so the JS layer and server-side
+ * telemetry can separate patch health from network health.
+ */
+class PatchFailedException extends IOException {
+    PatchFailedException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

package/android/src/main/java/cn/reactnative/modules/update/ReactReloadManager.java

@@ -0,0 +1,274 @@
+/**
+ * [INPUT]: 依赖 UpdateContext、ReactApplicationContext 与 ReactHost/ReactInstanceManager/ReactActivity 的跨版本反射能力
+ * [OUTPUT]: 对内提供 restartApp，在切换可选版本后按新架构 Host、旧架构 InstanceManager、Activity 重建顺序重载
+ * [POS]: Android React Native 生命周期兼容层，隔离框架版本差异，使 UpdateModuleImpl 不感知具体重载机制
+ */
+package cn.reactnative.modules.update;
+
+import android.app.Activity;
+import android.content.Context;
+import android.util.Log;
+import androidx.annotation.Nullable;
+import com.facebook.react.ReactActivity;
+import com.facebook.react.ReactApplication;
+import com.facebook.react.ReactDelegate;
+import com.facebook.react.ReactInstanceManager;
+import com.facebook.react.ReactNativeHost;
+import com.facebook.react.bridge.JSBundleLoader;
+import com.facebook.react.bridge.ReactApplicationContext;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+
+final class ReactReloadManager {
+    private ReactReloadManager() {
+    }
+
+    /**
+     * First half of a restart, for the state serial thread: activate the
+     * requested version (bundle digest + commit) and resolve the bundle to
+     * load. Nothing here touches React, so nothing here needs the UI thread
+     * (CODE_AUDIT 2.2). Returns the bundle path, or null for the packaged
+     * bundle.
+     */
+    @Nullable
+    static String prepareRestart(UpdateContext updateContext, @Nullable String hash) {
+        if (hash != null) {
+            updateContext.switchVersion(hash);
+        }
+        return updateContext.getBundleUrl();
+    }
+
+    /**
+     * Second half, for the UI thread: point the running React instance at
+     * {@code updateBundlePath} and reload it. Throws when no supported
+     * injection worked — the caller rejects RESTART_FAILED. There is
+     * deliberately no Activity.recreate() fallback: it would reload the
+     * previous bundle while the promise reported success (CODE_AUDIT 2.9).
+     */
+    static void reload(
+        UpdateContext updateContext,
+        ReactApplicationContext reactContext,
+        @Nullable String updateBundlePath
+    ) throws Throwable {
+        Context application = reactContext.getApplicationContext();
+        Activity currentActivity = reactContext.getCurrentActivity();
+
+        boolean newArchitectureEnabled = isNewArchitectureEnabled(application);
+        Object reactHost = newArchitectureEnabled ? getReactHost(currentActivity, application) : null;
+        if (reactHost != null) {
+            try {
+                reloadReactHost(reactHost, createBundleLoader(application, updateBundlePath, true));
+                return;
+            } catch (Throwable err) {
+                Log.e(UpdateContext.TAG,
+                    "Failed to reload via ReactHost, trying ReactInstanceManager", err);
+            }
+        }
+
+        JSBundleLoader loader = createBundleLoader(application, updateBundlePath, false);
+        ReactInstanceManager instanceManager =
+            resolveReactInstanceManager(updateContext, application);
+
+        // Java (mBundleLoader / mJSBundleFile) and Kotlin (bundleLoader /
+        // jsBundleFile) spellings of the private fields are both tried.
+        try {
+            Field loadField = getCompatibleField(instanceManager.getClass(), "bundleLoader");
+            loadField.setAccessible(true);
+            loadField.set(instanceManager, loader);
+        } catch (Throwable err) {
+            Field jsBundleField = getCompatibleField(instanceManager.getClass(), "jsBundleFile");
+            jsBundleField.setAccessible(true);
+            jsBundleField.set(instanceManager, updateBundlePath);
+        }
+
+        instanceManager.recreateReactContextInBackground();
+    }
+
+    private static Field getCompatibleField(Class<?> clazz, String fieldName)
+        throws NoSuchFieldException {
+        try {
+            return clazz.getDeclaredField("m" + capitalize(fieldName));
+        } catch (NoSuchFieldException e) {
+            try {
+                return clazz.getDeclaredField(fieldName);
+            } catch (NoSuchFieldException e2) {
+                throw new NoSuchFieldException(
+                    "Field not found with either name: m"
+                        + capitalize(fieldName)
+                        + " or "
+                        + fieldName
+                );
+            }
+        }
+    }
+
+    private static String capitalize(String str) {
+        if (str == null || str.length() == 0) {
+            return str;
+        }
+        return str.substring(0, 1).toUpperCase() + str.substring(1);
+    }
+
+    private static String getDefaultBundleAssetName(Context application) {
+        String bundleAssetName = "index.android.bundle";
+        if (!(application instanceof ReactApplication)) {
+            return bundleAssetName;
+        }
+
+        try {
+            ReactNativeHost reactNativeHost = ((ReactApplication) application).getReactNativeHost();
+            if (reactNativeHost == null) {
+                return bundleAssetName;
+            }
+
+            Method getBundleAssetNameMethod = ReactNativeHost.class.getDeclaredMethod("getBundleAssetName");
+            getBundleAssetNameMethod.setAccessible(true);
+            Object resolvedBundleAssetName = getBundleAssetNameMethod.invoke(reactNativeHost);
+            if (resolvedBundleAssetName instanceof String && !((String) resolvedBundleAssetName).isEmpty()) {
+                return (String) resolvedBundleAssetName;
+            }
+        } catch (Exception e) {
+            Log.e(UpdateContext.TAG, "Failed to get default asset name from ReactNativeHost", e);
+        }
+
+        return bundleAssetName;
+    }
+
+    private static String toAssetUrl(String bundleAssetName) {
+        if (bundleAssetName == null || bundleAssetName.isEmpty()) {
+            return "assets://index.android.bundle";
+        }
+        if (bundleAssetName.startsWith("assets://")) {
+            return bundleAssetName;
+        }
+        return "assets://" + bundleAssetName;
+    }
+
+    private static JSBundleLoader createBundleLoader(
+        Context application,
+        @Nullable String updateBundlePath,
+        boolean loadAssetSynchronously
+    ) {
+        if (updateBundlePath != null) {
+            return JSBundleLoader.createFileLoader(updateBundlePath);
+        }
+        return JSBundleLoader.createAssetLoader(
+            application,
+            toAssetUrl(getDefaultBundleAssetName(application)),
+            loadAssetSynchronously
+        );
+    }
+
+    @Nullable
+    private static Object getReactHost(@Nullable Activity currentActivity, Context application) {
+        if (currentActivity instanceof ReactActivity) {
+            try {
+                Method getReactDelegateMethod = ReactActivity.class.getMethod("getReactDelegate");
+                ReactDelegate reactDelegate =
+                    (ReactDelegate) getReactDelegateMethod.invoke(currentActivity);
+                if (reactDelegate != null) {
+                    Field reactHostField = getCompatibleField(reactDelegate.getClass(), "reactHost");
+                    reactHostField.setAccessible(true);
+                    Object reactHost = reactHostField.get(reactDelegate);
+                    if (reactHost != null) {
+                        return reactHost;
+                    }
+                }
+            } catch (Throwable ignored) {
+                Log.w(UpdateContext.TAG, "getReactHost via ReactDelegate reflection failed", ignored);
+            }
+        }
+
+        try {
+            Method getReactHostMethod = application.getClass().getMethod("getReactHost");
+            return getReactHostMethod.invoke(application);
+        } catch (Throwable ignored) {
+            Log.w(UpdateContext.TAG, "getReactHost via Application.getReactHost() failed", ignored);
+        }
+
+        return null;
+    }
+
+    private static boolean isNewArchitectureEnabled(Context application) {
+        if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
+            return true;
+        }
+
+        try {
+            Class<?> buildConfigClass = Class.forName(application.getPackageName() + ".BuildConfig");
+            Field newArchitectureField = buildConfigClass.getField("IS_NEW_ARCHITECTURE_ENABLED");
+            if (newArchitectureField.getBoolean(null)) {
+                return true;
+            }
+        } catch (Throwable ignored) {
+        }
+
+        if (application instanceof ReactApplication) {
+            try {
+                ReactNativeHost reactNativeHost = ((ReactApplication) application).getReactNativeHost();
+                Method isNewArchEnabledMethod = getDeclaredMethodInHierarchy(
+                    reactNativeHost.getClass(),
+                    "isNewArchEnabled"
+                );
+                isNewArchEnabledMethod.setAccessible(true);
+                Object result = isNewArchEnabledMethod.invoke(reactNativeHost);
+                return result instanceof Boolean && (Boolean) result;
+            } catch (Throwable ignored) {
+            }
+        }
+
+        return false;
+    }
+
+    private static Method getDeclaredMethodInHierarchy(Class<?> clazz, String methodName)
+        throws NoSuchMethodException {
+        Class<?> current = clazz;
+        while (current != null) {
+            try {
+                return current.getDeclaredMethod(methodName);
+            } catch (NoSuchMethodException ignored) {
+                current = current.getSuperclass();
+            }
+        }
+
+        throw new NoSuchMethodException(methodName);
+    }
+
+    private static void reloadReactHost(Object reactHost, JSBundleLoader loader) throws Throwable {
+        try {
+            Field devSupportField = getCompatibleField(reactHost.getClass(), "useDevSupport");
+            devSupportField.setAccessible(true);
+            devSupportField.set(reactHost, false);
+        } catch (Throwable ignored) {
+        }
+
+        Field reactHostDelegateField = getCompatibleField(reactHost.getClass(), "reactHostDelegate");
+        reactHostDelegateField.setAccessible(true);
+        Object reactHostDelegate = reactHostDelegateField.get(reactHost);
+
+        String bundleFieldName = "jsBundleLoader";
+        if ("expo.modules.ExpoReactHostFactory.ExpoReactHostDelegate".equals(
+            reactHostDelegate.getClass().getCanonicalName()
+        )) {
+            bundleFieldName = "_jsBundleLoader";
+        }
+
+        Field jsBundleLoaderField = reactHostDelegate.getClass().getDeclaredField(bundleFieldName);
+        jsBundleLoaderField.setAccessible(true);
+        jsBundleLoaderField.set(reactHostDelegate, loader);
+
+        Method reloadMethod = reactHost.getClass().getMethod("reload", String.class);
+        reloadMethod.invoke(reactHost, "react-native-update");
+    }
+
+    private static ReactInstanceManager resolveReactInstanceManager(
+        UpdateContext updateContext,
+        Context application
+    ) {
+        ReactInstanceManager instanceManager = updateContext.getCustomReactInstanceManager();
+        if (instanceManager != null) {
+            return instanceManager;
+        }
+        return ((ReactApplication) application).getReactNativeHost().getReactInstanceManager();
+    }
+}

package/android/src/main/java/cn/reactnative/modules/update/SafeZipFile.java

@@ -0,0 +1,187 @@
+/**
+ * [INPUT]: 依赖 java.util.zip.ZipFile、规范化文件路径与受控解压目标目录
+ * [OUTPUT]: 对外提供 SafeZipFile、受保护 entries 迭代及 unzipToPath/unzipToFile
+ * [POS]: Android 归档安全边界，在 DownloadTask 和 BundledResourceCopier 读取任何条目前阻断 Zip Slip 路径穿越
+ */
+package cn.reactnative.modules.update;
+
+import java.io.BufferedInputStream;
+import java.io.BufferedOutputStream;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Enumeration;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipFile;
+
+
+public class SafeZipFile extends ZipFile {
+
+    public SafeZipFile(File file) throws IOException {
+        super(file);
+    }
+
+    private static final int BUFFER_SIZE = 8192;
+
+    // Bytes written by unzipToFile across the archive: the sum of the central
+    // directory's declared sizes is checked up front (inspect), the actual
+    // stream is re-checked here — headers can lie.
+    private long totalWritten = 0;
+
+    static final class Inspection {
+        long entries;
+        long totalUncompressed;
+    }
+
+    /**
+     * Walks the central directory once, enforcing the archive_limits caps
+     * (entry count, per-entry size, total size, compression ratio) and the
+     * reserved-name / traversal rules, before a single byte is extracted.
+     */
+    Inspection inspect() throws IOException {
+        Inspection result = new Inspection();
+        Enumeration<? extends ZipEntry> entries = entries();
+        while (entries.hasMoreElements()) {
+            ZipEntry entry = entries.nextElement();
+            result.entries++;
+            if (result.entries > ArchiveLimits.MAX_ENTRIES) {
+                throw new IOException(
+                    "archive has too many entries (> " + ArchiveLimits.MAX_ENTRIES + ")");
+            }
+            long size = entry.getSize();
+            long compressed = entry.getCompressedSize();
+            if (size > ArchiveLimits.MAX_ENTRY_BYTES) {
+                throw new IOException(
+                    "archive entry too large: " + entry.getName() + " (" + size + " bytes)");
+            }
+            if (size > 0) {
+                result.totalUncompressed += size;
+                if (result.totalUncompressed > ArchiveLimits.MAX_TOTAL_UNCOMPRESSED_BYTES) {
+                    throw new IOException("archive expands beyond "
+                        + ArchiveLimits.MAX_TOTAL_UNCOMPRESSED_BYTES + " bytes");
+                }
+                if (compressed > 0 && size > ArchiveLimits.RATIO_CHECK_MIN_BYTES
+                    && size / compressed > ArchiveLimits.MAX_COMPRESSION_RATIO) {
+                    throw new IOException(
+                        "archive entry compression ratio too high: " + entry.getName());
+                }
+            }
+        }
+        return result;
+    }
+
+    // Files the SDK itself writes into a version directory to record its own
+    // decisions (the ".pakta-complete" install marker today). An archive
+    // must never be able to ship one: a package that unzips its own marker
+    // next to a bundle would be trusted as a finished install even when the
+    // patch step that follows fails.
+    static final String RESERVED_ENTRY_PREFIX = ".pakta-";
+
+    static boolean isReservedEntryName(String name) {
+        if (name == null) {
+            return false;
+        }
+        String normalized = name.replace('\\', '/');
+        while (normalized.endsWith("/")) {
+            normalized = normalized.substring(0, normalized.length() - 1);
+        }
+        int slash = normalized.lastIndexOf('/');
+        String baseName = slash >= 0 ? normalized.substring(slash + 1) : normalized;
+        return baseName.startsWith(RESERVED_ENTRY_PREFIX);
+    }
+
+    @Override
+    public Enumeration<? extends ZipEntry> entries() {
+        return new SafeZipEntryIterator(super.entries());
+    }
+
+    private static class SafeZipEntryIterator implements Enumeration<ZipEntry> {
+
+        final private Enumeration<? extends ZipEntry> delegate;
+
+        private SafeZipEntryIterator(Enumeration<? extends ZipEntry> delegate) {
+            this.delegate = delegate;
+        }
+
+        @Override
+        public boolean hasMoreElements() {
+            return delegate.hasMoreElements();
+        }
+
+        @Override
+        public ZipEntry nextElement() {
+            ZipEntry entry = delegate.nextElement();
+            if (null != entry) {
+                String name = entry.getName();
+                /**
+                 * avoid ZipperDown
+                 */
+                if (null != name && (name.contains("../") || name.contains("..\\"))) {
+                    throw new SecurityException("illegal entry: " + name);
+                }
+                if (isReservedEntryName(name)) {
+                    throw new SecurityException("reserved entry: " + name);
+                }
+            }
+            return entry;
+        }
+    }
+
+    public void unzipToPath(ZipEntry ze, File targetPath) throws IOException {
+        String name = ze.getName();
+        File target = new File(targetPath, name);
+
+        // Fixing a Zip Path Traversal Vulnerability
+        // https://support.google.com/faqs/answer/9294009
+        String canonicalPath = target.getCanonicalPath();
+        if (!canonicalPath.startsWith(targetPath.getCanonicalPath() + File.separator)) {
+            throw new SecurityException("Illegal name: " + name);
+        }
+        if (isReservedEntryName(name)) {
+            throw new SecurityException("reserved entry: " + name);
+        }
+
+        if (ze.isDirectory()) {
+            target.mkdirs();
+            return;
+        }
+        unzipToFile(ze, target);
+    }
+
+    public void unzipToFile(ZipEntry ze, File target) throws IOException {
+        File parent = target.getParentFile();
+        if (parent != null && !parent.exists() && !parent.mkdirs() && !parent.exists()) {
+            throw new IOException("Failed to create parent dir for " + target);
+        }
+
+        // The declared size is the budget when known; otherwise the global
+        // per-entry cap. Either way the stream may not exceed it.
+        long declared = ze.getSize();
+        long budget = declared >= 0
+            ? Math.min(declared, ArchiveLimits.MAX_ENTRY_BYTES)
+            : ArchiveLimits.MAX_ENTRY_BYTES;
+        long written = 0;
+        try (InputStream inputStream = getInputStream(ze)) {
+            try (BufferedOutputStream output = new BufferedOutputStream(new FileOutputStream(target));
+                 BufferedInputStream input = new BufferedInputStream(inputStream)) {
+                byte[] buffer = new byte[BUFFER_SIZE];
+                int n;
+                while ((n = input.read(buffer, 0, BUFFER_SIZE)) >= 0) {
+                    written += n;
+                    totalWritten += n;
+                    if (written > budget) {
+                        throw new IOException(
+                            "archive entry exceeds its declared size: " + ze.getName());
+                    }
+                    if (totalWritten > ArchiveLimits.MAX_TOTAL_UNCOMPRESSED_BYTES) {
+                        throw new IOException("archive expands beyond "
+                            + ArchiveLimits.MAX_TOTAL_UNCOMPRESSED_BYTES + " bytes");
+                    }
+                    output.write(buffer, 0, n);
+                }
+            }
+        }
+    }
+
+}

package/android/src/main/java/cn/reactnative/modules/update/StateCoreResult.java

@@ -0,0 +1,22 @@
+/**
+ * [INPUT]: 依赖 UpdateContext 的持久状态快照与 cpp/patch_core 状态机 JNI 映射
+ * [OUTPUT]: 对内提供包体身份、当前/上次版本、首启、回滚、清理、加载决策及成功确认匹配字段
+ * [POS]: Android Java/C++ 状态机 DTO，是 SharedPreferences 表示与纯原生决策之间的数据载体
+ */
+package cn.reactnative.modules.update;
+
+class StateCoreResult {
+    String packageVersion;
+    String buildTime;
+    String currentVersion;
+    String lastVersion;
+    boolean firstTime;
+    boolean firstTimeOk;
+    String rolledBackVersion;
+    boolean changed;
+    String staleVersionToDelete;
+    String loadVersion;
+    boolean didRollback;
+    boolean consumedFirstTime;
+    boolean markSuccessAccepted;
+}

package/android/src/main/java/cn/reactnative/modules/update/StateSerialRunner.java

@@ -0,0 +1,70 @@
+/**
+ * [INPUT]: 依赖单线程 Executor、Promise、UpdateContext 日志标识与稳定错误码
+ * [OUTPUT]: 对内提供 Operation 和 run，按提交顺序在后台执行状态持久化并统一成功/失败回调
+ * [POS]: Android 状态写入串行化边界，替代 UI 线程磁盘写入，同时保持 switch/mark/reset 的顺序语义
+ */
+package cn.reactnative.modules.update;
+
+import android.util.Log;
+import androidx.annotation.Nullable;
+import com.facebook.react.bridge.Promise;
+
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ThreadFactory;
+
+/**
+ * Runs state-persistence operations (switchVersion / markSuccess / setUuid /
+ * setLocalHashInfo) on a dedicated single background thread.
+ *
+ * These operations only read/modify SharedPreferences via a synchronous
+ * commit(); they were previously dispatched to the UI thread purely to
+ * serialize them. markSuccess in particular runs on every cold start, so doing
+ * its blocking disk write on the main thread caused jank/ANR on low-end
+ * devices. A single-thread executor preserves the same serialization guarantee
+ * while keeping the disk I/O off the UI thread.
+ *
+ * Note: reload/restart operations must still run on the UI thread and therefore
+ * keep using {@link UiThreadRunner}.
+ */
+final class StateSerialRunner {
+    interface Operation {
+        void run() throws Throwable;
+    }
+
+    // Single worker thread -> operations stay serialized in submission order,
+    // matching the previous UI-thread behavior. The thread is named so it is
+    // identifiable in thread dumps / ANR traces when diagnosing persistence.
+    private static final Executor EXECUTOR = Executors.newSingleThreadExecutor(
+        new ThreadFactory() {
+            @Override
+            public Thread newThread(Runnable r) {
+                return new Thread(r, "pakta-state-serial");
+            }
+        });
+
+    private StateSerialRunner() {
+    }
+
+    static void run(
+        @Nullable final Promise promise,
+        final String errorCode,
+        final String operationName,
+        final Operation operation
+    ) {
+        EXECUTOR.execute(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    operation.run();
+                } catch (Throwable error) {
+                    if (promise != null) {
+                        promise.reject(errorCode, operationName + " failed", error);
+                    } else {
+                        Log.e(UpdateContext.TAG, operationName + " failed", error);
+                    }
+                }
+            }
+        });
+    }
+}