feat: HBC transform (hdiffv2) support in the patch core + capability reporting

Patch core:
- hbc_transform.{h,cpp}: generic interpreter applying the delta-friendly
  reversible transform to Hermes bytecode offset tables. Layout
  descriptors arrive as untrusted wire metadata; every section bound,
  entry size and bit range is validated before any byte is written
- hbc_transform_wire.{h,cpp}: strict parser for the __diff.json
  hbcTransform metadata (v / hbcVersion / layout), depth- and
  size-capped, unknown keys skipped for forward compatibility
- ApplyPatchFromFileSource: when bundle_hbc_transform_meta is present,
  apply T(origin) -> hpatch -> T-inverse with temp-file cleanup;
  unparseable metadata or an unsupported transform version fails fast so
  callers fall back to the full package. Metadata absent = legacy path,
  byte-for-byte unchanged

Platforms:
- capability constant hbcTransformVersion exported from all three
  natives (Android JNI via NativeUpdateCore, iOS constantsToExport,
  HarmonyOS napi + getConstants); JS reports it as hbcT in checkUpdate
  so the server can gate the hdiffv2 track by actual capability
- metadata threaded from __diff.json to the native patch call on
  Android (DownloadTask + JNI signature), iOS (RCTPushy.mm) and
  HarmonyOS (DownloadTask.ts + napi); build manifests updated
  (Android.mk / podspec / harmony CMakeLists)

Tests: hbc_transform_test golden-compares against the CLI's JS reference
implementation (real v96 + both v98 header variants) and fuzzes
malformed descriptors; patch_core_test adds end-to-end transformed-patch
apply and bad-metadata rejection. All pass under ASan+UBSan.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sunnylqm

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 \

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

@@ -53,6 +53,17 @@ private static final class PatchArchiveContents {
         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
@@ -251,6 +262,7 @@ private PatchArchiveContents extractPatchArchive(File archiveFile, File unzipDir
                         contents.deletes,
                         contents.copyCrcs
                     );
+                    contents.hbcTransform = manifest.optJSONObject("hbcTransform");
                     continue;
                 }
 
@@ -311,7 +323,8 @@ private void doPatchFromApk() throws IOException, JSONException {
                 false,
                 new String[0],
                 new String[0],
-                new String[0]
+                new String[0],
+                contents.hbcTransformMetaFor("index.bundlejs.patch")
             );
         } finally {
             originBundleFile.delete();
@@ -345,7 +358,8 @@ private void doPatchFromPpk() throws IOException, JSONException {
             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();
@@ -444,7 +458,8 @@ private static native void applyPatchFromFileSource(
         boolean enableMerge,
         String[] copyFroms,
         String[] copyTos,
-        String[] deletes
+        String[] deletes,
+        String hbcTransformMeta
     );
 
     private static native void cleanupOldEntries(

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

@@ -23,4 +23,15 @@ static synchronized void ensureLoaded() {
 
         loaded = true;
     }
+
+    /**
+     * 原生 patch 内核支持的 HBC 变换规范版本(hdiffv2 能力特征)。
+     * 经 getConstants 暴露给 JS,再随 checkUpdate 上报,服务端按能力门控。
+     */
+    static int hbcTransformVersion() {
+        ensureLoaded();
+        return getHbcTransformVersion();
+    }
+
+    private static native int getHbcTransformVersion();
 }

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

@@ -35,6 +35,7 @@ static Map<String, Object> getConstants(UpdateContext updateContext) {
         }
 
         constants.put("uuid", updateContext.getKv("uuid"));
+        constants.put("hbcTransformVersion", NativeUpdateCore.hbcTransformVersion());
         return constants;
     }
 

cpp/patch_core/hbc_transform.cpp

@@ -0,0 +1,143 @@
+#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];
+      if (field.bits < 1 || field.bits > 32 || 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

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