react-native-update 10.47.0 → 10.48.1

package/android/jni/Android.mk

@@ -21,6 +21,8 @@ Hdp_Files := \
 
 LOCAL_SRC_FILES := \
 	../../cpp/patch_core/archive_patch_core.cpp \
+	../../cpp/patch_core/hbc_transform.cpp \
+	../../cpp/patch_core/hbc_transform_wire.cpp \
 	../../cpp/patch_core/patch_core.cpp \
 	../../cpp/patch_core/patch_core_android.cpp \
 	../../cpp/patch_core/state_core.cpp \

package/android/jni/hpatch.c

@@ -18,15 +18,6 @@
 #define  _check(v,errorType) do{ \
     if (!(v)){ if (result==kHPatch_ok) result=errorType; if (!_isInClear){ goto _clear; }; } }while(0)
 
-int hpatch_getInfo_by_mem(hpatch_singleCompressedDiffInfo* out_patinfo,
-                          const uint8_t* pat,size_t patsize){
-    hpatch_TStreamInput patStream;
-    mem_as_hStreamInput(&patStream,pat,pat+patsize);
-    if (!getSingleCompressedDiffInfo(out_patinfo,&patStream,0))
-        return kHPatch_error_info;//data error;
-    return kHPatch_ok; //ok
-}
-
 static hpatch_TDecompress* getDecompressPlugin(const char* compressType){
 #ifdef  _CompressPlugin_zlib
     if (zlibDecompressPlugin.is_can_open(compressType))
@@ -63,7 +54,9 @@ static int hpatch_by_stream(const hpatch_TStreamInput* old,hpatch_BOOL isLoadOld
         _check(old->streamSize==patInfo->oldDataSize,kHPatch_error_old_size);
         _check(out_new->streamSize>=patInfo->newDataSize,kHPatch_error_new_size);
         out_new->streamSize=patInfo->newDataSize;
-        if (strlen(patInfo->compressType)>0){
+        // v5 writer 可能保留 lzma2 标签但以 RAW 存储小 diff;compressedSize==0
+        // 才是格式里的未压缩判据,不能按标签强行走解压。
+        if ((strlen(patInfo->compressType)>0)&&(patInfo->compressedSize>0)){
             decompressPlugin=getDecompressPlugin(patInfo->compressType);
             _check(decompressPlugin,kHPatch_error_compressType);
         }
@@ -94,21 +87,57 @@ _clear:
     return result;
 }
 
-int hpatch_by_mem(const uint8_t* old,size_t oldsize,uint8_t* newBuf,size_t newsize,
-                  const uint8_t* pat,size_t patsize,const hpatch_singleCompressedDiffInfo* patInfo){
-    hpatch_TStreamInput oldStream;
-    hpatch_TStreamInput patStream;
-    hpatch_TStreamOutput newStream;
-    mem_as_hStreamInput(&oldStream,old,old+oldsize);
-    mem_as_hStreamInput(&patStream,pat,pat+patsize);
-    mem_as_hStreamOutput(&newStream,newBuf,newBuf+newsize);
-    return hpatch_by_stream(&oldStream,hpatch_FALSE,&patStream,&newStream,patInfo);
+// HDIFF13(diffStream 产物,v2 轨道的大 bundle patch):流式应用,
+// 内存 = 解压缓存 + IO 缓冲(+ old ≤ 8MB 时的整载优化),与 single 路径同级。
+static int hpatch_v13_by_stream(const hpatch_TStreamInput* old,hpatch_BOOL isLoadOldAllToMem,
+                                const hpatch_TStreamInput* pat,hpatch_TStreamOutput* out_new){
+    int     result=kHPatch_ok;
+    int     _isInClear=hpatch_FALSE;
+    hpatch_TDecompress* decompressPlugin=0;
+    uint8_t* temp_cache=0;
+    size_t temp_cache_size;
+    hpatch_compressedDiffInfo patInfo;
+    hpatch_TStreamInput _old;
+    {// info
+        _check(getCompressedDiffInfo(&patInfo,pat),kHPatch_error_info);
+        _check(old->streamSize==patInfo.oldDataSize,kHPatch_error_old_size);
+        _check(out_new->streamSize>=patInfo.newDataSize,kHPatch_error_new_size);
+        out_new->streamSize=patInfo.newDataSize;
+        if (strlen(patInfo.compressType)>0){
+            decompressPlugin=getDecompressPlugin(patInfo.compressType);
+            _check(decompressPlugin,kHPatch_error_compressType);
+        }
+    }
+    {// mem
+        size_t mem_size;
+        size_t oldSize=(size_t)old->streamSize;
+        isLoadOldAllToMem=isLoadOldAllToMem&&(old->streamSize<=kMaxLoadMemOldSize);
+        temp_cache_size=hpatch_kStreamCacheSize*8+hpatch_kFileIOBufBetterSize*3;
+        mem_size=temp_cache_size+(isLoadOldAllToMem?oldSize:0);
+        temp_cache=malloc(mem_size);
+        _check(temp_cache,kHPatch_error_malloc);
+        if (isLoadOldAllToMem){//load old to mem
+            uint8_t* oldMem=temp_cache+temp_cache_size;
+            _check(old->read(old,0,oldMem,oldMem+oldSize),kHPatch_error_old_fread);
+            mem_as_hStreamInput(&_old,oldMem,oldMem+oldSize);
+            old=&_old;
+        }
+    }
+
+    _check(patch_decompress_with_cache(out_new,old,pat,decompressPlugin,
+               temp_cache,temp_cache+temp_cache_size),kHPatch_error_patch);
+
+_clear:
+    _isInClear=hpatch_TRUE;
+    if (temp_cache){ free(temp_cache); temp_cache=0; }
+    return result;
 }
 
 int hpatch_by_file(const char* oldfile, const char* newfile, const char* patchfile){
     int     result=kHPatch_ok;
     int     _isInClear=hpatch_FALSE;
     int     patch_result;
+    hpatch_singleCompressedDiffInfo singleInfo;
     hpatch_TFileStreamInput oldStream;
     hpatch_TFileStreamInput patStream;
     hpatch_TFileStreamOutput newStream;
@@ -120,7 +149,13 @@ int hpatch_by_file(const char* oldfile, const char* newfile, const char* patchfi
     _check(hpatch_TFileStreamInput_open(&patStream,patchfile),kHPatch_error_pat_fopen);
     _check(hpatch_TFileStreamOutput_open(&newStream,newfile,~(hpatch_StreamPos_t)0),kHPatch_error_new_fopen);
 
-    patch_result=hpatch_by_stream(&oldStream.base,hpatch_TRUE,&patStream.base,&newStream.base,0);
+    // 按 patch 头自动分派格式:single(HDIFFSF20,现状)或 stream(HDIFF13,
+    // v2 轨道大 bundle)。老客户端只会收到 single;能力门控在服务端。
+    if (getSingleCompressedDiffInfo(&singleInfo,&patStream.base,0)){
+        patch_result=hpatch_by_stream(&oldStream.base,hpatch_TRUE,&patStream.base,&newStream.base,&singleInfo);
+    }else{
+        patch_result=hpatch_v13_by_stream(&oldStream.base,hpatch_TRUE,&patStream.base,&newStream.base);
+    }
     if (patch_result!=kHPatch_ok){
         _check(!oldStream.fileError,kHPatch_error_old_fread);
         _check(!patStream.fileError,kHPatch_error_pat_fread);

package/android/jni/hpatch.h

@@ -30,12 +30,6 @@ enum {
     kHPatch_error_new_size      =-15,
 };
 
-int hpatch_getInfo_by_mem(hpatch_singleCompressedDiffInfo* out_patinfo,
-                          const uint8_t* pat,size_t patsize);
-
-//patInfo can NULL
-int hpatch_by_mem(const uint8_t* old,size_t oldsize, uint8_t* newBuf,size_t newsize,
-                  const uint8_t* pat,size_t patsize,const hpatch_singleCompressedDiffInfo* patInfo);
 int hpatch_by_file(const char* oldfile, const char* newfile, const char* patchfile);
 
 #ifdef __cplusplus

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

@@ -53,6 +53,17 @@ class DownloadTask implements Runnable {
         final ArrayList<String> copyFroms = new ArrayList<String>();
         final ArrayList<String> copyTos = new ArrayList<String>();
         final ArrayList<String> deletes = new ArrayList<String>();
+        // __diff.json 的 hbcTransform 元数据(按 patch 条目名索引);
+        // 为空对象/缺失时返回 ""(native 走现状路径)
+        JSONObject hbcTransform;
+
+        String hbcTransformMetaFor(String patchEntryName) {
+            if (hbcTransform == null) {
+                return "";
+            }
+            JSONObject meta = hbcTransform.optJSONObject(patchEntryName);
+            return meta != null ? meta.toString() : "";
+        }
         // Maps a copy source path ("from") to the CRC32 of the file content,
         // when provided by the manifest ("copiesCrc"). Lets the resource
         // copier locate the file by content if the path is not present on
@@ -74,12 +85,15 @@ class DownloadTask implements Runnable {
     }
 
     private void postProgress(final long received, final long total) {
+        // Cross-platform progress contract: unknown length is reported as
+        // total=0, never a raw -1 (OkHttp's contentLength for chunked/gzip).
+        final long normalizedTotal = total > 0 ? total : 0;
         mainHandler.post(new Runnable() {
             @Override
             public void run() {
                 WritableMap progress = Arguments.createMap();
                 progress.putDouble("received", received);
-                progress.putDouble("total", total);
+                progress.putDouble("total", normalizedTotal);
                 progress.putString("hash", hash);
                 UpdateEventEmitter.sendEvent("RCTPushyDownloadProgress", progress);
             }
@@ -125,6 +139,7 @@ class DownloadTask implements Runnable {
                         int percentage = (int) (received * 100.0 / contentLength + 0.5);
                         if (percentage > currentPercentage) {
                             currentPercentage = percentage;
+                            lastPostedBytes = received;
                             postProgress(received, contentLength);
                         }
                     } else if (received - lastPostedBytes >= PROGRESS_BYTES_THRESHOLD) {
@@ -138,7 +153,11 @@ class DownloadTask implements Runnable {
             if (contentLength >= 0 && received != contentLength) {
                 throw new IOException("Unexpected eof while reading downloaded update");
             }
-            postProgress(received, contentLength);
+            // Final progress event, skipped when the loop already posted this
+            // exact value (known length reaching 100% posts it in-loop).
+            if (received != lastPostedBytes) {
+                postProgress(received, contentLength);
+            }
         }
 
     }
@@ -251,6 +270,7 @@ class DownloadTask implements Runnable {
                         contents.deletes,
                         contents.copyCrcs
                     );
+                    contents.hbcTransform = manifest.optJSONObject("hbcTransform");
                     continue;
                 }
 
@@ -311,7 +331,8 @@ class DownloadTask implements Runnable {
                 false,
                 new String[0],
                 new String[0],
-                new String[0]
+                new String[0],
+                contents.hbcTransformMetaFor("index.bundlejs.patch")
             );
         } finally {
             originBundleFile.delete();
@@ -345,7 +366,8 @@ class DownloadTask implements Runnable {
             plan.enableMerge,
             contents.copyFroms.toArray(new String[0]),
             contents.copyTos.toArray(new String[0]),
-            contents.deletes.toArray(new String[0])
+            contents.deletes.toArray(new String[0]),
+            contents.hbcTransformMetaFor("index.bundlejs.patch")
         );
         if (params.targetFile.exists()) {
             params.targetFile.delete();
@@ -357,7 +379,7 @@ class DownloadTask implements Runnable {
             params.unzipDirectory.getAbsolutePath(),
             params.hash,
             params.originHash,
-            3
+            params.maxAgeDays
         );
     }
 
@@ -444,7 +466,8 @@ class DownloadTask implements Runnable {
         boolean enableMerge,
         String[] copyFroms,
         String[] copyTos,
-        String[] deletes
+        String[] deletes,
+        String hbcTransformMeta
     );
 
     private static native void cleanupOldEntries(

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

@@ -18,6 +18,8 @@ class DownloadTaskParams {
     String      url;
     String      hash;
     String      originHash;
+    // TASK_TYPE_CLEANUP only: entries younger than this survive; 0 = delete all
+    int         maxAgeDays = 3;
     File        targetFile;
     File        unzipDirectory;
     File        originDirectory;

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

@@ -16,6 +16,7 @@ final class ErrorCodes {
     static final String SWITCH_VERSION_FAILED = "SWITCH_VERSION_FAILED";
     static final String MARK_SUCCESS_FAILED = "MARK_SUCCESS_FAILED";
     static final String RESTART_FAILED = "RESTART_FAILED";
+    static final String RESET_FAILED = "RESET_FAILED";
     static final String INVALID_HASH_INFO = "INVALID_HASH_INFO";
     static final String UNSUPPORTED_PLATFORM = "UNSUPPORTED_PLATFORM";
 

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

@@ -23,4 +23,16 @@ final class NativeUpdateCore {
 
         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/UpdateContext.java

@@ -26,8 +26,16 @@ public class UpdateContext {
     private final SharedPreferences sp;
 
     private ReactInstanceManager reactInstanceManager;
-    private boolean isUsingBundleUrl;
-    private boolean ignoreRollback;
+    // Written on the launch path, read from executor/JS threads.
+    private volatile boolean isUsingBundleUrl;
+    private volatile boolean ignoreRollback;
+    // The version whose bundle this process actually loaded (resolved in
+    // getBundleUrl). resetToPackagedBundle must not delete its directory:
+    // update assets (images/fonts) are read from it on demand at runtime, so
+    // wiping it under a silent (no-restart) reset would break every image the
+    // running app has not loaded yet. Volatile: written during launch, read
+    // from the state serial executor.
+    private volatile String launchVersion;
     private static final int STATE_OP_SWITCH_VERSION = 1;
     private static final int STATE_OP_MARK_SUCCESS = 2;
     private static final int STATE_OP_ROLLBACK = 3;
@@ -303,6 +311,42 @@ public class UpdateContext {
         this.cleanUp();
     }
 
+    /**
+     * Reset to the bundle packaged in the binary: wipe the whole update state
+     * (so the next launch resolves to the built-in bundle) and delete the
+     * downloaded versions, keeping only the directory of the version this
+     * process is running from (a silent reset must not break its on-demand
+     * asset loads). Only the client uuid survives — it identifies the install
+     * for gray release bucketing and must not change on reset.
+     */
+    public void resetToPackagedBundle() {
+        StateCoreResult resetState = new StateCoreResult();
+        resetState.packageVersion = getPackageVersion();
+        resetState.buildTime = getBuildTime();
+        resetState.firstTime = false;
+        resetState.firstTimeOk = true;
+        String uuid = sp.getString("uuid", null);
+        SharedPreferences.Editor editor = sp.edit();
+        editor.clear();
+        applyState(editor, resetState);
+        if (uuid != null) {
+            editor.putString("uuid", uuid);
+        }
+        persistEditor(editor, "reset to packaged bundle");
+        ignoreRollback = false;
+        Log.i(TAG, "Reset to packaged bundle");
+
+        DownloadTaskParams params = new DownloadTaskParams();
+        params.type = DownloadTaskParams.TASK_TYPE_CLEANUP;
+        params.maxAgeDays = 0;
+        // Keep the directory of the version this process is running from (a
+        // silent reset would otherwise break its on-demand asset loads); the
+        // orphaned directory is removed by the next regular cleanup.
+        params.hash = launchVersion;
+        params.unzipDirectory = rootDir;
+        enqueue(params);
+    }
+
     public void clearRollbackMark() {
         StateCoreResult currentState = getStateSnapshot();
         StateCoreResult nextState = runStateCore(
@@ -405,6 +449,7 @@ public class UpdateContext {
                 currentVersion = this.rollBack();
                 continue;
             }
+            launchVersion = currentVersion;
             return bundleFile.toString();
         }
 

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

@@ -1,5 +1,6 @@
 package cn.reactnative.modules.update;
 
+import android.util.Log;
 import androidx.annotation.Nullable;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.modules.core.DeviceEventManagerModule;
@@ -28,9 +29,17 @@ final class UpdateEventEmitter {
             return;
         }
 
-        reactContext
-            .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
-            .emit(eventName, params);
+        try {
+            reactContext
+                .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
+                .emit(eventName, params);
+        } catch (RuntimeException e) {
+            // The instance can be torn down between the check above and the
+            // emit (this SDK itself triggers reloads); sendEvent runs on the
+            // main thread, so a throw here would crash the app for a lost
+            // progress tick.
+            Log.w("pushy", "sendEvent " + eventName + " failed: " + e.getMessage());
+        }
     }
 
     @SuppressWarnings("deprecation")

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

@@ -191,6 +191,19 @@ public class UpdateModuleImpl {
         });
     }
 
+    public static void resetToPackagedBundle(
+        final UpdateContext updateContext,
+        final Promise promise
+    ) {
+        StateSerialRunner.run(promise, ErrorCodes.RESET_FAILED, "resetToPackagedBundle", new StateSerialRunner.Operation() {
+            @Override
+            public void run() {
+                updateContext.resetToPackagedBundle();
+                promise.resolve(true);
+            }
+        });
+    }
+
     private static void setUuidInternal(UpdateContext updateContext, String uuid) {
         updateContext.setKv("uuid", uuid);
     }

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

@@ -5,6 +5,7 @@ import static androidx.core.content.FileProvider.getUriForFile;
 import android.content.Intent;
 import android.net.Uri;
 import android.os.Build;
+import android.util.Log;
 import com.facebook.react.bridge.ReactApplicationContext;
 import java.io.File;
 import java.util.HashMap;
@@ -35,6 +36,16 @@ final class UpdateModuleSupport {
         }
 
         constants.put("uuid", updateContext.getKv("uuid"));
+        int supportedDiffVersion = 0;
+        try {
+            supportedDiffVersion = NativeUpdateCore.supportedDiffVersion();
+        } catch (UnsatisfiedLinkError e) {
+            // A mismatched librnupdate.so (stale manual copy / build cache)
+            // must not crash startup via getConstants; 0 simply means "no v2
+            // diff track" and the server degrades gracefully.
+            Log.e("pushy", "supportedDiffVersion missing from librnupdate.so", e);
+        }
+        constants.put("supportedDiffVersion", supportedDiffVersion);
         return constants;
     }
 

package/android/src/newarch/cn/reactnative/modules/update/UpdateModule.java

@@ -73,6 +73,11 @@ public class UpdateModule extends NativePushySpec {
         UpdateModuleImpl.markSuccess(updateContext, promise);
     }
 
+    @Override
+    public void resetToPackagedBundle(Promise promise) {
+        UpdateModuleImpl.resetToPackagedBundle(updateContext, promise);
+    }
+
     @Override
     public void setUuid(String uuid, Promise promise) {
         UpdateModuleImpl.setUuid(updateContext, uuid, promise);

package/android/src/oldarch/cn/reactnative/modules/update/UpdateModule.java

@@ -75,6 +75,11 @@ public class UpdateModule extends ReactContextBaseJavaModule {
         UpdateModuleImpl.markSuccess(updateContext);
     }
 
+    @ReactMethod
+    public void resetToPackagedBundle(Promise promise) {
+        UpdateModuleImpl.resetToPackagedBundle(updateContext, promise);
+    }
+
     @ReactMethod
     public void setUuid(String uuid) {
         UpdateModuleImpl.setUuid(updateContext, uuid);

package/cpp/patch_core/error_codes.h

@@ -31,6 +31,9 @@ constexpr const char* kSwitchVersionFailed = "SWITCH_VERSION_FAILED";
 constexpr const char* kMarkSuccessFailed = "MARK_SUCCESS_FAILED";
 // reloadUpdate / restartApp failed.
 constexpr const char* kRestartFailed = "RESTART_FAILED";
+// resetToPackagedBundle failed (state wipe or cleanup could not run), or the
+// installed native module predates the method (JS-layer detection).
+constexpr const char* kResetFailed = "RESET_FAILED";
 // Stored or provided hash info is not a valid JSON object.
 constexpr const char* kInvalidHashInfo = "INVALID_HASH_INFO";
 // The method is not supported on this platform (e.g. downloadAndInstallApk

package/cpp/patch_core/hbc_transform.cpp

@@ -0,0 +1,147 @@
+#include "hbc_transform.h"
+
+#include <cstring>
+
+namespace pushy {
+namespace hbc {
+
+namespace {
+
+constexpr uint8_t kHbcMagic[8] =
+    {0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f};
+constexpr size_t kHeaderSize = 128;
+constexpr size_t kCountsOffset = 32; // magic(8) + version(4) + sourceHash(20)
+constexpr uint32_t kMaxEntryCount = 0x0fffffff;
+constexpr uint32_t kMaxEntrySize = 4096;
+constexpr uint32_t kMaxSections = 64;
+constexpr uint32_t kMaxCountFields = (kHeaderSize - kCountsOffset) / 4; // 24
+
+inline uint32_t ReadU32(const uint8_t* p) {
+  return static_cast<uint32_t>(p[0]) | (static_cast<uint32_t>(p[1]) << 8) |
+      (static_cast<uint32_t>(p[2]) << 16) |
+      (static_cast<uint32_t>(p[3]) << 24);
+}
+
+inline void WriteU32(uint8_t* p, uint32_t v) {
+  p[0] = static_cast<uint8_t>(v);
+  p[1] = static_cast<uint8_t>(v >> 8);
+  p[2] = static_cast<uint8_t>(v >> 16);
+  p[3] = static_cast<uint8_t>(v >> 24);
+}
+
+inline uint64_t Align4(uint64_t x) {
+  return (x + 3) & ~static_cast<uint64_t>(3);
+}
+
+struct ResolvedSection {
+  uint64_t start;
+  uint64_t size;
+  const HbcSectionDesc* desc;
+};
+
+} // namespace
+
+bool TransformHbcInPlace(
+    uint8_t* data,
+    size_t size,
+    const HbcLayoutDesc& layout,
+    bool inverse) {
+  // ---- 校验阶段:改写任何字节之前完成全部检查 ----
+  if (data == nullptr || size < kHeaderSize) {
+    return false;
+  }
+  if (std::memcmp(data, kHbcMagic, sizeof(kHbcMagic)) != 0) {
+    return false;
+  }
+  if (layout.headerCountFields < 2 ||
+      layout.headerCountFields > kMaxCountFields) {
+    return false;
+  }
+  if (layout.sections == nullptr || layout.sectionCount == 0 ||
+      layout.sectionCount > kMaxSections) {
+    return false;
+  }
+
+  uint32_t counts[kMaxCountFields];
+  for (uint32_t i = 0; i < layout.headerCountFields; ++i) {
+    counts[i] = ReadU32(data + kCountsOffset + static_cast<size_t>(i) * 4);
+  }
+  // 位置约定:槽位 0 = fileLength,最后一个槽位 = debugInfoOffset
+  const uint64_t fileLength = counts[0];
+  const uint64_t debugInfoOffset = counts[layout.headerCountFields - 1];
+  if (fileLength != size) {
+    return false;
+  }
+  if (debugInfoOffset < kHeaderSize || debugInfoOffset > size) {
+    return false;
+  }
+
+  ResolvedSection resolved[kMaxSections];
+  uint64_t off = kHeaderSize;
+  for (uint32_t i = 0; i < layout.sectionCount; ++i) {
+    const HbcSectionDesc& s = layout.sections[i];
+    if (s.countIndex >= layout.headerCountFields) {
+      return false;
+    }
+    if (s.entrySize == 0 || s.entrySize > kMaxEntrySize) {
+      return false;
+    }
+    const uint64_t count = counts[s.countIndex];
+    if (count > kMaxEntryCount) {
+      return false;
+    }
+    if (s.deltaFieldCount > 0 && s.deltaFields == nullptr) {
+      return false;
+    }
+    for (uint32_t f = 0; f < s.deltaFieldCount; ++f) {
+      const HbcDeltaField& field = s.deltaFields[f];
+      // bit 必须单独设上界:bit=0xFFFFFFFF 时 bit+bits 的 uint32 求和会回绕
+      // 绕过 >32 检查,改写阶段的 << bit 就成了移位量 ≥32 的 UB。
+      // bits≥1 时合法 bit 必 ≤31。
+      if (field.bits < 1 || field.bits > 32 || field.bit > 31 ||
+          field.bit + field.bits > 32 ||
+          static_cast<uint64_t>(field.byte) + 4 > s.entrySize) {
+        return false;
+      }
+    }
+    const uint64_t sectionSize = count * s.entrySize; // ≤ 2^28 × 2^12 < 2^40
+    off = Align4(off);
+    if (off + sectionSize > debugInfoOffset) {
+      return false;
+    }
+    resolved[i] = {off, sectionSize, &s};
+    off += sectionSize;
+  }
+
+  // ---- 改写阶段:校验通过后不再有失败路径 ----
+  for (uint32_t i = 0; i < layout.sectionCount; ++i) {
+    const ResolvedSection& r = resolved[i];
+    const HbcSectionDesc& s = *r.desc;
+    for (uint32_t f = 0; f < s.deltaFieldCount; ++f) {
+      const HbcDeltaField& field = s.deltaFields[f];
+      const uint32_t fieldMask =
+          field.bits == 32 ? 0xffffffffu : ((1u << field.bits) - 1u);
+      const uint32_t mask = fieldMask << field.bit;
+      uint32_t prev = 0;
+      const uint64_t end = r.start + r.size;
+      for (uint64_t p = r.start + field.byte; p < end; p += s.entrySize) {
+        uint8_t* wordPtr = data + p;
+        const uint32_t word = ReadU32(wordPtr);
+        const uint32_t val = (word >> field.bit) & fieldMask;
+        uint32_t enc;
+        if (!inverse) {
+          enc = (val - prev) & fieldMask;
+          prev = val;
+        } else {
+          enc = (val + prev) & fieldMask;
+          prev = enc;
+        }
+        WriteU32(wordPtr, (word & ~mask) | (enc << field.bit));
+      }
+    }
+  }
+  return true;
+}
+
+} // namespace hbc
+} // namespace pushy

package/cpp/patch_core/hbc_transform.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace pushy {
+namespace hbc {
+
+// Hermes 字节码(HBC)delta-friendly 可逆变换的通用解释器。
+//
+// 布局描述表来自 patch 的 __diff.json 元数据(生成端 CLI 写入),本解释器
+// 不含任何 HBC 版本分支——Hermes 版本演进只需要生成端更新描述表,客户端
+// 零跟进。描述表被视为不可信输入:所有段边界、条目大小、位域范围在改写
+// 任何字节之前完成全量校验;校验失败时 buffer 保持原样。
+//
+// 变换语义与生成端(react-native-update-cli src/utils/hbcTransform.ts)
+// 严格一致:对描述的偏移位域做前项差分(wrapping,模字段位宽)。
+// wrapping 保证与数据单调性无关的严格可逆。
+
+struct HbcDeltaField {
+  // 条目内字节偏移处按小端读取 u32,取 [bit, bit+bits) 位做差分
+  uint32_t byte;
+  uint32_t bit;
+  uint32_t bits;
+};
+
+struct HbcSectionDesc {
+  // 段大小 = headerCounts[countIndex] × entrySize(字节段 entrySize 为 1)
+  uint32_t countIndex;
+  uint32_t entrySize;
+  const HbcDeltaField* deltaFields;
+  uint32_t deltaFieldCount;
+};
+
+// 与 wire 格式的位置约定一致:counts 槽位 0 = fileLength,
+// 最后一个槽位 = debugInfoOffset(结构校验依赖)。
+struct HbcLayoutDesc {
+  uint32_t headerCountFields;
+  const HbcSectionDesc* sections;
+  uint32_t sectionCount;
+};
+
+// 对 data 原地执行变换(inverse=false)或逆变换(inverse=true)。
+// 返回 false 表示 data 不是该描述表下结构合法的 HBC(或描述表本身非法),
+// 此时 data 未被修改。
+bool TransformHbcInPlace(
+    uint8_t* data,
+    size_t size,
+    const HbcLayoutDesc& layout,
+    bool inverse);
+
+} // namespace hbc
+} // namespace pushy